calico/node 구성하기
calico/node 컨테이너는 모든 노드에 배포되어 Felix, BIRD, confd 세 가지 데몬을 실행해요. 이 문서는 환경 변수로 calico/node를 설정하는 방법과 주요 옵션을 정리한 레퍼런스예요. 매니페스트 기반 설치에서는 주로 환경 변수를 쓰고, Node 커스텀 리소스나 Operator로도 설정할 수 있어요.
출처: 문서
본문
calico/node 컨테이너는 모든 노드에 배포되고(쿠버네티스에서는 DaemonSet으로 배포해요), 세 가지 내부 데몬을 실행해요:
- Felix: 모든 노드에서 실행되며 엔드포인트를 제공하는 Calico 데몬이에요.
- BIRD: 라우팅 정보를 다른 노드에 전파하는 BGP 데몬이에요.
- confd: Calico 데이터스토어의 설정 변경을 감시하고 BIRD 설정 파일을 갱신하는 데몬이에요.
매니페스트 기반 설치에서는 calico/node를 주로 환경 변수로 설정해요. 보통 배포 매니페스트에 환경 변수를 지정하죠. 개별 노드는 Node 커스텀 리소스로 업데이트할 수도 있고, calico/node를 Calico Operator로 설정할 수도 있어요.
이 페이지의 나머지 부분에서는 사용할 수 있는 설정 옵션을 나열하고, 이어서 여러 설정별로 주의할 점을 다뤄요.
Tab: Operator
Operator가 설치하는 경우 calico/node를 직접 설정할 필요가 없어요. Operator 설정 전체 레퍼런스는 설치 API 레퍼런스 문서를 참고해 주세요.
Tab: Manifest
환경 변수
기본 IP 풀 구성하기
Calico는 IP 풀을 사용해 pod에 주소를 할당하는 방법과, 특정 주소 집합에 네트워킹이 동작하는 방식을 설정해요. IP 풀의 전체 스키마는 이 페이지의 IP 풀 스키마 문서에서 확인할 수 있어요.
calico/node가 기본 IP 풀을 대신 만들도록 설정할 수도 있지만, 클러스터에 이미 풀이 하나도 없을 때만 가능해요. 다음 옵션들이 생성되는 풀의 파라미터를 제어해요.
| Environment | Description | Schema |
|---|---|---|
| CALICO_IPV4POOL_CIDR | The IPv4 Pool to create if none exists at start up. It is invalid to define this variable and NO_DEFAULT_POOLS. [Default: First not used in locally of (192.168.0.0/16, 172.16.0.0/16, .., 172.31.0.0/16) ] | IPv4 CIDR |
| CALICO_IPV4POOL_BLOCK_SIZE | Block size to use for the IPv4 Pool created at startup. Block size for IPv4 should be in the range 20-32 (inclusive) [Default: 26] |
int |
| CALICO_IPV4POOL_IPIP | IPIP Mode to use for the IPv4 Pool created at start up. If set to a value other than Never, CALICO_IPV4POOL_VXLAN should not be set. [Default: Always] |
Always, CrossSubnet, Never ("Off" is also accepted as a synonym for "Never") |
| CALICO_IPV4POOL_VXLAN | VXLAN Mode to use for the IPv4 Pool created at start up. If set to a value other than Never, CALICO_IPV4POOL_IPIP should not be set. [Default: Never] |
Always, CrossSubnet, Never |
| CALICO_IPV4POOL_NAT_OUTGOING | Controls NAT Outgoing for the IPv4 Pool created at start up. [Default: true] |
boolean |
| CALICO_IPV4POOL_NODE_SELECTOR | Controls the NodeSelector for the IPv4 Pool created at start up. [Default: all()] |
selector |
| CALICO_IPV6POOL_CIDR | The IPv6 Pool to create if none exists at start up. It is invalid to define this variable and NO_DEFAULT_POOLS. [Default: <a randomly chosen /48 ULA>] |
IPv6 CIDR |
| CALICO_IPV6POOL_BLOCK_SIZE | Block size to use for the IPv6 POOL created at startup. Block size for IPv6 should be in the range 116-128 (inclusive) [Default: 122] |
int |
| CALICO_IPV6POOL_VXLAN | VXLAN Mode to use for the IPv6 Pool created at start up. [Default: Never] |
Always, CrossSubnet, Never |
| CALICO_IPV6POOL_NAT_OUTGOING | Controls NAT Outgoing for the IPv6 Pool created at start up. [Default: false] |
boolean |
| CALICO_IPV6POOL_NODE_SELECTOR | Controls the NodeSelector for the IPv6 Pool created at start up. [Default: all()] |
selector |
| CALICO_IPV4POOL_DISABLE_BGP_EXPORT | Disable exporting routes over BGP for the IPv4 Pool created at start up. [Default: false] |
boolean |
| CALICO_IPV6POOL_DISABLE_BGP_EXPORT | Disable exporting routes over BGP for the IPv6 Pool created at start up. [Default: false] |
boolean |
| NO_DEFAULT_POOLS | Prevents Calico from creating a default pool if one does not exist. [Default: false] |
boolean |
BGP 네트워킹 구성하기
Calico 노드의 BGP 설정은 보통 Node, BGPConfiguration, BGPPeer 리소스로 구성해요. calico/node도 이 객체들의 특정 필드를 설정할 수 있는 옵션을 몇 가지 노출하는데, 아래에서 설명해요.
| Environment | Description | Schema |
|---|---|---|
| NODENAME | A unique identifier for this host. See node name determination for more details. | lowercase string |
| IP | The IPv4 address to assign this host or detection behavior at startup. Refer to IP setting for the details of the behavior possible with this field. | IPv4 |
| IP6 | The IPv6 address to assign this host or detection behavior at startup. Refer to IP setting for the details of the behavior possible with this field. | IPv6 |
| IP_AUTODETECTION_METHOD | The method to use to autodetect the IPv4 address for this host. This is only used when the IPv4 address is being autodetected. See IP Autodetection methods for details of the valid methods. [Default: first-found] |
string |
| IP6_AUTODETECTION_METHOD | The method to use to autodetect the IPv6 address for this host. This is only used when the IPv6 address is being autodetected. See IP Autodetection methods for details of the valid methods. [Default: first-found] |
string |
| AS | The AS number for this node. When specified, the value is saved in the node resource configuration for this host, overriding any previously configured value. When omitted, if an AS number has been previously configured in the node resource, that AS number is used for the peering. When omitted, if an AS number has not yet been configured in the node resource, the node will use the global value (see example modifying Global BGP settings for details.) | int |
| CALICO_ROUTER_ID | Sets the router id to use for BGP if no IPv4 address is set on the node. For an IPv6-only system, this may be set to hash. It then uses the hash of the nodename to create a 4 byte router id. See note below. [Default: ``] |
string |
| CALICO_K8S_NODE_REF | The name of the corresponding node object in the Kubernetes API. When set, used for correlating this node with events from the Kubernetes API. | string |
데이터스토어 접근 구성하기
| Environment | Description | Schema |
|---|---|---|
| DATASTORE_TYPE | Type of datastore. [Default: kubernetes] |
kubernetes, etcdv3 |
쿠버네티스 데이터스토어 접근 구성하기
| Environment | Description | Schema |
|---|---|---|
| KUBECONFIG | When using the Kubernetes datastore, the location of a kubeconfig file to use. | string |
| K8S_API_ENDPOINT | Location of the Kubernetes API. Not required if using kubeconfig. | string |
| K8S_CERT_FILE | Location of a client certificate for accessing the Kubernetes API. | string |
| K8S_KEY_FILE | Location of a client key for accessing the Kubernetes API. | string |
| K8S_CA_FILE | Location of a CA for accessing the Kubernetes API. | string |
SECONDARY: Calico가 쿠버네티스 API를 데이터스토어로 사용하도록 설정되면, BGP 구성에 쓰이는 환경 변수들은 무시돼요. 노드 AS 번호 선택(AS)과 모든 IP 선택 옵션(IP, IP6, IP_AUTODETECTION_METHOD, IP6_AUTODETECTION_METHOD)도 여기에 포함돼요.
etcd 데이터스토어 접근 구성하기
| Environment | Description | Schema |
|---|---|---|
| ETCD_ENDPOINTS | A comma separated list of etcd endpoints [Example: http://127.0.0.1:2379,http://127.0.0.2:2379] (required) |
string |
| ETCD_DISCOVERY_SRV | Domain name to discover etcd endpoints via SRV records. Mutually exclusive with ETCD_ENDPOINTS. [Example: example.com] (optional) |
string |
| ETCD_KEY_FILE | Path to the file containing the private key matching the calico/node client certificate. Enables calico/node to participate in mutual TLS authentication and identify itself to the etcd server. Example: /etc/node/key.pem (optional) |
string |
| ETCD_CERT_FILE | Path to the file containing the client certificate issued to calico/node. Enables calico/node to participate in mutual TLS authentication and identify itself to the etcd server. Example: /etc/node/cert.pem (optional) |
string |
| ETCD_CA_CERT_FILE | Path to the file containing the root certificate of the certificate authority (CA) that issued the etcd server certificate. Configures calico/node to trust the CA that signed the root certificate. The file may contain multiple root certificates, causing calico/node to trust each of the CAs included. Example: /etc/node/ca.pem |
string |
로깅 구성하기
| Environment | Description | Schema |
|---|---|---|
| CALICO_DISABLE_FILE_LOGGING | Disables logging to file. [Default: "false"] | string |
| CALICO_STARTUP_LOGLEVEL | The log severity above which startup calico/node logs are sent to the stdout. [Default: ERROR] |
DEBUG, INFO, WARNING, ERROR, CRITICAL, or NONE (case-insensitive) |
CNI 플러그인 구성하기
calico/node에는 클러스터에서 사용하는 CNI 플러그인과 CNI 플러그인 구성에 따라 설정할 수 있는 옵션이 몇 가지 있어요.
| Environment | Description | Schema |
|---|---|---|
| USE_POD_CIDR | Use the Kubernetes Node.Spec.PodCIDR field when using host-local IPAM. Requires Kubernetes API datastore. This field is required when using the Kubernetes API datastore with host-local IPAM. [Default: false] |
boolean |
| CALICO_MANAGE_CNI | Tells Calico to update the kubeconfig file at /host/etc/cni/net.d/calico-kubeconfig on credentials change. [Default: true] | boolean |
기타 환경 변수
| Environment | Description | Schema |
|---|---|---|
| DISABLE_NODE_IP_CHECK | Skips checks for duplicate Node IPs. This can reduce the load on the cluster when a large number of Nodes are restarting. [Default: false] |
boolean |
| WAIT_FOR_DATASTORE | Wait for connection to datastore before starting. If a successful connection is not made, node will shutdown. [Default: false] |
boolean |
| CALICO_NETWORKING_BACKEND | The networking backend to use. In bird mode, Calico will provide BGP networking using the BIRD BGP daemon; VXLAN networking can also be used. In vxlan mode, only VXLAN networking is provided; BIRD and BGP are disabled. If set to none (also known as policy-only mode), both BIRD and VXLAN are disabled. [Default: bird] |
bird, vxlan, none |
| CLUSTER_TYPE | Contains comma delimited list of indicators about this cluster. e.g. k8s, mesos, kubeadm, canal, bgp | string |
부록
노드 이름 결정 방식
calico/node는 자신이 실행 중인 노드의 이름을 알아야 해요. 노드 이름은 이 노드에 설정된 Node 리소스가 있으면 이를 가져올 때, 없으면 노드를 나타내는 새 노드 리소스를 만들 때 사용해요. 노드별 BGP 구성, Felix 구성, 엔드포인트를 노드와 연결할 때도 쓰여요.
calico/node 컨테이너는 시작할 때 다음 우선순위대로 노드 이름을 정해요:
NODENAME환경 변수에 값이 지정돼 있으면 그 값을 사용해요./var/lib/calico/nodename파일이 존재하면 그 값을 사용해요.HOSTNAME환경 변수에 값이 지정돼 있으면 그 값을 사용해요.- 운영체제가 반환하는 호스트 이름을 소문자로 바꿔 사용해요.
노드가 이름을 정하고 나면 그 값은 이후 사용을 위해 /var/lib/calico/nodename에 캐시돼요.
예를 들어 다음 조건이 주어졌다고 해 볼게요:
NODENAME=""인 경우/var/lib/calico/nodename파일이 없는 경우HOSTNAME="host-A"인 경우- 운영체제가 호스트 이름으로 "host-A.internal.myorg.com"을 반환하는 경우
calico/node는 이름으로 "host-a"를 사용하고 그 값을 /var/lib/calico/nodename에 기록해요. 이후 calico/node를 다시 시작하면 디스크의 파일에서 읽은 캐시 값 "host-a"를 사용하죠.
IP 설정
IP(IPv4용)와 IP6(IPv6용) 환경 변수는 노드의 해당 IP 버전 주소를 지정하거나, 자동 감지를 강제하거나, 자동 감지를 비활성화하는 데 사용해요. 환경 변수를 설정하면 그 주소는 이 호스트의 노드 리소스 구성에 저장되고, 이전에 설정된 값이 있으면 덮어써요.
calico/node는 호스트에서 서브넷 정보를 감지하려 시도하고, 가능하면 제공된 주소를 이 정보로 보완해요.
IP 설정의 특수 값
IP(6) 환경 변수에 설정할 수 있는 특수 값은 다음과 같아요:
-
값을 설정하지 않거나 빈 문자열: 노드 리소스에 이전에 설정한 주소가 있으면 그 주소를 사용해요. 노드 리소스에 이전 주소가 없다면 두 버전의 동작이 달라져요:
IP는 IPv4 주소를 자동 감지해 노드 리소스에 설정해요.IP6는 자동 감지를 하지 않아요.
-
autodetect: 항상 IP 주소 자동 감지를 수행하고, 감지된 주소가 노드 리소스에 설정된 값을 덮어써요. -
none: 자동 감지를 수행하지 않아요(IPv4를 비활성화할 때 유용해요).
IP 자동 감지 방식
Calico를 라우팅에 사용할 때는 각 노드가 노드 간 라우팅에 쓸 IPv4 주소와/또는 IPv6 주소를 가져야 해요. 노드별 IP 주소 설정을 없애기 위해, calico/node 컨테이너가 이 IP 주소들을 자동 감지하도록 설정할 수 있어요. 다만 많은 시스템에서는 호스트에 물리 인터페이스가 여러 개이거나, 하나의 물리 인터페이스에 여러 IP 주소가 설정돼 있을 수 있어요. 이런 경우 선택지가 여러 개라서 올바른 주소를 자동 감지하기가 까다로워져요.
IP 자동 감지 방식은 배포 환경에 맞는 기준으로 후보를 좁혀, 올바른 주소를 더 잘 고르도록 도와줘요.
다음 절에서 사용할 수 있는 IP 자동 감지 방식들을 설명해요.
first-found
first-found 옵션은 모든 인터페이스의 IP 주소를 나열하고, 첫 번째 유효한 인터페이스에서 (IP 버전과 주소 유형을 기준으로) 첫 번째 유효한 IP 주소를 반환해요. 도커 브리지 같이 알려진 "로컬" 인터페이스 몇 가지는 제외돼요. 인터페이스와 IP 주소가 나열되는 순서는 시스템에 따라 달라져요.
이 방식이 기본 감지 방법이에요. 다만 이 방법은 아주 단순한 추측만 하기 때문에, 노드에 특정 IP 주소를 직접 설정하거나 다른 감지 방식을 사용하는 것을 권장해요.
예시:
IP_AUTODETECTION_METHOD=first-found
IP6_AUTODETECTION_METHOD=first-found
kubernetes-internal-ip
kubernetes-internal-ip 방식은 쿠버네티스 노드의 Status.Addresses 필드에 나열된 첫 번째 내부 IP 주소를 선택해요.
예시:
IP_AUTODETECTION_METHOD=kubernetes-internal-ip
IP6_AUTODETECTION_METHOD=kubernetes-internal-ip
can-reach=DESTINATION
can-reach 방식은 로컬 라우팅을 이용해, 지정한 목적지에 도달하는 데 사용될 IP 주소를 알아내요. IP 주소와 도메인 이름 모두 사용할 수 있어요.
IP 주소를 사용한 예시:
IP_AUTODETECTION_METHOD=can-reach=8.8.8.8
IP6_AUTODETECTION_METHOD=can-reach=2001:4860:4860::8888
도메인 이름을 사용한 예시:
IP_AUTODETECTION_METHOD=can-reach=www.google.com
IP6_AUTODETECTION_METHOD=can-reach=www.google.com
interface=INTERFACE-REGEX
interface 방식은 지정한 인터페이스 정규 표현식으로 일치하는 인터페이스를 찾아, 첫 번째로 일치한 인터페이스의 첫 번째 IP 주소를 반환해요. 인터페이스와 IP 주소가 나열되는 순서는 시스템에 따라 달라져요.
eth0, eth1, eth2 등의 인터페이스에 유효한 IP 주소가 있을 때의 예시:
IP_AUTODETECTION_METHOD=interface=eth.*
IP6_AUTODETECTION_METHOD=interface=eth.*
skip-interface=INTERFACE-REGEX
skip-interface 방식은 지정한 인터페이스 정규 표현식으로 인터페이스를 제외하고, 일치하지 않는 첫 번째 인터페이스의 첫 번째 IP 주소를 반환해요. 인터페이스와 IP 주소가 나열되는 순서는 시스템에 따라 달라져요.
enp6s0f0, eth0, eth1, eth2 등의 인터페이스를 제외할 때의 예시:
IP_AUTODETECTION_METHOD=skip-interface=enp6s0f0,eth.*
IP6_AUTODETECTION_METHOD=skip-interface=enp6s0f0,eth.*
cidr=CIDR
cidr 방식은 노드에서 주어진 CIDR 범위 안에 속하는 아무 IP 주소나 선택해요. 예를 들면 다음과 같아요:
예시:
IP_AUTODETECTION_METHOD=cidr=10.0.1.0/24,10.0.2.0/24
IP6_AUTODETECTION_METHOD=cidr=2001:4860::0/64
노드 준비 상태
calico/node 컨테이너는 exec 준비 상태(readiness) 엔드포인트를 지원해요.
이 엔드포인트에 접근하려면 다음 명령어를 사용해요.
docker exec calico-node /bin/calico-node [flag]
[flag] 자리에는 다음 값 중 하나 이상을 넣어 주세요.
-bird-ready-bird6-ready-felix-ready
BIRD 준비 상태 엔드포인트는 모든 BGP 피어가 established 상태이고 graceful restart가 진행 중이 아닌지 확인해 BGP 메시가 건강한지 검증해요. 클러스터에 더 이상 없는 피어에 접근할 수 없어 BIRD 준비 상태 검사가 실패한다면 노드 폐기 문서를 참고해 주세요.
IPv6 전용 시스템에서 CALICO_ROUTER_ID 설정하기
CALICO\_ROUTER\_ID를 hash로 설정하면 설정된 노드 이름의 해시를 라우터 ID로 사용해요. 이 기능은 라우터 ID로 쓸 IPv4 주소가 없는 IPv6 전용 시스템에서만 사용해야 해요. 각 노드가 자신의 라우터 ID를 독자적으로 고르기 때문에, 두 노드가 같은 ID를 골라 충돌하는 일이 생길 수도 있어요. 충돌 가능성은 클러스터가 커질수록 커지므로 노드 500개 이상인 큰 클러스터에서는 이 기능을 사용하면 안 돼요.
더 알아보기 (Learn more)
Felix 세부 설정은 Felix 구성 레퍼런스에서, IP 풀의 상세 스키마는 IPPool 리소스 문서에서 확인할 수 있어요. BGP 피어링을 다룰 때는 Node와 BGPPeer 리소스 문서도 함께 참고하면 좋아요.