API 서버에서 네이티브 CRD로 마이그레이션하기

원문 보기 위키 갱신 2026.10.11

이 문서는 Calico 리소스를 집계(aggregated) API 서버의 백킹 스토리지에서 네이티브 projectcalico.org/v3 CRD로 옮기는 방법을 다뤄요. 마이그레이션이 끝나면 API 서버 컴포넌트를 제거할 수 있어요. DatastoreMigration 컨트롤러가 자동화된 인플레이스 마이그레이션을 담당하고, 단계별 절차와 충돌 해결, 마이그레이션 중단 방법까지 함께 안내해요.

출처: 문서

본문

큰 그림

Calico 리소스를 집계 API 서버의 crd.projectcalico.org/v1 백킹 스토리지에서 네이티브 projectcalico.org/v3 CRD로 자동 마이그레이션해서, API 서버 컴포넌트를 제거할 수 있게 해요.

가치

최신 Calico 설치는 집계 API 서버 없이 네이티브 projectcalico.org/v3 CRD를 직접 사용해요. 운영이 더 단순해지고, 컴포넌트 하나가 줄어들며, CEL 검증 규칙 같은 Kubernetes 네이티브 기능도 쓸 수 있게 돼요. DatastoreMigration 컨트롤러는 아직 API 서버를 실행 중인 기존 클러스터를 위한 자동화된 인플레이스 마이그레이션 경로를 제공해요.

개념

동작 방식

마이그레이션 컨트롤러는 Calico 리소스 전체를 v1 CRD(API 서버의 백킹 스토리지)에서 네이티브 v3 CRD로 복사해요. 마이그레이션 구간 동안에는 데이터스토어가 짧게 잠기고(DatastoreReady=false) 컴포넌트들이 일시 정지한 채 캐시해 둔 데이터 플레인 상태를 유지해요. 그래서 기존 워크로드 연결은 전 과정에서 그대로 보존돼요.

마이그레이션은 다음 단계로 진행돼요:

단계	설명
`Pending`	CR이 생성됨, 사전 조건 검증 중
`Migrating`	데이터스토어 잠김, v1에서 v3 CRD로 리소스 복사 중
`WaitingForConflictResolution`	충돌 발견 — 사용자 개입 필요 (충돌 해결 참고)
`Converged`	모든 리소스 마이그레이션 완료, 데이터스토어 잠금 해제, 컴포넌트가 v3로 전환되기를 대기
`Complete`	모든 컴포넌트가 v3 CRD를 사용 중
`Failed`	마이그레이션에 복구 불가능한 오류 발생; CR을 삭제해 롤백한 뒤 재시도

마이그레이션되는 항목

모든 Calico 리소스 타입이 마이그레이션 대상이에요. 네트워크 정책, IP 풀, BGP 구성, Felix 구성, IPAM 블록 등이 포함돼요. IPAM 리소스는 새 IP 할당이 막히는 구간을 최소화하도록 가장 마지막에 마이그레이션돼요.

컨트롤러는 복사 과정에서 정책 이름 마이그레이션(레거시 default. 접두사 제거)도 자동으로 처리해요.

마이그레이션 구간 동안 일어나는 일

컴포넌트(Felix, Typha, kube-controllers)가 일시 정지하고 캐시한 데이터 플레인 상태를 유지해요
기존 워크로드 연결은 보존돼요 — 패킷 손실은 예상되지 않아요
마이그레이션이 끝날 때까지 새 파드 스케줄링과 정책 변경은 차단돼요
마이그레이션 마지막 단계 동안 IPAM 할당은 차단돼요

잠긴 구간은 보통 짧지만(클러스터 크기에 따라 수 초에서 수 분), 정책 변경이나 새 파드 배포가 필요 없는 유지보수 구간을 미리 잡아 두는 게 좋아요.

시작하기 전에

Calico v3.32 이상 (또는 마이그레이션 컨트롤러가 포함된 릴리스)
클러스터가 현재 API 서버 모드로 동작 중 (집계 API 서버가 배포되어 있음)
Kubernetes 1.32 이상. Calico는 기본값 채우기에 MutatingAdmissionPolicy API를 사용해요. 기본으로 활성화되지 않은 클러스터에서는 API 서버에 MutatingAdmissionPolicy feature gate를 켜야 해요.
GitOps(ArgoCD, Flux)를 사용 중이라면: 마이그레이션을 시작하기 전에 동기화를 일시 중지하세요. 이 도구들은 API 그룹 전환을 방해할 수 있어요. 마이그레이션이 끝나면 매니페스트를 projectcalico.org/v3로 업데이트하면 돼요.

WARNING: DatastoreMigration CR이 아직 존재하는 동안에는 DatastoreMigration CRD를 절대 삭제하지 마세요.

