내부망 환경의 Calico CNI 배포 이슈
관리 노드 1개와 작업 노드 2개로 구성된 소규모 Kubernetes 클러스터를 구축할 때, 네트워크 플러그인으로 Calico를 선택하는 경우가 많습니다. 하지만 외부 인터넷 연결이 제한적이거나 프록시 환경인 내부망(On-premise)에서는 배포 과정에서 여러 가지 장애가 발생할 수 있습니다. 특히 ImagePullBackOff와 권한 관련 오류가 가장 대표적입니다.
주요 장애 현상 분석
Calico 배포 후 kubectl get pods -n kube-system 명령어로 상태를 확인했을 때, Pod가 정상적으로 생성되지 않는다면 다음 두 가지 원인을 의심해 보아야 합니다.
- 이미지 다운로드 실패:
containerd환경에서 Docker Hub 접근이 차단되어calico/node또는calico/kube-controllers이미지를 가져오지 못하는 경우입니다. - CNI 권한 인증 실패:
kubectl describe pod실행 시connection is unauthorized와 같은 메시지가 출력된다면, Calico가 Kubernetes API 서버에 접근하기 위한 RBAC 설정이나 ServiceAccount에 문제가 있는 것입니다.
해결 방법: containerd 기반 이미지 수동 관리
Docker CLI가 설치되지 않은 containerd 전용 환경에서는 ctr 명령어를 사용하여 각 노드에 필요한 이미지를 직접 주입해야 합니다. Kubernetes는 k8s.io라는 별도의 네임스페이스를 사용하므로 이미지 작업 시 이를 명시해야 합니다.
# 1. 관리 노드 및 모든 작업 노드에서 이미지 수동 풀링
sudo ctr -n k8s.io images pull docker.io/calico/node:v3.27.3
sudo ctr -n k8s.io images pull docker.io/calico/kube-controllers:v3.27.3
# 2. 이미지 태그 설정 (필요 시)
sudo ctr -n k8s.io images tag docker.io/calico/node:v3.27.3 docker.io/calico/node:v3.27.3
sudo ctr -n k8s.io images tag docker.io/calico/kube-controllers:v3.27.3 docker.io/calico/kube-controllers:v3.27.3
이미지 준비가 완료되면 기존에 오류가 발생한 Pod를 삭제하여 재배포를 유도합니다. Kubernetes 스케줄러는 로컬에 이미 준비된 이미지를 사용하여 Pod를 즉시 실행합니다.
# 기존 실패한 Calico Pod 제거
kubectl delete pod -l k8s-app=calico-node -n kube-system
kubectl delete pod -l k8s-app=calico-kube-controllers -n kube-system
네트워크 통신 정상 여부 확인
Pod가 Running 상태로 전환되었다면, 실제로 서로 다른 노드에 배치된 Pod 간에 통신이 원활한지 테스트해야 합니다. 이는 Calico의 BGP 라우팅이나 캡슐화(IPIP/VXLAN)가 정상 작동하는지 확인하는 필수 단계입니다.
# 테스트용 Pod 생성
kubectl run net-test-1 --image=busybox --restart=Never -- sleep 4000
kubectl run net-test-2 --image=busybox --restart=Never -- sleep 4000
# 각 Pod의 IP 확인
kubectl get pods -o wide
# 서로 다른 노드의 Pod IP로 ping 테스트
kubectl exec -it net-test-1 -- ping -c 4 [net-test-2-IP]
운영 팁 및 주의사항
- 노드별 로컬 저장소:
containerd는 노드마다 이미지 저장소가 격리되어 있습니다. 따라서 Master 노드뿐만 아니라 모든 Worker 노드에서 동일한 이미지 풀링 작업을 수행해야 합니다. - YAML 설정 확인: Calico 매니페스트 파일에서
CALICO_IPV4POOL_CIDR설정이 클러스터의 실제 Pod 네트워크 대역과 일치하는지 확인하십시오. - 방화벽 규칙: 내부망인 경우 노드 간에 BGP(TCP 179) 또는 VXLAN(UDP 4789) 포트가 개방되어 있는지 보안 팀과 확인이 필요합니다.