Calico를 오퍼레이터 관리형 설치로 마이그레이션하기

원문 보기 위키 갱신 2026.10.11

매니페스트 기반 Calico 설치를 Calico 오퍼레이터가 관리하는 설치로 전환하는 절차를 다뤄요. 플랫폼 자동 감지, 더 간단한 업그레이드, 리소스 라이프사이클 관리 같은 이점을 얻을 수 있어요. 마이그레이션 후 리소스가 calico-system 네임스페이스로 옮겨지는 것까지 확인해요.

출처: 문서

본문

큰 그림

Calico 설치를 매니페스트 기반 리소스에서 Calico 오퍼레이터가 관리하는 설치로 전환해요.

이런 점이 좋아요

Calico 오퍼레이터는 전통적인 매니페스트 기반 Calico 리소스 설치 대비 다음을 포함한 여러 장점을 제공해요.

플랫폼과 구성의 자동 감지.
간소화된 업그레이드 절차.
최종 사용자 구성과 제품 코드 사이의 명확한 분리.
리소스 조정(reconciliation)과 라이프사이클 관리.

개념

오퍼레이터 설치 vs 매니페스트 기반 설치

과거의 대부분의 Calico 설치는 매니페스트 기반이었어요. 즉 Calico가 .yaml 파일에 담긴 Kubernetes 리소스 묶음으로 직접 설치되는 방식이에요.

Calico 오퍼레이터는 Deployment, DaemonSet, Secret 같은 Kubernetes 리소스를 만들고 갱신하는 방식으로 Calico 설치와 그 라이프사이클을 관리하는 Kubernetes 애플리케이션이에요. 사용자가 직접 개입할 필요가 없어요.

매니페스트 기반 설치에 익숙하고 오퍼레이터를 사용하려는 사용자라면 알아 둘 몇 가지 핵심 차이가 있어요.

Calico 리소스는 Calico 매니페스트가 사용하는 kube-system 네임스페이스에서 새로운 calico-system 네임스페이스로 옮겨져요.
Calico 오퍼레이터가 의도하지 않은 변경을 조정(reconcile)해서 기대 상태를 유지하기 때문에, Calico 리소스를 더 이상 손으로 편집할 수 없어요.
대신 operator.tigera.io API로 Calico 리소스를 구성할 수 있어요.

오퍼레이터 마이그레이션

새 클러스터라면 퀵스타트 가이드의 단계를 따라 오퍼레이터로 시작하면 돼요.

calico.yaml 매니페스트로 Calico를 설치한 기존 클러스터라면, 오퍼레이터를 설치할 때 클러스터의 기존 Calico 리소스를 감지하고 그것들의 소유권을 가져오는 방법을 계산해요. 오퍼레이터는 지원되는 기존 커스터마이징은 유지하고, 감지한 지원되지 않는 구성은 경고해요.

시작하기 전에

Calico 설치가 Kubernetes 데이터스토어를 사용하도록 구성되어 있는지 확인하세요. 클러스터가 etcdv3을 직접 사용한다면 이 문서를 따르기 전에 데이터스토어 마이그레이션 절차를 먼저 수행해야 해요.
Calico v3.33 오퍼레이터 관리형 설치로의 마이그레이션은 Calico v3.33 매니페스트 기반 설치에서만 지원돼요.

방법

클러스터를 오퍼레이터로 마이그레이션하기

SECONDARY: 다음 절차 동안 kube-system 네임스페이스의 어떤 리소스도 편집하거나 삭제하지 마세요. 업그레이드를 방해할 수 있어요.

Tigera Operator와 커스텀 리소스 정의를 설치해요.

kubectl apply --server-side --force-conflicts -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v1_crd_projectcalico_org.yaml
kubectl apply --server-side --force-conflicts -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/tigera-operator.yaml

SECONDARY: CRD 번들의 크기가 커서 kubectl apply가 요청 한도를 초과할 수 있어요. 대신 kubectl create나 kubectl replace를 사용하세요.

Installation 리소스를 만들어 오퍼레이터가 마이그레이션을 시작하게 트리거해요. 오퍼레이터가 기존 Calico 설정을 자동으로 감지해 spec 섹션을 채워요.
```
kubectl create -f - <<EOF
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
  name: default
spec: {}
EOF
```
다음 명령으로 마이그레이션 상태를 모니터링해요.
```
kubectl describe tigerastatus calico
```

마이그레이션이 완료되면 Calico 리소스가 calico-system 네임스페이스로 옮겨진 것을 볼 수 있어요.

kubectl get pods -n calico-system

다음과 같은 출력이 보일 거예요.

NAME                                       READY   STATUS    RESTARTS   AGE
calico-kube-controllers-7688765788-9rqht   1/1     Running   0          17m
calico-node-4ljs6                          1/1     Running   0          14m
calico-node-bd8mc                          1/1     Running   0          14m
calico-node-cpbd8                          1/1     Running   0          14m
calico-node-jl97q                          1/1     Running   0          14m
calico-node-xw2nj                          1/1     Running   0          14m
calico-typha-57bf79f96f-6sk8x              1/1     Running   0          14m
calico-typha-57bf79f96f-g99s9              1/1     Running   0          14m
calico-typha-57bf79f96f-qtchs              1/1     Running   0          14m

이 시점에서 오퍼레이터가 kube-system 네임스페이스의 Calico 리소스를 자동으로 정리했을 거예요. 수동 정리는 필요 없어요.

더 알아보기 (Learn more)

마이그레이션의 본질은 "오퍼레이터가 기존 리소스의 소유권을 가져오고 calico-system으로 옮긴다"예요. CRD가 크다는 이유로 kubectl apply 실패 시 create/replace로 우회하는 팁이 실전에서 자주 쓰여요. v3.33 매니페스트 → v3.33 오퍼레이터라는 버전 매칭 조건도 잊지 마세요.