CRD를 삭제하면 해당 타입의 모든 커스텀 리소스가 삭제되고, 그 과정에서 CR의 finalizer가 실행돼요. CR이 Complete 상태였다면 crd.projectcalico.org CRD 전부와 그 안에 저장된 데이터가 삭제돼요. 다른 단계였다면 마이그레이션이 롤백돼요. 항상 CR을 먼저 삭제하고 사라진 것을 확인한 다음에 CRD를 삭제하세요.

방법

네이티브 CRD로 마이그레이션하기

v3 CRD를 설치해요.

Calico 릴리스의 v3 CRD 매니페스트를 적용해요. 집계 API 서비스가 활성화된 동안에는 Kubernetes가 이 CRD들을 무시하기 때문에, 미리 해 두어도 안전해요.

클러스터가 Kubernetes 1.36 이상 기반이라면:
```
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v3_projectcalico_org.yaml
```
클러스터가 Kubernetes 1.34 또는 1.35 기반이라면:
```
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/v3_projectcalico_org-v1beta1.yaml
```

DatastoreMigration CRD를 설치해요.

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.33.0/manifests/migration.projectcalico.org_datastoremigrations.yaml

DatastoreMigration CR을 만들어요.

kubectl apply -f - <<EOF
apiVersion: migration.projectcalico.org/v1
kind: DatastoreMigration
metadata:
  name: v1-to-v3
spec:
  type: APIServerToCRDs
EOF

진행 상황을 모니터링해요.
```
kubectl get datastoremigration v1-to-v3 -w
```
Pending → Migrating → Converged → Complete 단계 전환을 볼 수 있어요.

리소스 타입별 진행 상황을 더 자세히 보려면:
```
kubectl get datastoremigration v1-to-v3 -o yaml
```
완료를 기다려요.

오퍼레이터 관리 설치: 마이그레이션이 Converged에 도달하면 오퍼레이터가 자동으로 감지해 모든 컴포넌트를 v3 CRD 모드로 전환해요. 모든 컴포넌트에 CALICO_API_GROUP=projectcalico.org/v3를 설정하고 롤링 업데이트를 트리거해요. 수동 작업은 필요 없어요 — 단계가 Complete에 도달하기만 하면 돼요.

매니페스트 기반 설치: 마이그레이션이 Converged에 도달하면 모든 Calico 컴포넌트(calico-node, typha, kube-controllers)에 CALICO_API_GROUP=projectcalico.org/v3를 수동으로 설정하고 롤링 업데이트를 트리거해야 해요. helm 값이나 매니페스트를 업데이트해 API 서버를 비활성화하세요.
v1 CRD를 정리해요.

새 CRD에서 모든 것이 잘 동작한다고 확신되면 DatastoreMigration CR을 삭제하세요. CR의 finalizer가 crd.projectcalico.org CRD 전부와 저장된 데이터를 삭제해요.
```
kubectl delete datastoremigration v1-to-v3
```
DatastoreMigration CRD를 삭제해요.

이전 단계의 CR이 사라진 다음에만 진행하세요. 이 CRD는 Calico 설치의 일부가 아니므로 마이그레이션 이후로 남아 있을 이유가 없어요. 지우면 향후 릴리스가 deprecated된 v1beta1 버전을 제거할 때 스토리지 버전 마이그레이션을 실행하지 않아도 되는 부수적인 이점도 있어요.
```
kubectl get datastoremigration
kubectl delete crd datastoremigrations.migration.projectcalico.org
```
GitOps 동기화 재개 (해당하는 경우). 매니페스트를 projectcalico.org/v3 API 버전으로 업데이트하고 동기화를 재개해요.

충돌 해결하기

마이그레이션이 v1 소스와 다른 spec을 가진 v3 리소스를 발견하면 충돌을 보고해요. 단계가 WaitingForConflictResolution로 바뀌고 마이그레이션이 일시 중지돼요.

어떤 리소스에 충돌이 있는지 확인하려면:

kubectl get datastoremigration v1-to-v3 -o jsonpath='{.status.conditions}' | jq .

각 충돌 condition에는 리소스 이름과 불일치에 대한 설명이 들어 있어요. 해결 방법은 다음과 같아요:

우연히 만들어졌거나 오래된(stale) v3 리소스라면 충돌하는 v3 리소스를 삭제하세요. 다음 reconcile 때 마이그레이션이 v1 소스에서 다시 만들어 줘요.
v3 버전을 유지하고 싶다면 v3 리소스를 v1 소스에 맞게 업데이트하세요.

모든 충돌을 해결하고 나면 다음 reconcile 주기에 마이그레이션 컨트롤러가 자동으로 재개해요.

