kubectl로 Calico API 관리 활성화하기

원문 보기 위키 갱신 2026.10.11

기존 클러스터에 Calico Open Source 집계(aggregation) API 서버를 설치해 calicoctl 없이 kubectl로 projectcalico.org/v3 리소스를 관리하는 방법을 안내해요.

출처: 문서

본문

큰 그림

기존 클러스터에 Calico API 서버를 설치해 kubectl로 Calico API를 관리할 수 있게 해요.

SUCCESS: 새 Calico 설치는 네이티브 v3 CRDs를 기본으로 사용해요. 이는 집계 API 서버 없이 projectcalico.org/v3 리소스를 직접 제공해요. 이 페이지는 대신 집계 API 서버를 설치하거나 활성화하는 방법을 다뤄요.

네이티브 v3 CRDs는 집계 API 서버의 후속 격이에요. 집계 API 서버는 네이티브 v3 CRDs가 모든 플랫폼에서 완전히 지원될 때까지 계속 지원되며, 향후 릴리스에서 제거될 예정이에요.

가치

API 서버는 Calico용 REST API를 제공하고, calicoctl 없이 kubectl로 projectcalico.org/v3 API를 관리할 수 있게 해줘요.

SECONDARY: 새 설치는 집계 API 서버가 아닌 네이티브 v3 CRDs를 기본으로 사용해요. 집계 API 서버를 원하거나 기존 클러스터에 추가하는 경우에 이 페이지를 사용하세요.

API 서버 모드로 설치하기 (v1 CRDs)

새 설치는 v3 CRD 모드가 기본이에요. 대신 집계 API 서버 모드로 설치하려면 오퍼레이터가 모드를 결정하기 전에 v1 CRDs를 설치하세요. crd.projectcalico.org/v1 CRDs가 있으면 오퍼레이터는 항상 API 서버 모드로 실행해요.

Tab: Helm 설치

Tigera Operator 전에 v1 CRD 차트를 설치해요:

helm template calico-crds projectcalico/crd.projectcalico.org.v1 --version v3.33.0 | kubectl apply --server-side -f -

Tab: 매니페스트 설치

Tigera Operator 전에 v1 CRDs를 적용해요:

kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v1_crd_projectcalico_org.yaml

그 다음 평소 설치 절차를 계속하면 돼요. 집계 API 서버는 자동으로 배포돼요.

시작하기 전에

Kubernetes API 데이터스토어를 사용하는 Calico가 설치된 클러스터가 있는지 확인해요. 없다면 etcd에서 마이그레이션할 수 있어요.
적절한 업그레이드 지침을 사용해 Calico v3.20+로 업그레이드해요.
비(非)오퍼레이터 설치라면 openssl이 설치된 머신이 필요해요.

개념

calicoctl vs kubectl

이전 릴리스에서는 projectcalico.org/v3 API 그룹의 Calico API 리소스를 관리하려면 calicoctl이 필요했어요. calicoctl CLI 도구는 이 API에 중요한 검증과 기본값 적용을 제공해요. Calico API 서버는 그 기본값 적용과 검증을 서버 사이드에서 수행해, calicoctl 의존성 없이 동일한 API 의미 체계를 제공해요.

대안으로 네이티브 v3 CRDs를 사용하면 projectcalico.org/v3 리소스가 네이티브 CRD이므로 리소스 관리에 API 서버나 calicoctl이 모두 필요 없이 kubectl이 직접 동작해요.

다음 하위 명령에는 여전히 calicoctl이 필요해요:

방법

API 서버 설치하기

설치 방법에 따라 아래 방식을 선택하세요.

Tab: Operator 설치

다음 명령으로 operator.tigera.io/APIServer 인스턴스를 만들어요.

kubectl create -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
  name: default
spec: {}
EOF

다음 명령으로 Available 상태로 표시되는지 확인해요.

kubectl get tigerastatus apiserver

다음 출력이 보여야 해요:

NAME        AVAILABLE   PROGRESSING   DEGRADED   SINCE
apiserver   True        False         False      1m10s

Tab: 매니페스트 설치

다음 매니페스트를 만들어요. 이 매니페스트는 calico-apiserver 네임스페이스에 API 서버를 deployment로 설치해요.
```
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/apiserver.yaml
```
API 서버가 ContainerCreating 상태에 머무는 것을 볼 수 있어요. 이는 메인 Kubernetes API 서버를 인증하기 위한 자격 증명이 제공되기를 기다리는 중이에요.
다음 openssl 명령으로 프라이빗 키와 CA 번들을 생성해요. 이 인증서는 메인 API 서버가 Calico API 서버와 인증할 때 사용돼요.

