호스트 엔드포인트 오브젝트 만들기

원문 보기 위키 갱신 2026.10.11

Calico가 호스트 네트워크 인터페이스를 보호하게 하려면 etcd에 호스트 엔드포인트 오브젝트를 만들어야 해요. 이 문서는 HostEndpoint 리소스의 작성 방법과 인터페이스 지정 방식, 자주 만나는 검증 오류를 다뤄요. calicoctl create 명령으로 호스트 엔드포인트 리소스(HostEndpoint)를 만들 수 있어요.

출처: 문서

본문

Calico가 보호하기 원하는 각 호스트 엔드포인트에 대해, etcd에 호스트 엔드포인트 오브젝트를 만들어야 해요. calicoctl create 명령으로 호스트 엔드포인트 리소스(HostEndpoint)를 만드세요.

호스트 엔드포인트가 참조할 인터페이스를 지정하는 방법은 두 가지예요. 인터페이스 이름을 지정하거나, 인터페이스의 예상 IP 주소를 지정할 수 있어요. 어느 쪽이든 인터페이스를 소유한 호스트에서 실행 중인 Calico 노드의 이름도 알아야 해요; 대부분의 경우 이는 호스트의 호스트명과 같아요.

예를 들어 my-host 호스트에서 IP 10.0.0.1을 가진 eth0 인터페이스를 보호하려면 아래 명령을 실행해요. 엔드포인트 이름은 엔드포인트 식별에 필요한 임의의 이름이에요.

이 명령을 실행할 때는 꺾쇠 괄호로 된 자리표시자를 여러분 배포에 맞는 값으로 바꾸세요.

calicoctl create -f - <<EOF
- apiVersion: projectcalico.org/v3
  kind: HostEndpoint
  metadata:
    name: <name of endpoint>
    labels:
      role: webserver
      environment: production
  spec:
    interfaceName: eth0
    node: <node name or hostname>
    profiles: [<list of profile IDs>]
    expectedIPs: ["10.0.0.1"]
EOF

참고: Felix는 시스템의 올바른 호스트명을 감지하려고 해요. 시작 시점에 판단한 값을 다음 형식으로 로그에 남겨요: 2015-10-20 17:42:09,813 \[INFO\]\[30149/5\] calico.felix.config 285: Parameter FelixHostname (Felix compute host hostname) has value 'my-hostname' read from None 이 값(여기서는 'my-hostname')은 etcd에서 사용하는 호스트명과 일치해야 해요. 이상적으로는 호스트의 시스템 호스트명을 올바르게 설정하는 게 좋지만, 그게 불가능하다면 FelixHostname 설정값으로 Felix 값을 덮어쓸 수 있어요. 자세한 내용은 configuration 문서를 참고하세요.

<list of profile IDs>는 엔드포인트에 적용할 보안 프로필의 선택적 목록이고, labels에는 셀렉터 표현식에서 사용할 수 있는 임의의 키/값 쌍들이 들어가요.

참고: 다른 호스트에서 보안 규칙을 렌더링할 때, Calico는 레이블 셀렉터를 IP 주소로 해석하기 위해 expectedIPs 필드를 사용해요. expectedIPs 필드가 생략되면 레이블을 사용하는 보안 규칙은 이 엔드포인트와 매칭에 실패해요. 또는, IP 주소가 10.0.0.1일 것이라는 건 알지만 인터페이스 이름은 모른다면:

calicoctl create -f - <<EOF
- apiVersion: projectcalico.org/v3
  kind: HostEndpoint
  metadata:
    name: <name of endpoint>
    labels:
      role: webserver
      environment: production
  spec:
    node: <node name or hostname>
    profiles: [<list of profile IDs>]
    expectedIPs: ["10.0.0.1"]
EOF

호스트 엔드포인트 오브젝트를 만들고 나면 Felix가 해당 인터페이스의 트래픽을 감시하기 시작해요. 정책이나 프로필이 하나도 없다면, 인터페이스에서 트래픽이 드랍되는 걸 볼 거예요.

참고: 기본적으로 Calico에는 ssh 같은 특정 트래픽을 허용하는 failsafe가 들어 있어요. failsafe 규칙을 비활성화하거나 설정하는 방법은 아래에서 더 자세히 다뤄요.

트래픽이 드랍되는 게 보이지 않는다면, 설정에서 호스트명, IP 주소, (사용했다면) 인터페이스 이름을 확인하세요. 엔드포인트 데이터에 문제가 있었다면 Felix가 WARNING 수준으로 검증 오류를 로그에 남기고 해당 엔드포인트를 무시해요:

Felix 로그에서 "Validation failed" 문자열을 grep하면 오류를 찾을 수 있어요.

grep "Validation failed" /var/log/calico/felix.log

오류 예시는 다음과 같아요.

2016-05-31 12:16:21,651 [WARNING][8657/3] calico.felix.fetcd 1017:
    Validation failed for host endpoint HostEndpointId<eth0>, treating as
    missing: 'name' or 'expected_ipvX_addrs' must be present.;
    '{ "labels": {"foo": "bar"}, "profile_ids": ["prof1"]}'

오류 메시지는 꽤 길 수 있지만 거부된 정확한 원인을 로그에 남겨요; 이 경우 'name' or 'expected\_ipvX\_addrs' must be present가 인터페이스의 이름 또는 예상 IP 주소 중 하나는 반드시 지정해야 한다는 뜻이라고 알려 줘요.

더 알아보기 (Learn more)

호스트 엔드포인트는 인터페이스 이름 또는 예상 IP로 지정할 수 있지만, 레이블 기반 정책 매칭에는 expectedIPs가 꼭 필요해요. 생성 직후 트래픽이 드랍되는지 확인하면 설정이 맞았는지 빠르게 판별할 수 있어요. 검증 오류는 Felix 로그의 "Validation failed" 문자열로 추적하세요.