마이그레이션 중단하기

무언가 잘못됐다면 마이그레이션이 Converged에 도달하기 전에 DatastoreMigration CR을 삭제하세요:

kubectl delete datastoremigration v1-to-v3

finalizer가 롤백을 처리해요:

마이그레이션 중에 만들어진 부분적인 v3 리소스를 정리해요
집계 APIService를 복원해 컴포넌트가 다시 v1 CRD를 읽도록 만들어요
컴포넌트는 마이그레이션이 없었던 것처럼 정상 동작으로 복귀해요

마이그레이션 중에 v1 데이터는 절대 수정되지 않기 때문에, 중단 후에도 v1 데이터가 여전히 권위 있는(authoritative) 소스로 남아요.

중단은 Converged까지만 가능해요. Converged부터는 리소스가 이미 v3 CRD에 들어 있고 컴포넌트가 전환 중이므로, 마이그레이션이 Complete까지 진행되도록 두세요.

이미 마이그레이션을 완료한 클러스터에는 중단해서 되돌아갈 대상이 없고, v1 CRD를 삭제했다면 v1 데이터도 사라져요. 그런 클러스터에서는 두 번째 DatastoreMigration CR을 만들지 마세요.

v3.32에서 v3.33으로 업그레이드하기

v3.33에서는 DatastoreMigration CRD가 migration.projectcalico.org/v1beta1에서 v1로 옮겨가요. CRD는 두 버전을 모두 서빙하고 v1beta1은 deprecated 상태이므로, v3.32 CRD 위에 v3.33 CRD를 적용하는 것은 단순 업데이트예요. 자리를 만들겠다고 오래된 CRD를 삭제하지 마세요.

v3.33부터 마이그레이션은 migration.projectcalico.org/v1에서만 구동돼요. 업그레이드 시점에 이미 진행 중이던 마이그레이션은 끝까지 진행되지만, pre-GA인 v1beta1 CRD만 서빙하는 클러스터는 새 마이그레이션 시작을 거부하고 v1 CRD를 적용해야 한다고 보고해요.

마이그레이션 CRD는 Calico 설치의 일부가 아니므로 대부분의 클러스터에서는 할 일이 없어요. v3.32에서 설치해 두었다면 DatastoreMigration CR 상태에 따라 조치가 달라져요:

v3.32에서의 상태	업그레이드하기 전에
마이그레이션 CRD를 설치한 적 없음	할 일 없음. 평소처럼 업그레이드하세요.
CRD 설치됨, CR 없음	필수 작업 없음. CRD 삭제는 선택적인 정리이며, CR이 없는 것을 확인한 후에만 진행하세요.
CR이 `Complete` 상태로 남아 있음	네이티브 CRD로 마이그레이션하기의 정리 단계를 실행하세요: CR 삭제, 그다음 CRD 삭제. 그 후에 업그레이드하세요.
CR이 `Pending`, `Migrating`, `WaitingForConflictResolution` 상태	업그레이드하지 마세요. 마이그레이션을 먼저 마치거나 중단하세요.
CR이 `Converged` 상태	업그레이드하지 마세요. `Complete`를 기다리세요; 이 단계에서는 중단이 불가능해요.
CR이 `Failed` 상태	CR을 삭제해 롤백하고, 클러스터가 v1에서 건강한지 확인한 뒤 업그레이드하세요.
마이그레이션 완료 후 v1 CRD까지 삭제됨	할 일 없으며, 이 클러스터에서 두 번째 `DatastoreMigration` CR은 절대 만들지 마세요.

알려진 제한 사항

non-Calico 리소스의 OwnerReferences. 마이그레이션은 Calico 리소스의 OwnerReference UID를 재매핑하지만, Calico 객체를 가리키는 OwnerReferences를 찾기 위해 non-Calico 리소스(ConfigMap, Secret, 다른 프로젝트의 커스텀 리소스)를 훑지는 않아요. Calico 리소스를 참조하는 OwnerReferences를 가진 non-Calico 리소스가 있다면, 마이그레이션 후 Calico 리소스 UID가 바뀌기 때문에 그 참조는 stale 상태가 돼요. 마이그레이션이 끝난 뒤 이런 참조는 수동으로 업데이트해야 해요. 이런 경우는 드물 것으로 예상돼요.

더 알아보기 (Learn more)

마이그레이션의 핵심은 finalizer 동작이에요. CR과 CRD의 삭제 순서를 지키지 않으면 데이터 삭제로 이어질 수 있어요. GitOps를 쓴다면 동기화 일시 중지와 projectcalico.org/v3 매니페스트 업데이트 타이밍을 미리 계획해 두세요.