네이티브 v3 CRDs

원문 보기 위키 갱신 2026.10.11

새 Calico 설치는 기본으로 네이티브 projectcalico.org/v3 CRDs를 사용해요. 이 페이지에서는 네이티브 v3 CRD 모드가 동작하는 방식과, 대신 집계(aggregation) API 서버로 설치하는 방법을 설명해요.

출처: 문서

본문

큰 그림

새 Calico 설치는 기본으로 네이티브 projectcalico.org/v3 CRDs를 사용해요: Calico 리소스는 집계 API 서버 없이 CRD가 직접 뒷받침해요. 이 페이지는 이 모드가 어떻게 동작하는지, 그리고 대신 집계 API 서버로 설치하는 방법을 설명해요.

네이티브 projectcalico.org/v3 CRDs는 Calico 집계 API 서버의 후속 격이에요. 집계 API 서버는 당분간 지원되지만 향후 릴리스에서 제거될 예정이에요.

가치

기본적으로 Calico는 집계 API 서버를 사용해 projectcalico.org/v3 API를 제공하고, 리소스는 내부적으로 crd.projectcalico.org/v1 CRDs로 저장해요. 네이티브 projectcalico.org/v3 CRDs를 사용하면 Calico 리소스 자체가 CRD가 되어 다음과 같은 이점이 있어요:

더 간단한 아키텍처 — 배포하고 관리할 집계 API 서버가 없어요
GitOps 친화적 — CRD와 API 서버 사이 순서 의존성이 없어서 ArgoCD나 Flux 같은 도구로 리소스를 어떤 순서로든 적용할 수 있어요
플랫폼 마찰 감소 — 호스트 네트워크 파드 같은 집계 API 서버의 요구 사항이 사라져요
kubectl 직접 사용 — API 서버를 별도 설치하지 않고도 kubectl로 projectcalico.org/v3 리소스를 관리할 수 있어요
네이티브 Kubernetes 검증과 기본값 적용 — CRD 스키마에 내장된 CEL 검증 규칙과 기본값 적용용 MutatingAdmissionPolicies를 사용해, 커스텀 API 서버 대신 Kubernetes 내장 메커니즘을 활용해요

개념

네이티브 `projectcalico.org/v3` CRDs의 동작 방식

네이티브 projectcalico.org/v3 CRDs를 사용할 때:

Calico 리소스는 projectcalico.org/v3 API 그룹을 사용하며 네이티브 Kubernetes CRD로 등록돼요.
APIServer 커스텀 리소스는 여전히 만들어지지만, 집계 API 서버를 실행하는 대신 admission 정책으로 검증과 기본값 적용을 처리하는 webhooks 파드를 배포해요.
Calico는 시작 시 클러스터에 설치된 CRD를 기준으로 모드를 자동 감지해요. projectcalico.org/v3 CRDs가 있으면 네이티브로 사용하고, crd.projectcalico.org/v1 CRDs가 있으면 API 서버 모드로 실행해요.

검증과 기본값 적용

네이티브 projectcalico.org/v3 CRDs를 사용할 때 리소스 검증과 기본값 적용은 네이티브 CRD 검증·기본값 적용과 ValidatingAdmissionPolicies, MutatingAdmissionPolicies가 처리해요. Calico는 기본값 적용에 MutatingAdmissionPolicies를 사용하는데, Kubernetes 1.34 이상이 필요해요: Kubernetes 1.34와 1.35에서는 베타 admissionregistration.k8s.io/v1beta1 API를, 1.36 이상에서는 GA admissionregistration.k8s.io/v1 API를 사용해요. Kubernetes 1.33 이하에서는 MutatingAdmissionPolicy가 알파 API(v1alpha1)로만 제공되며 Calico는 지원하지 않아요. Kubernetes 1.34와 1.35에서는 기본적으로 활성화되어 있지 않기 때문에 네이티브 projectcalico.org/v3 CRDs를 사용하기 전에 Kubernetes API 서버에서 MutatingAdmissionPolicy 기능 게이트를 활성화해야 해요. Kubernetes 1.36 이상에서는 이 기능이 GA이고 기본 활성화돼 있어요.

시작하기 전에

Calico가 설치되지 않은 Kubernetes 클러스터, 또는 새로 설치를 진행하는 클러스터. 기존 클러스터를 API 서버 모드에서 마이그레이션하려면 API 서버에서 네이티브 CRD로 마이그레이션을 참고하세요.
Kubernetes 1.34 이상. Calico는 기본값 적용에 MutatingAdmissionPolicies를 사용하는데, Kubernetes 1.34와 1.35에서는 베타 admissionregistration.k8s.io/v1beta1 API가, 1.36 이상에서는 GA admissionregistration.k8s.io/v1 API가 필요해요. 둘 다 Kubernetes 1.33 이하에서는 사용할 수 없어요(그 버전에서는 MutatingAdmissionPolicy가 알파 전용). Kubernetes 1.34와 1.35에서는 기본적으로 활성화되지 않으므로 API 서버에서 MutatingAdmissionPolicy 기능 게이트를 활성화해야 해요. Kubernetes 1.36 이상에서는 이 기능이 GA이고 기본 활성화돼 있어요.

방법

네이티브 `projectcalico.org/v3` CRDs로 Calico 설치하기

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

Tab: Helm 설치

Calico Helm 저장소를 추가해요:

helm repo add projectcalico https://docs.tigera.io/calico/charts

tigera-operator 네임스페이스를 만들어요:
```
kubectl create namespace tigera-operator
```

