본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

Windows용 Calico 문제 해결하기

원문 보기 위키 갱신

Calico for Windows 클러스터에서 자주 마주치는 문제와 진단 절차, 로그 위치를 정리한 가이드예요. HNS 네트워크와 엔드포인트 확인부터 kubelet·API 서버 연결 문제, BGP 상태 점검까지 순서대로 살펴봐요. 문제가 생겼을 때 이 문서를 체크리스트처럼 활용해 보세요.

출처: 문서

본문

유용한 문제 해결 명령어

HNS 네트워크 살펴보기

Calico CNI 플러그인을 사용할 때는 각 Calico IPAM 블록(또는 host-local IPAM 모드에서는 단일 podCIDR)이 HNS l2bridge 네트워크로 표현돼요. 다음 명령으로 네트워크를 살펴보세요.

ipmo -DisableNameChecking C:\CalicoWindows\libs\hns\hns.psm1
Get-HNSNetwork

파드 엔드포인트 살펴보기

다음 명령으로 시스템의 HNS 엔드포인트를 볼 수 있어요. Calico로 네트워킹된 파드마다 HNS 엔드포인트가 하나씩 있어야 해요:

ipmo -DisableNameChecking C:\CalicoWindows\libs\hns\hns.psm1
Get-HNSEndpoint

문제 해결

Windows 파드에서 kubectl exec가 타임아웃으로 실패함

Windows 방화벽(그리고 네트워크 방화벽이나 클라우드 보안 그룹)이 포트 10250의 호스트 트래픽을 허용하는지 확인하세요.

kubelet이 등록에 실패하고, 로그에서 node not found를 불폼함

클라우드 프로바이더(예: AWS 클라우드 프로바이더)와 노드 구성이 어긋나서 생길 수 있어요. 예를 들어 AWS 클라우드 프로바이더는 노드의 nodename이 자기 사설 도메인 이름과 일치할 것을 요구해요.

Calico for Windows 초기화 후 AWS 메타데이터 서버에 더 이상 접근할 수 없음

Microsoft가 작업 중인 알려진 Windows 이슈예요. vSwitch가 만들어질 때 메타데이터 서버로 가는 라우트가 사라져요. 우회 방법으로 다음을 실행해서 라우트를 직접 다시 추가하세요:

New-NetRoute -DestinationPrefix 169.254.169.254/32 -InterfaceIndex <interface-index\>

<interface-index\>는 다음 명령이 보여주는 "vEthernet (Ethernet 2)" 디바이스의 인덱스예요.

Get-NetAdapter

설치가 "Waiting for Calico initialization to finish"에서 멈춤

Windows의 Execution protection 기능 때문일 수 있어요. Ctrl-C로 설치를 종료하고, 스크립트 차단을 해제한 다음, uninstall-calico.ps1을 실행하고 이어서 install-calico.ps1을 실행하세요.

Windows Server 2019 insider preview: 노드 재부팅 후 Calico for Windows가 시작에 실패하고, tigera-node.err.log 파일에 오류가 있음

Windows 노드를 재부팅한 뒤 파드 스케줄링이 실패하고, kubelet 로그에 "timed out waiting for interface matching the management IP (169.254.57.5) of network" 같은 CNI 오류가 남아요.

(IP 주소는 다를 수 있지만 항상 169.254.x.x 주소예요.)

우회 방법:

  • stop-calico.ps1과 start-calico.ps1 스크립트로 Calico for Windows를 중지했다가 다시 시작해요
  • HNS 네트워크가 부팅 직전에 임시 자가 할당 주소를 가져가고, 올바른 IP가 알려진 뒤에도 갱신되지 않을 때가 있어요. 노드를 한 번 더 재부팅하면 보통 문제가 해결돼요.

Invoke-Webrequest가 TLS 오류로 실패함

"The request was aborted: Could not create SSL/TLS secure channel" 오류는 보통 Windows가 기본으로 TLS v1.2(많은 웹사이트가 요구해요)를 지원하지 않는다는 뜻이에요. TLS v1.2를 켜려면 다음 명령을 실행하세요:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

kubelet이 API 서버와의 접촉을 계속 실패함

Calico for Windows를 설치할 때 kubelet이 이미 실행 중이었다면, 컨테이너 vSwitch 생성으로 kubelet이 연결을 잃고 API 서버에 계속 재접속에 실패할 수 있어요. 해결하려면 Calico for Windows 설치 후에 kubelet을 재시작하세요.

Linux 노드와 Windows 노드의 파드 사이에 연결성이 없음

AWS를 사용 중이라면 노드에 할당된 인터페이스에서 source/dest check가 꺼져 있는지 확인하세요. 이렇게 해야 노드가 로컬 파드를 대신해서 트래픽을 포워딩할 수 있어요. AWS에서 "Change Source/Dest. Check" 옵션은 선택한 네트워크 인터페이스의 Actions 메뉴에 있어요.

