문제 해결 및 진단

원문 보기 위키 갱신 2026.10.11

Calico 오픈소스 클러스터에서 문제를 만났을 때 진단 정보를 모으고 로그를 확인하는 방법을 안내해요. BGP 피어 상태 점검, NetworkManager 설정, 자주 만나는 오류 패턴까지 차근차근 살펴봐요. 문제가 해결되지 않으면 GitHub에 이슈를 올려 보고할 수도 있어요.

출처: 문서

본문

로그와 진단

슈퍼유저 권한으로 calicoctl 커맨드 라인 도구를 사용하면 진단 정보를 수집할 수 있어요. 예를 들면 다음과 같아요:

sudo calicoctl node diags

로그를 보려면 다음 명령을 사용하세요:

kubectl logs -n calico-system <pod_name>

일부 Calico 컴포넌트의 디버그 로그를 보려면, 연관된 환경 변수를 통해 LogSeverityScreen을 설정하세요.

문제를 보고하려면 GitHub에 이슈를 열어 주세요.

BGP 피어 상태 확인하기

같은 호스트 안의 컨테이너 사이, 그리고 컨테이너와 인터넷 사이에는 연결이 되는데 서로 다른 호스트의 컨테이너 사이에만 연결이 안 된다면, BGP 설정에 문제가 있을 가능성이 커요.

각 호스트에서 calicoctl node status를 확인해 보세요. 다음과 같은 출력이 포함되어 있어야 해요:

Calico process is running.

IPv4 BGP status
+--------------+-------------------+-------+----------+-------------+
| PEER ADDRESS |     PEER TYPE     | STATE |  SINCE   |    INFO     |
+--------------+-------------------+-------+----------+-------------+
| 172.17.8.102 | node-to-node mesh | up    | 23:30:04 | Established |
+--------------+-------------------+-------+----------+-------------+

IPv6 BGP status
No IPv6 peers found.

또는 CalicoNodeStatus 리소스를 만들어서 노드의 BGP 세션 상태를 확인할 수도 있어요.

이런 출력이 보이지 않는다면 다음 항목을 확인해 보세요.

호스트 사이에 IP 연결성이 있는지 확인하세요.
네트워크가 TCP 포트 179에서 필요한 BGP 트래픽을 허용하는지 확인하세요.

NetworkManager 설정하기

Calico 네트워킹을 사용하기 전에 NetworkManager를 먼저 설정하세요.

NetworkManager는 컨테이너 연결을 위해 Calico veth 페어가 앵커되는, 기본 네트워크 네임스페이스에 있는 인터페이스의 라우팅 테이블을 건드려요. 이 때문에 Calico 에이전트가 제대로 라우팅하지 못할 수 있어요.

NetworkManager가 이 인터페이스들을 방해하지 못하게 하려면 /etc/NetworkManager/conf.d/calico.conf 경로에 다음 설정 파일을 만드세요:

[keyfile]
unmanaged-devices=interface-name:cali*;interface-name:tunl*;interface-name:vxlan.calico;interface-name:vxlan-v6.calico;interface-name:wireguard.cali;interface-name:wg-v6.cali

sudo calicoctl 실행 시 오류

sudo로 명령을 실행할 때는 여러분의 환경 변수가 sudo 환경으로 넘어가지 않는다는 점을 기억하세요. 환경 변수를 포함하려면 -E 플래그를 붙여 sudo를 실행해야 해요:

sudo -E calicoctl node diags

아니면 다음처럼 sudo 명령에 환경 변수를 직접 지정할 수도 있어요:

sudo ETCD_ENDPOINTS=http://172.25.0.1:2379 calicoctl node run

또한 연결 정보를 환경 변수 대신 설정 파일로 지정할 수 있다는 점도 기억해 두세요. 자세한 내용은 calicoctl 설치를 참고하세요.

Error: calico/node is not ready: BIRD is not ready: BGP not established with 10.0.0.1

대부분의 경우, 쿠버네티스에서 이 "unready" 상태 오류는 특정 피어가 클러스터 안에서 도달할 수 없다는 뜻이에요. 두 피어 사이의 BGP 연결이 환경에서 허용되어 있는지 확인하세요.

이 오류는 node-to-node mesh에 구성된 비활성 Node 리소스가 있을 때도 발생할 수 있어요. 이럴 때는 오래된 노드를 폐기(decommission)하면 해결돼요.

리눅스 conntrack 테이블 공간 부족

리눅스 시스템에서 흔한 문제 중 하나는 conntrack 테이블 공간이 부족해지는 것이에요. 이러면 iptables 성능이 나빠질 수 있어요. 한 호스트에서 많은 워크로드를 돌리거나, 워크로드가 많은 TCP 연결이나 양방향 UDP 스트림을 만들 때 생기기 쉬워요. 이 문제를 피하려면 다음 명령으로 conntrack 테이블 크기를 늘리는 걸 권장해요:

sysctl -w net.netfilter.nf_conntrack_max=1000000
echo "net.netfilter.nf_conntrack_max=1000000" >> /etc/sysctl.conf

더 알아보기 (Learn more)

진단 정보 수집은 문제 해결의 출발점이에요. 같은 호스트 안에서는 통신이 되는데 호스트 사이에서만 안 된다면 BGP 설정부터 의심해 보세요. 그래도 해결되지 않으면 Calico GitHub 이슈 트래커에 상황을 공유해 보세요.