기본 v1 CRD 차트 대신 v3 CRD 차트를 설치해요.

클러스터가 Kubernetes 1.36 이상 기반이라면:

helm template calico-crds projectcalico/projectcalico.org.v3 --version v3.33.0 --api-versions admissionregistration.k8s.io/v1/MutatingAdmissionPolicy | kubectl apply --server-side -f -

클러스터가 Kubernetes 1.34 또는 1.35 기반이라면:

helm template calico-crds projectcalico/projectcalico.org.v3 --version v3.33.0 --api-versions admissionregistration.k8s.io/v1beta1/MutatingAdmissionPolicy | kubectl apply --server-side -f -

SECONDARY: 이 차트는 기본 설치에서 사용하는 crd.projectcalico.org.v1 차트를 대체해요. 두 CRD 차트를 함께 설치하지 마세요.

Tigera Operator를 설치해요:

helm install calico projectcalico/tigera-operator --version v3.33.0 --namespace tigera-operator

커스텀 구성이 담긴 values.yaml이 있다면:

helm install calico projectcalico/tigera-operator --version v3.33.0 -f values.yaml --namespace tigera-operator

Tab: 매니페스트 설치

v3 CRDs를 설치해요:

클러스터가 Kubernetes 1.36 이상 기반이라면:
```
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v3_projectcalico_org.yaml
```
클러스터가 Kubernetes 1.34 또는 1.35 기반이라면:
```
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v3_projectcalico_org-v1beta1.yaml
```
SECONDARY: 이 매니페스트는 기본 설치에서 사용하는 v1_crd_projectcalico_org.yaml을 대체해요. 두 CRD 매니페스트를 함께 설치하지 마세요.

Tigera Operator를 설치해요:

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

필요한 커스텀 리소스를 만들어 Calico를 설치해요:

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

설치 후 다음 단계를 완료해요:

webhooks 파드를 배포하도록 APIServer CR을 만들어요. 이는 집계 API 서버를 실행하지 않아요 — 대신 검증과 기본값 적용을 처리하는 admission webhook을 배포해요.
```
kubectl create -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
  name: default
spec: {}
EOF
```
모든 파드가 실행 중인지 확인해요:
```
watch kubectl get pods -n calico-system
```
projectcalico.org 리소스를 사용할 수 있는지 확인해요:
```
kubectl api-resources | grep '\sprojectcalico.org'
```

이제 kubectl을 직접 사용해 Calico 리소스를 관리할 수 있어요. 예를 들면:

kubectl get ippools
kubectl get felixconfigurations
kubectl get bgpconfigurations

API 서버 모드와의 동작 차이

대부분의 클라이언트에서는 API가 기대대로, 기존 동작과 일관되게 계속 동작해요. 아래에 몇 가지 작은 예외만 있어요.

kubectl 접근

네이티브 projectcalico.org/v3 CRDs를 사용하면 집계 API 서버 없이도 kubectl이 Calico 리소스를 직접 관리할 수 있어요. 별도 설치 단계나 캐시 정리도 필요 없어요.

IPPool CIDR 겹침 검증

API 서버 모드에서는 기존 풀과 겹치는 CIDR로 IPPool을 만들면 생성 시점에 동기적으로 거부돼요.

네이티브 projectcalico.org/v3 CRDs를 사용하면 IPPool CIDR 겹침 검증은 비동기로 동작해요. CIDR이 겹치는 풀은 성공적으로 생성되지만 Disabled 상태 조건이 붙어요. IPAM은 비활성화된 풀에서는 주소를 할당하지 않아요. CIDR 겹침 때문에 비활성화된 풀을 찾으려면 IPPool 상태를 확인해요:

kubectl get ippool <pool-name> -o yaml

Tier RBAC 적용

두 모드 모두에서 tier 기반 RBAC은 tier.networkpolicies, tier.globalnetworkpolicies 같은 의사 리소스(pseudo-resources)를 사용하는 동일한 ClusterRole과 RoleBinding 정의를 사용해요.

API 서버 모드에서는 집계 API 서버가 모든 작업(create, update, delete, get, list, watch)에 tier RBAC을 적용해요.

네이티브 projectcalico.org/v3 CRDs를 사용할 때는 admission webhook이 create, update, delete 작업에 tier RBAC을 적용해요. 하지만 admission webhook은 읽기 작업을 가로챌 수 없기 때문에 tiered 정책에 대한 GET, LIST, WATCH 작업에는 적용되지 않아요. 이는 알려진 한계예요.

calicoctl

네이티브 projectcalico.org/v3 CRDs를 사용해도 calicoctl은 계속 동작하지만, kubectl이 Calico 리소스를 기본으로 처리하므로 덜 필요해요. 그래도 calicoctl이 유용한 경우는:

calicoctl node 하위 명령
calicoctl ipam 하위 명령
calicoctl version

알려진 한계

GET/LIST/WATCH tier RBAC 미적용 — Admission webhook은 읽기 작업을 가로챌 수 없기 때문에, 네이티브 projectcalico.org/v3 CRDs를 사용할 때 GET, LIST, WATCH에 대한 tier 기반 RBAC은 적용되지 않아요.

더 알아보기 (Learn more)

네이티브 v3 CRDs는 집계 API 서버 없이 CRD와 admission 정책만으로 검증과 기본값 적용을 처리하는 더 단순한 아키텍처예요. MutatingAdmissionPolicy 요구 사항(Kubernetes 1.34 이상)만 확인하면 GitOps 파이프라인에서도 훨씬 자유로워져요.