워크로드 엔드포인트

원문 보기 위키 갱신 2026.10.11

Calico Open Source의 WorkloadEndpoint 리소스에 대한 참조 문서예요. 파드나 VM 인터페이스를 나타내며, 정책 적용과 IPAM의 기준이 되는 리소스예요. YAML 예제와 각 필드의 정의를 필드별 표로 정리했어요.

출처: 문서

본문

워크로드 엔드포인트 리소스(WorkloadEndpoint)는 Calico 네트워크에 연결된 컨테이너나 VM을 호스트에 연결하는 인터페이스를 나타내요.

각 엔드포인트는 레이블 집합과 프로필 목록을 지정할 수 있고, Calico는 이를 사용해 해당 인터페이스에 정책을 적용해요.

워크로드 엔드포인트는 네임스페이스가 있는 리소스예요. 즉, 특정 네임스페이스의 NetworkPolicy는 그 네임스페이스의 WorkloadEndpoint에만 적용돼요. 두 리소스의 namespace 값이 같으면 같은 네임스페이스에 속한 거예요.

SECONDARY: calicoctl은 사용자가 워크로드 엔드포인트 리소스를 완전히 관리할 수 있게 해 주지만, 이 리소스의 라이프사이클은 보통 Calico CNI 플러그인, Calico Docker 네트워크 플러그인, Calico OpenStack Neutron 드라이버 같은 오케스트레이터 전용 플러그인이 처리해요. 일반적으로 calicoctl은 이 리소스 타입을 조회할 때만 사용하는 것을 권장해요.

YAML 예제

apiVersion: projectcalico.org/v3
kind: WorkloadEndpoint
metadata:
  name: node1-k8s-my--nginx--b1337a-eth0
  namespace: default
  labels:
    app: frontend
    projectcalico.org/namespace: default
    projectcalico.org/orchestrator: k8s
spec:
  node: node1
  orchestrator: k8s
  endpoint: eth0
  containerID: 1337495556942031415926535
  pod: my-nginx-b1337a
  endpoint: eth0
  interfaceName: cali0ef24ba
  mac: ca:fe:1d:52:bb:e9
  ipNetworks:
  - 192.168.0.0/32
  profiles:
  - profile1
  ports:
  - name: some-port
    port: 1234
    protocol: TCP
  - name: another-port
    port: 5432
    protocol: UDP

정의

Metadata

필드	설명	허용 값	스키마	기본값
name	이 워크로드 엔드포인트 리소스의 이름이에요. 필수예요.	`.`, `_`, `-`를 포함할 수 있는 영숫자 문자열	string
namespace	namespace는 리소스 이름에 추가 한정자를 제공해요.		string	"default"
labels	이 엔드포인트에 적용할 레이블 집합이에요.		map

Spec

필드	설명	스키마
workload	이 엔드포인트가 속한 워크로드의 이름이에요.	string
orchestrator	이 엔드포인트를 만든 오케스트레이터예요.	string
node	이 엔드포인트가 있는 노드예요.	string
containerID	워크로드 엔드포인트의 CNI CONTAINER_ID예요.	string
pod	이 워크로드 엔드포인트의 Kubernetes 파드 이름이에요.	string
endpoint	컨테이너 네트워크 인터페이스 이름이에요.	string
ipNetworks	인터페이스에 할당된 CIDR들이에요.	문자열 목록
ipNATs	이 엔드포인트에 적용할 1:1 NAT 매핑 목록이에요.	IPNATs 목록
ipv4Gateway	워크로드에서 나가는 트래픽의 게이트웨이 IPv4 주소예요.	string
ipv6Gateway	워크로드에서 나가는 트래픽의 게이트웨이 IPv6 주소예요.	string
profiles	이 엔드포인트에 할당된 프로필 목록이에요.	문자열 목록
interfaceName	워크로드에 붙은 호스트 측 인터페이스의 이름이에요.	string
mac	워크로드가 만들어 내는 트래픽의 소스 MAC 주소예요.	IEEE 802 MAC-48, EUI-48 또는 EUI-64
ports	이 워크로드가 노출하는 네임드 포트 목록이에요.	WorkloadEndpointPorts 목록

IPNAT

IPNAT는 WorkloadEndpoint 리소스의 단일 NAT 매핑을 담고 있어요.

필드	설명	허용 값	스키마	기본값
internalIP	NAT 매핑의 내부 IP 주소예요.	유효한 IP 주소	string
externalIP	외부 IP 주소예요.	유효한 IP 주소	string

EndpointPort

WorkloadEndpointPort는 이름을 엔드포인트의 특정 TCP/UDP/SCTP 포트와 연결해서, 정책 규칙에서 네임드 포트로 참조할 수 있게 해 줘요.

필드	설명	허용 값	스키마
name	이 포트에 붙일 이름이에요. 정책 규칙에서 참조할 수 있게 해 줘요. 이름은 엔드포인트 안에서 유일해야 해요.		string
protocol	이 네임드 포트의 프로토콜이에요.	`TCP`, `UDP`, `SCTP`	string
port	워크로드 포트 번호예요.	`1`-`65535`	int
hostPort	이 포트로 포워딩되는 호스트의 포트예요.	`1`-`65535`	int
hostIP	hostPort에 접근할 수 있는 호스트의 IP 주소예요.	`1`-`65535`	int

SECONDARY: WorkloadEndpointPort 항목 자체는 포트의 연결성에 어떤 변화도 만들지 않아요. 정책에서 참조될 때만 효과가 있어요.

SECONDARY: hostPort와 hostIP 필드는 읽기 전용이고, Kubernetes hostPort 구성에서 결정돼요. 이 필드들은 Calico에서 호스트 포트가 활성화된 경우에만 사용돼요.

더 알아보기 (Learn more)

WorkloadEndpoint는 파드/VM 인터페이스를 나타내는 네임스페이스 리소스예요. 라이프사이클은 보통 CNI 플러그인 같은 오케스트레이터가 관리하니, calicoctl로는 조회 용도로만 쓰는 걸 권장해요. 정책에서 네임드 포트를 쓰려면 EndpointPort를 활용해 보세요.