Calico 네트워킹을 사용 중이라면 사용 중인 Calico IP 풀에 IPIP 모드가 꺼져 있는지("Never"로 설정) 확인하세요. Windows는 IPIP를 지원하지 않아요. IP 풀을 확인하려면 calicoctl을 쓸 수 있어요:

calicoctl get ippool -o yaml

IPIP가 비활성화된 IP 풀의 출력 예시예요:

apiVersion: projectcalico.org/v3
items:
  - apiVersion: projectcalico.org/v3
    kind: IPPool
    metadata:
      creationTimestamp: 2018-11-26T15:37:39Z
      name: default-ipv4-ippool
      resourceVersion: '172'
      uid: 34db7316-f191-11e8-ad7d-02850eebe6c4
    spec:
      blockSize: 26
      cidr: 192.168.0.0/16
      disabled: true
      ipipMode: Never
      natOutgoing: true

Felix가 시작되지만 로그를 출력하지 않음

기본적으로 Felix는(데이터스토어 구성이 의도적으로 로깅을 껐을 수 있으니) 데이터스토어에 연결될 때까지 로깅을 미뤄요. 시작 시점부터 로깅하려면 FELIX_LOGSEVERITYSCREEN 환경 변수를 "info" 또는 "debug" 레벨로 업데이트하세요.

Calico BGP 모드: 연결성 문제, Linux calico/node 파드가 unready를 보고함

어떤 헬스 체크가 실패했는지 보여주는 상세 헬스 출력을 확인하세요:

kubectl describe pod -n calico-system <calico-node-pod>

SECONDARY: Calico 설치가 operator 관리 방식이 아니라면 calico-system 대신 kube-system 네임스페이스를 사용하세요.

헬스 체크가 BGP 피어 실패를 보고하면, 피어의 IP 주소가 노드의 기대 IP이거나 외부 BGP 피어인지 확인하세요. 실패한 피어링의 IP가 Windows 노드라면:

  • 노드가 살아 있고 IP로 도달 가능한지 확인해요

  • RemoteAccess 서비스가 설치되어 있고 실행 중인지 확인해요:

    Get-Service | ? Name -EQ RemoteAccess

  • 구성된 로그 디렉터리(기본 C:\CalicoWindows\logs)에서 confd 서비스 로그의 오류를 확인해요.

Windows 호스트에서 BGP 상태 살펴보기

Windows BGP 라우터는 구성과 상태를 PowerShell 커맨드렛으로 노출해요.

BGP 피어 보기:

Get-BgpPeer

출력 예시:

PeerName LocalIPAddress PeerIPAddress PeerASN OperationMode ConnectivityStatus
-------- -------------- ------------- ------- ------------- ------------------
Mesh_172_20_48_43 172.20.55.101 172.20.48.43 64512 Mixed Connected
Mesh_172_20_51_170 172.20.55.101 172.20.51.170 64512 Mixed Connected
Mesh_172_20_54_3 172.20.55.101 172.20.54.3 64512 Mixed Connected
Mesh_172_20_58_252 172.20.55.101 172.20.58.252 64512 Mixed Connected
For an established peering, the ConnectivityStatus column should be "Connected".

다른 호스트에서 학습한 라우트 살펴보기:

Get-BgpRouteInformation -Type all

출력 예시:

DestinationNetwork NextHop LearnedFromPeer State LocalPref MED
------------------ ------- --------------- ----- --------- ---
10.243.128.192/26 172.20.58.252 Mesh_172_20_58_252 Best 100
10.244.115.128/26 172.20.48.43 Mesh_172_20_48_43 Best 100
10.244.128.192/26 172.20.58.252 Mesh_172_20_58_252 Best 100

활성 라우트는 State가 "Best"로 보여야 해요. State가 "Unresolved"인 라우트는 BGP 라우터가 피어로 가는 라우트를 해석하지 못했다는 뜻이고, 그 라우트는 사용되지 않아요. BGP 라우터가 시작된 뒤 네트워킹 상태가 바뀌면 이런 일이 생길 수 있어요. BGP 라우터를 재시작하면 문제가 해결될 수 있어요:

Restart-Service RemoteAccess

이 호스트가 내보내는 라우트를 보려면:

(Get-BgpCustomRoute).Network

출력 예시:

10.243.214.152/29
10.243.214.160/29
10.243.214.168/29
10.244.42.0/26

더 알아보기 (Learn more)

Windows 쪽 문제는 대부분 HNS 상태, 방화벽/보안 그룹, IPIP 미지원 세 가지로 좁혀져요. BGP 이슈는 Get-BgpPeer와 Get-BgpRouteInformation 출력이 결정적인 단서를 줘요. Felix 로그가 조용하다면 FELIX_LOGSEVERITYSCREEN을 info 이상으로 올려 보세요.