calicoctl을 etcd 데이터스토어에 연결하도록 구성하기

원문 보기 위키 갱신 2026.10.12

calicoctl CLI 도구를 etcd 클러스터에 연결하도록 구성하는 방법을 다뤄요. 구성 파일 옵션과 환경 변수, TLS 인증서 설정, IPv6/혼합 환경 예제까지 정리되어 있어요. etcd 데이터스토어를 쓰는 Calico 클러스터를 운영한다면 이 문서의 구성 파일 샘플이 바로 출발점이 될 거예요.

출처: 문서

본문

큰 그림

etcd 클러스터를 위한 calicoctl CLI 도구 구성 방법을 배워요.

가치

calicoctl CLI 도구는 Calico 클러스터와 상호작용할 수 있는 유용한 관리 명령을 제공해요.

개념

calicoctl vs kubectl

이전 릴리스에서는 projectcalico.org/v3 API 그룹의 Calico API 리소스를 관리하려면 calicoctl이 필요했어요. calicoctl CLI 도구는 이 API들에 중요한 검증과 기본값 채우기를 제공해요.

최신 릴리스에서는 Calico API 서버가 그 기본값 채우기와 검증을 서버 측에서 수행해서, calicoctl 의존성 없이 같은 API 의미 체계를 제공해요. 그래서 대부분의 작업에는 calicoctl 대신 Calico API 서버를 설치하고 kubectl을 쓰기를 권장해요.

다음 하위 커맨드에서는 여전히 calicoctl이 필요해요.

OpenStack 같은 비(非)Kubernetes 플랫폼에서도 calicoctl이 필요해요.

방법

etcd 구성 옵션 전체 목록

구성 파일 옵션	환경 변수	설명	스키마
`datastoreType`	`DATASTORE_TYPE`	사용할 데이터스토어를 나타내요. 지정하지 않으면 `kubernetes`가 기본이에요. (선택 사항)	`kubernetes`, `etcdv3`
`etcdEndpoints`	`ETCD_ENDPOINTS`	etcd 엔드포인트의 쉼표 구분 목록이에요. 예: `http://127.0.0.1:2379,http://127.0.0.2:2379` (필수)	string
`etcdDiscoverySrv`	`ETCD_DISCOVERY_SRV`	SRV 레코드로 etcd 엔드포인트를 찾을 도메인 이름이에요. `etcdEndpoints`와 함께 쓸 수 없어요. 예: `example.com` (선택 사항)	string
`etcdUsername`	`ETCD_USERNAME`	RBAC용 사용자 이름이에요. 예: `user` (선택 사항)	string
`etcdPassword`	`ETCD_PASSWORD`	지정한 사용자 이름의 비밀번호예요. 예: `password` (선택 사항)	string
`etcdKeyFile`	`ETCD_KEY_FILE`	`calicoctl` 클라이언트 인증서와 맞는 개인 키가 담긴 파일의 경로예요. `calicoctl`이 상호 TLS 인증에 참여해 etcd 서버에 자신을 알릴 수 있게 해줘요. 예: `/etc/calicoctl/key.pem` (선택 사항)	string
`etcdCertFile`	`ETCD_CERT_FILE`	`calicoctl`에 발급된 클라이언트 인증서가 담긴 파일의 경로예요. `calicoctl`이 상호 TLS 인증에 참여해 etcd 서버에 자신을 알릴 수 있게 해줘요. 예: `/etc/calicoctl/cert.pem` (선택 사항)	string
`etcdCACertFile`	`ETCD_CA_CERT_FILE`	etcd 서버 인증서를 발급한 인증 기관(CA)의 루트 인증서가 담긴 파일의 경로예요. `calicoctl`이 루트 인증서에 서명한 CA를 신뢰하도록 설정해요. 이 파일에는 루트 인증서가 여러 개 들어갈 수 있어서, 포함된 각 CA를 모두 신뢰하게 돼요. 예: `/etc/calicoctl/ca.pem` (선택 사항)	string
`etcdKey`		`calicoctl` 클라이언트 인증서와 맞는 개인 키예요. `calicoctl`이 상호 TLS 인증에 참여해 etcd 서버에 자신을 알릴 수 있게 해줘요. 예시는 아래를 참고하세요.(선택 사항)	string
`etcdCert`		`calicoctl`에 발급된 클라이언트 인증서예요. `calicoctl`이 상호 TLS 인증에 참여해 etcd 서버에 자신을 알릴 수 있게 해줘요. 예시는 아래를 참고하세요.(선택 사항)	string
`etcdCACert`		etcd 서버 인증서를 발급한 인증 기관(CA)의 루트 인증서예요. `calicoctl`이 루트 인증서에 서명한 CA를 신뢰하도록 설정해요. 구성 파일에는 루트 인증서가 여러 개 들어갈 수 있어서, 포함된 각 CA를 모두 신뢰하게 돼요. 예시는 아래를 참고하세요.(선택 사항)	string

SECONDARY:

TLS가 켜진 상태로 실행한다면 엔드포인트 주소가 HTTPS를 쓰는지 확인하세요.

환경 변수로 지정할 때는 etcdv3에 DATASTORE_TYPE 환경 변수가 필수예요.

모든 환경 변수는 CALICO_ 접두어도 붙일 수 있어요. 예를 들어 CALICO_DATASTORE_TYPE, CALICO_ETCD_ENDPOINTS 등을 쓸 수 있어요. 접두어 없는 이름이 시스템에 이미 정의된 환경 변수와 충돌할 때 유용해요.

구성 파일 옵션 etcdCACert, etcdCert, etcdKey에는 대응하는 환경 변수가 없어요.