SECONDARY: 다음 명령의 -addext 인자는 openssl 1.1.1 이상이 필요해요. openssl version으로 자신의 openssl 버전을 확인할 수 있어요.
```
openssl req -x509 -nodes -newkey rsa:4096 -keyout apiserver.key -out apiserver.crt -days 365 -subj "/" -addext "subjectAltName = DNS:calico-api.calico-apiserver.svc"
```

키와 인증서를 Kubernetes 시크릿으로 Calico API 서버에 제공해요.

kubectl create secret -n calico-apiserver generic calico-apiserver-certs --from-file=apiserver.key --from-file=apiserver.crt

CA 번들로 메인 API 서버를 구성해요.

kubectl patch apiservice v3.projectcalico.org -p \
    "{\"spec\": {\"caBundle\": \"$(kubectl get secret -n calico-apiserver calico-apiserver-certs -o go-template='{{ index .data "apiserver.crt" }}')\"}}"

위 단계를 마치면 API 서버 파드가 준비 상태가 되고 Calico API 리소스를 사용할 수 있게 돼요. 다음 명령으로 API를 사용할 수 있는지 확인할 수 있어요:

kubectl api-resources | grep '\sprojectcalico.org'

다음 출력이 보여야 해요:

bgpconfigurations                 bgpconfig,bgpconfigs                            projectcalico.org              false        BGPConfiguration
bgppeers                                                                          projectcalico.org              false        BGPPeer
clusterinformations               clusterinfo                                     projectcalico.org              false        ClusterInformation
felixconfigurations               felixconfig,felixconfigs                        projectcalico.org              false        FelixConfiguration
globalnetworkpolicies             gnp,cgnp,calicoglobalnetworkpolicies            projectcalico.org              false        GlobalNetworkPolicy
globalnetworksets                                                                 projectcalico.org              false        GlobalNetworkSet
hostendpoints                     hep,heps                                        projectcalico.org              false        HostEndpoint
ippools                                                                           projectcalico.org              false        IPPool
kubecontrollersconfigurations                                                     projectcalico.org              false        KubeControllersConfiguration
networkpolicies                   cnp,caliconetworkpolicy,caliconetworkpolicies   projectcalico.org              true         NetworkPolicy
networksets                       netsets                                         projectcalico.org              true         NetworkSet
profiles                                                                          projectcalico.org              false        Profile

SECONDARY: kubectl은 로컬에서 API를 캐시하는 방식 때문에 계속 crd.projectcalico.org API 그룹을 선호할 수 있어요. 클러스터용 캐시 디렉터리를 제거해 kubectl이 업데이트하도록 강제할 수 있어요. 기본 캐시 위치는 $(HOME)/.kube/cache예요.

projectcalico.org API에 kubectl 사용하기

API 서버가 설치되면 kubectl로 Calico API를 다룰 수 있어요. 예를 들어 IP 풀을 조회하고 편집할 수 있어요.

kubectl get ippools

다음과 비슷한 출력이 보여야 해요:

NAME                  CREATED AT
default-ipv4-ippool   2021-03-19T16:47:12Z

Calico API 서버 제거하기

API 서버를 제거하려면 설치 방법에 따라 다음 지침을 사용하세요.

Tab: Operator 설치

   kubectl delete apiserver default

Tab: 매니페스트 설치

   kubectl delete -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/apiserver.yaml

제거한 후에는 네이티브 v3 CRDs를 사용 중이어서 kubectl이 직접 동작하는 경우가 아니라면 calicoctl로 projectcalico.org/v3 API를 관리해야 해요.

다음 단계

추천 튜토리얼

Kubernetes NetworkPolicy API로 간단한 애플리케이션 보호하기
Kubernetes NetworkPolicy API로 ingress와 egress 트래픽 제어하기
차단된 연결과 허용된 연결을 실시간으로 보여주는 튜토리얼 실행하기: 차단/허용 데모

더 알아보기 (Learn more)

집계 API 서버는 calicoctl 없이 kubectl만으로 projectcalico.org/v3 API를 다룰 수 있게 해주는 전통적인 방식이에요. 다만 새 설치는 네이티브 v3 CRDs가 기본이라는 점, 그리고 매니페스트 설치에서는 인증서 시크릿과 caBundle 패치가 필요하다는 점을 기억하세요.