Calico Kubernetes 컨트롤러 구성하기

원문 보기 위키 갱신 2026.10.12

Calico Kubernetes 컨트롤러는 Kubernetes 클러스터에 배포되어 Kubernetes API를 감시하고 클러스터 상태에 따라 동작을 수행해요. Operator 설치에서는 KubeControllersConfiguration 리소스를, 매니페스트 설치에서는 환경 변수를 주로 쓴다는 점만 구분하면 구성이 어렵지 않아요. 각 컨트롤러가 무엇을 감시하고 언제 기본으로 켜지는지도 함께 정리했어요.

출처: 문서

본문

탭: Operator

Operator로 Calico를 설치했다면 대신 KubeControllersConfiguration 리소스를 참고하세요.

탭: Manifest

컨트롤러는 주로 환경 변수로 구성해요. 컨트롤러를 Kubernetes 파드로 실행할 때는 파드 매니페스트의 env 섹션으로 설정해요.

calico-kube-controllers 컨테이너

calico-kube-controllers 컨테이너에는 다음 컨트롤러가 들어 있어요.

policy 컨트롤러: Kubernetes API에서 Kubernetes 네트워크 정책을 감시하고, 그 정책을 Calico 네트워크 정책으로 데이터스토어(etcd)에 동기화해요. 네트워크 정책을 데이터플레인에서 구현하는 건 Felix의 몫이에요.
namespace 컨트롤러: 네임스페이스를 감시하고 Calico 프로파일을 프로그래밍해요.
serviceaccount 컨트롤러: 서비스 어카운트를 감시하고 Calico 프로파일을 프로그래밍해요.
workloadendpoint 컨트롤러: 파드 라벨 변경을 감시하고 Calico 워크로드 엔드포인트를 업데이트해요.
node 컨트롤러: Kubernetes 노드의 삭제를 감시해서 Calico에서 해당 데이터를 제거하고, 노드 업데이트를 감시해서 각 노드의 호스트 엔드포인트를 생성·동기화하도록 선택적으로 설정할 수 있어요.

Calico Kubernetes 매니페스트는 이 컨트롤러들을 calico-kube-controllers 디플로이먼트의 단일 파드 안에서 실행해요.

데이터스토어 접근 구성하기

데이터스토어 타입은 DATASTORE_TYPE 환경 변수로 설정할 수 있어요. 지원 값은 etcdv3와 kubernetes예요.

etcdv3

Calico Kubernetes 컨트롤러는 etcd 접근 구성을 위해 다음 환경 변수를 지원해요.

환경 변수	설명	스키마
`ETCD_ENDPOINTS`	접속할 etcd 엔드포인트의 쉼표 구분 목록이에요. 예: `http://10.0.0.1:2379,http://10.0.0.2:2379`	string
`ETCD_DISCOVERY_SRV`	SRV 레코드로 etcd 엔드포인트를 찾을 도메인 이름이에요. `ETCD_ENDPOINTS`와 함께 쓸 수 없어요. 예: `example.com`	string
`ETCD_CA_CERT_FILE`	etcd 서버 인증서를 발급한 CA의 루트 인증서가 담긴 파일의 경로예요. Kubernetes 컨트롤러가 etcd 서버가 제공한 인증서의 서명을 신뢰하도록 설정해요. Kubernetes 컨트롤러의 서버 인증을 끄려면 값을 `none`으로 설정하세요.	path
`ETCD_CERT_FILE`	Kubernetes 컨트롤러에 발급된 클라이언트 인증서가 담긴 파일의 경로예요. Kubernetes 컨트롤러가 상호 TLS 인증에 참여해 etcd 서버에 자신을 알릴 수 있게 해줘요. 예: `/etc/kube-controllers/cert.pem`	path
`ETCD_KEY_FILE`	Kubernetes 컨트롤러의 클라이언트 인증서에 맞는 개인 키가 담긴 파일의 경로예요. Kubernetes 컨트롤러가 상호 TLS 인증에 참여해 etcd 서버에 자신을 알릴 수 있게 해줘요. 예: `/etc/kube-controllers/key.pem`	path

*_FILE 변수들은 해당 인증서/키의 경로예요. 따라서 컨트롤러를 Kubernetes 파드로 실행할 때는 그 파일들이 파드 안에 실제로 존재하도록 보장해야 해요. 보통 다음 두 방법 중 하나로 처리해요.

호스트에서 인증서를 마운트해요. 이 방법은 컨트롤러가 실행되는 호스트에 인증서가 있어야 해요.
Kubernetes Secret을 사용해 인증서를 파일로 파드에 마운트해요.

kubernetes

컨트롤러를 Kubernetes 파드로 실행할 때는 Kubernetes API 접근이 자동으로 구성되기 때문에 추가 구성이 필요 없어요. 다만 필요하면 명시적인 kubeconfig 파일 오버라이드로 API 접근을 구성할 수도 있어요.

환경 변수	설명	스키마
`KUBECONFIG`	컨테이너 안에 마운트된 Kubernetes kubeconfig 파일의 경로예요.	path

기타 구성

SECONDARY: 가능하면 환경 변수 대신 KubeControllersConfiguration API 리소스로 kube-controllers 컴포넌트를 구성하세요. 일부 구성 옵션은 환경 변수로는 사용할 수 없어요.

다음 환경 변수로 Calico Kubernetes 컨트롤러를 구성할 수 있어요.