이전 버전의 calicoctl은 etcd 엔드포인트를 지정하는 수단으로 ETCD_SCHEME과 ETC_AUTHORITY 환경 변수를 지원했어요. 이 변수들은 더 이상 지원되지 않으니 대신 ETCD_ENDPOINTS를 사용하세요.

구성 파일 예제

apiVersion: projectcalico.org/v3
kind: CalicoAPIConfig
metadata:
spec:
  etcdEndpoints: https://etcd1:2379,https://etcd2:2379,https://etcd3:2379
  etcdKeyFile: /etc/calico/key.pem
  etcdCertFile: /etc/calico/cert.pem
  etcdCACertFile: /etc/calico/ca.pem

인라인 CA 인증서, 클라이언트 인증서, 키가 들어간 구성 파일 예제

apiVersion: projectcalico.org/v3
kind: CalicoAPIConfig
metadata:
spec:
  datastoreType: etcdv3
  etcdEndpoints: 'https://127.0.0.1:2379'
  etcdCACert: |
    -----BEGIN CERTIFICATE-----
    MIICKzCCAZSgAwIBAgIBAzANBgkqhkiG9w0BAQQFADA3MQswCQYDVQQGEwJVUzER
    MA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncyBDQTAeFw05NzEw
    MTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBgNVBAYTAlVTMREwDwYDVQQK
    EwhOZXRzY2FwZTENMAsGA1UECxMEUHViczEXMBUGA==
    -----END CERTIFICATE-----
  etcdCert: |
    -----BEGIN CERTIFICATE-----
    gI6iLXgMsp2EOlD56I6FA1jrCtNb01XQvX3eyFuA6g5T1jWGYBDtvQb0WRVkdUy9
    L/uK+sHQwtloCSuakcQAsWV9bajCQtHX8XGu25Yz56kpJ/OJjcishxT6pc/sthum
    A5PX739JsNUi/p5aG+H/6eNx+ukJP7QaM646YCfS5i8S9DJUvim+/BSlKi2ZiOCd
    0MYH4Xb7lmAOTNmTvSYpKo9J2fZ9erw0MYSBTyjh6F7PRbHBiivgUnJfGQ==
    -----END CERTIFICATE-----
  etcdKey: |
    -----BEGIN RSA PRIVATE KEY-----
    k0dWj16h9P6TvfcNl2iwT4VIwx0uy2faWBED1DrCJcuQCy5nPrts2ZIaAWPi1t3t
    VbDKQvs+KXBEeqh0qYcYkejUXqIF0uKUFLjiQmZssjpL5RHqqWuYKbO87n+Jod1L
    TjGRHdbP0zF2U0LdjM17rc2hpJ3qrmgJ7pOLzbXMcOr+NP1ojRCArXhQ4iLs7D8T
    eHw9QH4luJYtnmk7x03izLMQdLWcKnUbqh/xOVPyazgJHXwRxwNXpMsBVGY=
    -----END RSA PRIVATE KEY-----

환경 변수 사용 예제

ETCD_ENDPOINTS=http://myhost1:2379 calicoctl get bgppeers

etcd DNS 디스커버리 사용 예제

ETCD_DISCOVERY_SRV=example.com calicoctl get nodes

IPv6 사용 예제

IPv6 로컬호스트 [::1]에서 수신하는 단일 노드 etcd 클러스터를 만들어요.

etcd --listen-client-urls=http://[::1]:2379 --advertise-client-urls=http://[::1]:2379

etcd IPv6 클러스터를 사용해요.

ETCD_ENDPOINTS=http://[::1]:2379 calicoctl get bgppeers

IPv4/IPv6 혼합 사용 예제

IPv4와 IPv6 로컬호스트 [::1]에서 수신하는 단일 노드 etcd 클러스터를 만들어요.

etcd --listen-client-urls=http://[::1]:2379,http://127.0.0.1:2379 --advertise-client-urls=http://[::1]:2379

IPv6 엔드포인트를 사용해요.

ETCD_ENDPOINTS=http://[::1]:2379 calicoctl get bgppeers

IPv4 엔드포인트를 사용해요.

ETCD_ENDPOINTS=http://127.0.0.1:2379 calicoctl get bgppeers

calico/node

주의할 점은 calicoctl이 호스트에서 지정된 키를 직접 사용해 etcd에 접근할 뿐 아니라, 이 환경 변수들을 그대로 전달하고 키를 볼륨 마운트로 시작된 calico-node 컨테이너에 넣어준다는 거예요.

따라서 etcd를 위한 calico/node 구성은 파라미터를 올바르게 설정한 상태로 calicoctl node run을 실행하는 것만으로 쉽게 끝나요.

구성 확인하기

설치와 구성이 올바른지 확인하는 간단한 명령이 있어요.

calicoctl get nodes

올바르게 설정됐다면 등록된 노드의 목록이 나와요. 빈 목록이 나오면 잘못된 데이터스토어를 가리키고 있거나 아직 노드가 하나도 등록되지 않은 거예요. 오류가 나오면 원인을 고친 뒤 다시 시도하세요.

다음 단계

이제 Calico의 대부분을 읽고 구성할 준비가 됐어요. 명령 전체 목록은 명령 레퍼런스에서 찾을 수 있어요.

관리할 수 있는 리소스의 전체 목록과 각 리소스에 대한 설명은 리소스 정의에서 확인할 수 있어요.

더 알아보기 (Learn more)

TLS를 쓴다면 엔드포인트가 HTTPS인지 먼저 확인하는 습관이 디버깅 시간을 크게 줄여줘요. calicoctl get nodes로 설정을 검증한 뒤 문제가 있으면 데이터스토어 주소와 인증서 경로부터 살펴보세요. 대부분의 작업은 이제 kubectl로도 가능하다는 점도 기억해두세요.