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

원문 보기 위키 갱신 2026.10.11

calicoctl CLI 도구를 Kubernetes API 데이터스토어에 연결하도록 구성하는 방법을 다뤄요. kubeconfig 경로, 환경 변수, 구성 파일 세 가지 방식을 모두 소개해요. 설정이 맞았는지 확인하는 명령까지 함께 안내해요.

출처: 문서

본문

큰 그림

calicoctl CLI 도구를 자신의 Kubernetes 클러스터에 맞게 구성하는 방법을 알아봐요.

이런 점이 좋아요

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

개념

calicoctl vs kubectl

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

최신 릴리스에서는 Calico API 서버가 그 기본값 적용과 검증을 서버 측에서 수행하고, calicoctl 없이도 같은 API 시맨틱을 노출해요. 그래서 대부분의 작업에는 Calico API 서버를 설치하고 calicoctl 대신 kubectl을 사용하는 것을 권해요.

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

기본 구성

기본적으로 calicoctl은 $(HOME)/.kube/config에 있는 기본 kubeconfig를 사용해 Kubernetes API에서 읽기를 시도해요.

기본 kubeconfig가 없거나 다른 API 접근 정보를 지정하고 싶다면, 다음 구성 옵션을 사용할 수 있어요.

방법

Kubernetes API 연결 구성 전체 목록

구성 파일 옵션	환경 변수	설명	스키마
`datastoreType`	`DATASTORE_TYPE`	사용할 데이터스토어를 나타내요. [기본값: `kubernetes`]	`kubernetes`, `etcdv3`
`kubeconfig`	`KUBECONFIG`	Kubernetes 데이터스토어를 사용할 때 사용할 kubeconfig 파일의 위치, 예: /path/to/kube/config.	string
`k8sAPIEndpoint`	`K8S_API_ENDPOINT`	Kubernetes API의 위치. kubeconfig를 사용하면 필요 없어요. [기본값: `https://kubernetes-api:443`]	string
`k8sCertFile`	`K8S_CERT_FILE`	Kubernetes API 접근용 클라이언트 인증서의 위치, 예: `/path/to/cert`.	string
`k8sKeyFile`	`K8S_KEY_FILE`	Kubernetes API 접근용 클라이언트 키의 위치, 예: `/path/to/key`.	string
`k8sCAFile`	`K8S_CA_FILE`	Kubernetes API 접근용 CA의 위치, 예: `/path/to/ca`.	string
`k8sToken`		Kubernetes API 접근에 사용할 토큰.	string

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

Kubernetes 커맨드 라인

DATASTORE_TYPE=kubernetes KUBECONFIG=~/.kube/config calicoctl get nodes

구성 파일 예시

apiVersion: projectcalico.org/v3
kind: CalicoAPIConfig
metadata:
spec:
  datastoreType: 'kubernetes'
  kubeconfig: '/path/to/.kube/config'

환경 변수 사용 예시

export DATASTORE_TYPE=kubernetes
export KUBECONFIG=~/.kube/config
calicoctl get workloadendpoints

CALICO_ 접두사가 붙은 이름을 사용하는 경우예요.

export CALICO_DATASTORE_TYPE=kubernetes
export CALICO_KUBECONFIG=~/.kube/config
calicoctl get workloadendpoints

여러 개의 kubeconfig 파일을 사용하는 경우예요.

export DATASTORE_TYPE=kubernetes
export KUBECONFIG=~/.kube/main:~/.kube/auxy
calicoctl get --context main workloadendpoints
calicoctl get --context auxy workloadendpoints

구성 확인하기

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

calicoctl get nodes

올바르게 설정되었다면 등록된 노드의 목록이 나와요. 빈 목록이 반환되면 잘못된 데이터스토어를 바라보고 있거나 아직 등록된 노드가 없는 거예요. 오류가 반환되면 문제를 고친 뒤 다시 시도하세요.

다음 단계

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

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

더 알아보기 (Learn more)

핵심은 DATASTORE_TYPE=kubernetes와 kubeconfig 경로(또는 CALICO_ 접두사 변형) 두 가지예요. Calico API 서버를 설치했다면 대부분의 작업을 kubectl로 대체할 수 있다는 점도 기억하세요. calicoctl get nodes로 연결이 정상인지 가장 먼저 확인하는 습관을 들이면 좋아요.