etcdv3 데이터스토어에서 Kubernetes 데이터스토어로 Calico 데이터 마이그레이션하기

원문 보기 위키 갱신 2026.10.12

운영 중인 클러스터를 중단하지 않고 etcdv3 데이터스토어에서 Kubernetes API 데이터스토어로 전환하고 싶다면 이 가이드가 정답이에요. calicoctl의 마이그레이션 명령으로 데이터스토어를 잠그고, 내보내고, 다시 가져오는 흐름을 차근차근 안내해요. Kubernetes 데이터스토어로 이사하면 구성 요소가 줄고 RBAC 지원도 좋아지는 장점이 있죠.

출처: 문서

본문

큰 그림

운영 중인 클러스터에서 Calico 데이터스토어를 etcdv3에서 Kubernetes로 전환해요.

가치

Kubernetes를 데이터스토어로 사용하면 etcdv3를 직접 쓰는 것에 비해 구성 요소가 줄어들고 역할 기반 접근 제어(RBAC) 지원이 더 좋아지는 등 여러 가지 이점이 있어요. 대부분의 사용자에게 Kubernetes 데이터스토어가 더 나은 경험을 제공해요. 기존 클러스터의 etcdv3 데이터스토어에서 Kubernetes 데이터스토어로 데이터를 마이그레이션하는 매끄러운 방법을 제공해요. etcd 데이터스토어 대비 Kubernetes 데이터스토어 사용의 전체 장점 목록은 Calico 데이터스토어 문서를 참고하세요.

시작하기 전에

Calico 설치가 etcdv3 데이터스토어를 사용하도록 구성되어 있는지 확인하세요. 이 가이드는 Kubernetes API 데이터스토어로 설치된 클러스터에는 적용되지 않아요.
최신 버전의 calicoctl이 설치되고 etcd에 접근하도록 구성되어 있어야 해요.

참고: 아래 단계에서 calicoctl 구성을 수정해야 하므로, 이 절차에는 Kubernetes pod로 설치된 calicoctl을 사용하지 않는 걸 권장해요. 대신 etcd와 Kubernetes API에 접근할 수 있는 호스트에 바이너리를 직접 설치하세요.

방법

데이터스토어 마이그레이션하기

데이터스토어 내용을 마이그레이션할 때는 calicoctl datastore migrate 명령과 하위 명령을 사용해요. 자세한 내용은 calicoctl datastore migrate 문서를 참고하세요.

마이그레이션을 위해 etcd 데이터스토어를 잠가요. 이렇게 하면 데이터 변경이 클러스터에 영향을 주는 일을 막을 수 있어요.
```
calicoctl datastore migrate lock
```
참고: 위 명령을 실행한 후에는 마이그레이션이 완료될 때까지 클러스터 구성을 변경할 수 없어요. 마이그레이션이 끝날 때까지 새 pod는 시작되지 않아요.
데이터스토어 내용을 파일로 내보내요.
```
calicoctl datastore migrate export > etcd-data
```
calicoctl이 Kubernetes 데이터스토어에 접근하도록 구성해요.
내보낸 파일에서 데이터스토어 내용을 가져와요(임포트).
```
calicoctl datastore migrate import -f etcd-data
```
데이터스토어가 제대로 임포트되었는지 확인해요. calicoctl로 etcd 데이터스토어에 있던 Calico 리소스(예: networkpolicy)를 조회하면 확인할 수 있어요.
```
calicoctl get networkpolicy
```
Calico가 Kubernetes 데이터스토어를 읽도록 구성해요. Kubernetes 데이터스토어로 Calico를 설치하는 방법 안내를 따르세요. 설치 안내에는 적용할 calico.yaml 파일의 관련 버전이 나와 있어요.
```
kubectl apply -f calico.yaml
```
다음 명령을 모니터링하면서 Calico가 롤링 업데이트를 마칠 때까지 기다려요.
```
kubectl rollout status daemonset calico-node -n kube-system
```
데이터스토어의 잠금을 해제해요. 이제 Calico 리소스가 다시 클러스터에 영향을 줄 수 있어요.
```
calicoctl datastore migrate unlock
```
참고: Kubernetes 데이터스토어의 잠금이 해제되면 데이터스토어 마이그레이션은 더 이상 롤백할 수 없어요. 잠금을 해제하기 전에 Kubernetes 데이터스토어에 기대한 Calico 리소스가 모두 채워져 있는지 반드시 확인하세요.

데이터스토어 마이그레이션 롤백하기

데이터스토어 마이그레이션의 롤백은 원본 etcd 데이터스토어가 아직 존재하고, 데이터스토어 리소스를 임포트한 뒤 Kubernetes 데이터스토어의 잠금을 해제하지 않은 경우에만 가능해요. 다음 단계는 Kubernetes 데이터스토어로 임포트된 Calico 리소스를 삭제하고, 클러스터가 다시 원본 etcd 데이터스토어를 읽도록 구성해요.

Kubernetes 데이터스토어를 잠가요.
```
calicoctl datastore migrate lock
```
모든 Calico CRD를 삭제해요. 이렇게 하면 Kubernetes 데이터스토어에 임포트된 데이터가 모두 제거돼요.
```
kubectl delete $(kubectl get crds -o name | grep projectcalico.org)
```
Calico가 etcd 데이터스토어를 읽도록 구성해요. etcd 데이터스토어로 Calico를 설치하는 방법 안내를 따르세요. 설치 안내에는 적용할 calico.yaml 파일의 관련 버전이 나와 있어요.
```
kubectl apply -f calico.yaml
```
calicoctl이 etcd 데이터스토어에 접근하도록 구성해요.
etcd 데이터스토어의 잠금을 해제해요. 이제 Calico 리소스가 다시 클러스터에 영향을 줄 수 있어요.
```
calicoctl datastore migrate unlock
```

더 알아보기 (Learn more)

Kubernetes 데이터스토어는 대부분의 사용자에게 권장되는 기본 선택이에요. 마이그레이션 전에 잠금 상태에서 데이터가 완전히 임포트되었는지 확인하는 습관이 롤백 불가능한 실수를 막아 줘요.