환경 변수	설명	스키마	기본값
`DATASTORE_TYPE`	사용할 데이터스토어 타입	etcdv3, kubernetes	kubernetes
`ENABLED_CONTROLLERS`	실행할 컨트롤러	namespace, node, policy, serviceaccount, workloadendpoint	policy,namespace,serviceaccount,workloadendpoint,node
`LOG_LEVEL`	표시할 최소 로그 레벨	debug, info, warning, error	info
`KUBECONFIG`	Kubernetes API 접근에 쓸 kubeconfig 파일의 경로	path
`SYNC_NODE_LABELS`	켜면 Kubernetes 노드 라벨이 Calico 노드 객체로 복사돼요.	boolean	true
`AUTO_HOST_ENDPOINTS`	enabled로 설정하면 각 노드의 호스트 엔드포인트를 자동 생성해요.	enabled, disabled	disabled
`COMPACTION_PERIOD`	이 주기로 etcd 데이터베이스를 컴팩트해요. "0"으로 설정하면 꺼져요.	duration	10m

각 컨트롤러 알아보기

Node 컨트롤러

Node 컨트롤러는 사용 중인 데이터스토어에 따라 여러 기능을 수행해요.

두 데이터스토어 모두

IP 주소를 가비지 컬렉트해요.
Kubernetes 노드의 호스트 엔드포인트를 자동으로 프로비저닝해요.

etcdv3 전용

Kubernetes 노드가 삭제되면 projectcalico.org/v3 Node 리소스를 가비지 컬렉트해요.
Kubernetes와 Calico Node 리소스 사이에서 라벨을 동기화해요.

ENABLED_CONTROLLERS를 명시하지 않으면 Node 컨트롤러는 기본으로 켜지지 않아요. 하지만 Calico Kubernetes 매니페스트는 ENABLED_CONTROLLERS를 명시하기 때문에 calico-kube-controllers 디플로이먼트 안에서 이 컨트롤러가 켜져요.

이 컨트롤러는 etcdv3와 kubernetes 데이터스토어 타입 어느 쪽에서도 유효해요.

etcdv3

etcdv3를 사용할 때 Node 컨트롤러를 켜려면 다음 두 단계를 수행하세요.

KubeControllersConfiguration에서 컨트롤러를 켜거나, kube-controllers 환경의 활성 컨트롤러 목록에 "node"를 추가하세요. 예: ENABLED_CONTROLLERS=workloadendpoint,profile,policy,node
calico-node 데몬셋의 environment 섹션에 다음 스니펫을 추가해서 calico/node에 Kubernetes 노드 참조를 구성하세요.
```
- name: CALICO_K8S_NODE_REF
  valueFrom:
    fieldRef:
      fieldPath: spec.nodeName
```

SYNC_NODE_LABELS를 true로 설정하면(기본으로 켜져 있어요) Kubernetes 노드 리소스의 라벨이 대응하는 Calico 노드 리소스의 라벨과 동기화 상태로 유지돼요. 두 노드 리소스가 같은 라벨을 다른 값으로 지정하면 Kubernetes 노드 리소스가 우선해요. Kubernetes 노드에 없는 Calico 리소스의 라벨은 그대로 남아요.

kubernetes

kubernetes를 사용할 때 Node 컨트롤러를 켜려면 KubeControllersConfiguration에서 컨트롤러를 켜거나, kube-controllers 환경의 활성 컨트롤러 목록을 node로 설정하세요. 예: ENABLED_CONTROLLERS=node

Policy 컨트롤러

Policy 컨트롤러는 Kubernetes 네트워크 정책을 Calico 데이터스토어로 동기화해요. NetworkPolicy 이벤트를 감시하려면 이 컨트롤러가 Kubernetes API 읽기 권한을 갖고 있어야 해요.

ENABLED_CONTROLLERS를 명시하지 않으면 Policy 컨트롤러는 기본으로 켜져요.

이 컨트롤러는 Calico 데이터스토어로 etcd를 사용할 때만 유효해요.

Workload endpoint 컨트롤러

Workload endpoint 컨트롤러는 Kubernetes 파드 라벨 변경을 대응하는 워크로드 엔드포인트 업데이트로 자동 동기화해요. Pod 이벤트를 감시하려면 이 컨트롤러가 Kubernetes API 읽기 권한을 갖고 있어야 해요.

ENABLED_CONTROLLERS를 명시하지 않으면 Workload endpoint 컨트롤러는 기본으로 켜져요.

이 컨트롤러는 Calico 데이터스토어로 etcd를 사용할 때만 유효해요.

Namespace 컨트롤러

Namespace 컨트롤러는 Kubernetes 네임스페이스 라벨 변경을 Calico 데이터스토어로 동기화해요. Namespace 이벤트를 감시하려면 이 컨트롤러가 Kubernetes API 읽기 권한을 갖고 있어야 해요.

ENABLED_CONTROLLERS를 명시하지 않으면 Namespace 컨트롤러는 기본으로 켜져요.

이 컨트롤러는 Calico 데이터스토어로 etcd를 사용할 때만 유효해요.

Service account 컨트롤러

Service account 컨트롤러는 Kubernetes 서비스 어카운트 변경을 Calico 데이터스토어로 동기화해요. ServiceAccount 이벤트를 감시하려면 이 컨트롤러가 Kubernetes API 읽기 권한을 갖고 있어야 해요.

ENABLED_CONTROLLERS를 명시하지 않으면 Service account 컨트롤러는 기본으로 켜져요.

이 컨트롤러는 Calico 데이터스토어로 etcd를 사용할 때만 유효해요.

더 알아보기 (Learn more)

Operator 설치라면 환경 변수보다 KubeControllersConfiguration 리소스가 정답이라는 점만 기억하면 돼요. 매니페스트 설치에서는 ENABLED_CONTROLLERS로 컨트롤러를 골라 켜고, etcd 데이터스토어용 인증서 파일이 파드 안에 실제로 마운트되어 있는지 꼭 확인하세요. 각 컨트롤러의 기본 동작 여부는 ENABLED_CONTROLLERS 명시 여부에 따라 달라진다는 것도 유의하세요.