Amazon EKS Hybrid Nodes 게이트웨이 문제 해결

Amazon EKS Hybrid Nodes 게이트웨이 문제 해결 (Amazon EKS Hybrid Nodes gateway troubleshooting)

이 페이지는 Amazon EKS Hybrid Nodes 게이트웨이의 일반적인 문제를 진단하고 해결하기 위한 지침을 제공해요. 각 섹션은 증상, 가능한 원인, 진단 단계, 해결 방법을 설명해요. 운영 세부 사항은 Amazon EKS Hybrid Nodes 게이트웨이 운영을 참고하세요.

출처: 문서

본문

VPC에서 하이브리드 노드의 Pod에 연결할 수 없음

VPC의 리소스(EC2 인스턴스, 로드 밸런서, Kubernetes 컨트롤 플레인 등)에서 하이브리드 노드에서 실행되는 Pod에 연결할 수 없어요.

가능한 원인:

  • VPC 라우팅 테이블 항목이 없거나 잘못된 ENI를 가리키고 있음.
  • 게이트웨이 리더 Pod가 실행 중이지 않거나 설정을 완료하지 않음.
  • Cilium VTEP가 하이브리드 노드에서 활성화되지 않았거나 구성되지 않음.
  • 게이트웨이 EC2 인스턴스에서 소스/대상 확인이 활성화되어 있음.

진단 단계:

  1. VPC 라우팅 테이블 항목 확인. 하이브리드 Pod CIDR에 대한 경로가 존재하고 활성 게이트웨이 인스턴스의 기본 ENI를 가리키는지 확인해요. 
    aws ec2 describe-route-tables \
  --route-table-ids ROUTE_TABLE_ID \
  --query "RouteTables[].Routes[?DestinationCidrBlock=='POD_CIDR']"
    경로가 없으면 게이트웨이 로그에서 라우팅 테이블 오류를 확인해요. 경로가 잘못된 ENI를 가리키면 장애 조치(failover)가 완료되지 않았을 수 있어요.
  2. 게이트웨이 Pod 상태와 리더 선출 확인. 두 개의 게이트웨이 Pod가 실행 중이고 하나가 리더 리스를 보유하고 있는지 확인해요. 
    kubectl get pods -n eks-hybrid-nodes-gateway
kubectl get lease -n eks-hybrid-nodes-gateway
    리스를 보유한 Pod가 없으면 리더 선출 문제를 참고하세요.
  3. 하이브리드 노드의 Cilium VTEP 구성 확인. CiliumVTEPConfig 리소스가 존재하고 리더의 노드 IP를 포함하는지 확인해요. 
    kubectl get ciliumvtepconfig hybrid-gateway -o yaml
    spec.endpoints[0].tunnelEndpoint가 리더 게이트웨이 노드의 IP 주소와 일치해야 해요. 리소스가 없거나 오래된 IP가 있으면 게이트웨이가 리더 설정을 완료하지 않았을 수 있어요.
  4. 소스/대상 확인 확인. 게이트웨이 EC2 인스턴스에서 소스/대상 확인이 비활성화되었는지 확인해요. 
    aws ec2 describe-instance-attribute \
  --instance-id GATEWAY_INSTANCE_ID \
  --attribute sourceDestCheck
    sourceDestCheck가 true이면 비활성화하세요. EKS Hybrid Nodes 게이트웨이 시작하기를 참고하세요.

하이브리드 노드로 가는 웹훅 호출 실패

Kubernetes API 서버가 하이브리드 노드에서 실행되는 웹훅 엔드포인트에 도달할 수 없어요. 웹훅 admission 요청이 타임아웃되거나 연결 오류를 반환해요.

가능한 원인:

  • 게이트웨이가 컨트롤 플레인에서 하이브리드 Pod로 트래픽을 라우팅하지 않음.
  • CiliumVTEPConfig 리소스가 없거나 오래된 엔드포인트 IP가 있음.

진단 단계:

  1. 컨트롤 플레인이 게이트웨이 노드 IP에 도달할 수 있는지 확인해요. 컨트롤 플레인은 VPC 라우팅 테이블로 트래픽을 보내고, 이는 게이트웨이의 ENI로 전달해요. VPC에서 하이브리드 노드의 Pod에 연결할 수 없음의 단계를 사용해 VPC 라우팅 테이블 항목이 올바른지 확인해요.
  2. CiliumVTEPConfig 리소스를 확인해요. 리소스가 존재하고 tunnelEndpoint가 현재 리더의 노드 IP와 일치하는지 확인해요. 
    kubectl get ciliumvtepconfig hybrid-gateway -o yaml
    터널 엔드포인트가 오래된 경우(이전 리더를 가리키는 경우) 게이트웨이가 리더 설정 시퀀스를 완료하지 않았을 수 있어요. CiliumVTEPConfig upsert 중 오류가 있는지 게이트웨이 로그를 확인해요.

VPC 라우팅 테이블 업데이트 실패

게이트웨이 로그에 VPC 라우팅 테이블 작업 관련 오류가 표시되고, 하이브리드 Pod CIDR에 대한 경로가 생성되거나 업데이트되지 않아요.

가능한 원인:

  • 게이트웨이의 IAM 역할에 필요한 EC2 권한이 없음.
  • 구성의 라우팅 테이블 ID가 잘못되었거나 라우팅 테이블이 존재하지 않음.
  • 게이트웨이가 EC2 API 엔드포인트에 도달할 수 없음.

진단 단계:

  1. IAM 권한 확인. 게이트웨이에는 다음 IAM 작업이 필요해요.
    • ec2:DescribeRouteTables
    • ec2:CreateRoute
    • ec2:ReplaceRoute
    • ec2:DescribeInstances 게이트웨이 노드의 인스턴스 프로파일 또는 Pod Identity 구성에 연결된 IAM 역할을 확인해요.
  2. 구성의 라우팅 테이블 ID 확인. 게이트웨이 배포에서 ROUTE_TABLE_IDS 환경 변수에 유효한 라우팅 테이블 ID가 포함되어 있는지 확인해요. 
    kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].env}' | jq .
    라우팅 테이블 ID가 VPC에 존재하는지 확인해요. 
    aws ec2 describe-route-tables --route-table-ids ROUTE_TABLE_ID
  3. 라우팅 테이블 오류가 있는지 게이트웨이 로그 확인. 라우팅 테이블 작업 관련 오류 메시지를 찾아요. 
    kubectl logs -n eks-hybrid-nodes-gateway LEADER_POD | grep -i "route table"
    일반적인 오류 메시지:
    • Failed to verify route table access – 게이트웨이가 라우팅 테이블을 설명할 수 없음. IAM 권한과 라우팅 테이블 ID를 확인하세요.
    • Failed to update route tables – 게이트웨이가 경로를 만들거나 교체할 수 없음. IAM 권한을 확인하세요.
    • failed to access route table – 라우팅 테이블 ID가 잘못되었거나 IAM 역할에 ec2:DescribeRouteTables가 없을 수 있음.

게이트웨이 Pod 시작 실패 또는 비정상

게이트웨이 Pod가 CrashLoopBackOff, Error, Pending 상태이거나 상태 엔드포인트가 오류를 반환해요.

가능한 원인:

  • 필수 환경 변수(VPC_CIDR, POD_CIDRS, ROUTE_TABLE_IDS)가 설정되지 않음.
  • 게이트웨이 노드에서 IP 포워딩이 활성화되지 않음.
  • 노드 레이블 또는 anti-affinity 제약 조건이 스케줄링을 방지함.

진단 단계:

  1. Pod 로그 확인. 실패하는 Pod의 로그를 확인해 오류를 식별해요. 
    kubectl logs -n eks-hybrid-nodes-gateway LEADER_POD
  2. 필수 환경 변수 확인. 게이트웨이에는 NODE_IP, VPC_CIDR, POD_CIDRS가 필요해요. 어느 하나라도 없으면 게이트웨이가 즉시 종료돼요. Pod spec을 확인해요. 
    kubectl get pod -n eks-hybrid-nodes-gateway LEADER_POD -o jsonpath='{.spec.containers[0].env}' | jq .
    • NODE_IP는 Pod spec의 status.hostIP에서 자동으로 설정돼요. 비어 있으면 Pod가 아직 노드에 스케줄링되지 않았을 수 있어요.
    • VPC_CIDR과 POD_CIDRS는 Helm 값에서 오며, 올바르게 설정되었는지 확인해요.
  3. IP 포워딩 확인. 게이트웨이는 시작 시 IP 포워딩이 활성화되었는지 확인하고 그렇지 않으면 종료해요. Pod 로그에서 IP forwarding is not enabled 오류 메시지를 찾아요. 노드에서 IP 포워딩을 활성화해요. 
    # Check current setting
cat /proc/sys/net/ipv4/ip_forward

# Enable if not set
sudo sysctl -w net.ipv4.ip_forward=1
    영구 설정의 경우 kubelet을 통해 IP 포워딩을 구성하거나 /etc/sysctl.d/에 net.ipv4.ip_forward=1을 추가하세요.
  4. 노드 레이블 및 스케줄링 제약 조건 확인. 게이트웨이 Pod는 hybrid-gateway-node=true 레이블이 있는 노드가 필요해요. Pod anti-affinity는 각 Pod가 별도의 노드에서 실행되도록 보장해요. Pod가 Pending이면 스케줄링 문제를 확인해요. 
    kubectl describe pod -n eks-hybrid-nodes-gateway LEADER_POD
    노드 부족, 누락된 레이블, anti-affinity 충돌을 나타내는 이벤트를 찾아요.

리더 선출 문제

게이트웨이 Pod가 실행 중이지만 어떤 Pod도 리더 리스를 획득하지 못하거나, 리더십 전환이 자주 발생해요.

가능한 원인:

  • Lease 객체에 대한 RBAC 권한이 없음.
  • 게이트웨이 Pod와 Kubernetes API 서버 사이의 네트워크 연결이 불안정함.
  • 리더 선출 매개변수가 잘못 구성됨.

진단 단계:

  1. Lease 객체 확인. Lease가 존재하고 현재 보유자를 검사해요. 
    kubectl get lease -n eks-hybrid-nodes-gateway hybrid-gateway-leader -o yaml
    spec.holderIdentity 필드는 현재 리더를 보여줘요. spec.renewTime은 Lease가 마지막으로 갱신된 시각을 보여줘요. renewTime이 오래되었다면 리더가 API 서버에 대한 연결을 잃었을 수 있어요.
  2. RBAC 권한 확인. 게이트웨이 서비스 계정은 게이트웨이 네임스페이스에서 Lease 객체를 get, create, update할 권한이 필요해요. Role과 RoleBinding을 확인해요. 
    kubectl get role -n eks-hybrid-nodes-gateway
kubectl get rolebinding -n eks-hybrid-nodes-gateway
    Role에는 coordination.k8s.io API 그룹의 leases 리소스에 대한 get, create, update 동사가 포함되어야 해요.
  3. 리스 오류가 있는지 Pod 로그 확인. Pod 로그에서 리더 선출 오류를 찾아요. 
    kubectl logs -n eks-hybrid-nodes-gateway LEADER_POD | grep -i "leader\|lease"
    일반적인 문제:
    • Failed to acquire lease – Pod가 Lease 객체를 만들거나 업데이트할 수 없음. RBAC 권한을 확인하세요.
    • Leadership ended 다음에 Leader setup complete 메시지가 자주 표시됨 – 리더가 리스를 잃고 다시 획득하고 있음. 이는 Pod와 API 서버 사이의 네트워크 불안정을 나타낼 수 있어요. --leader-election-lease-duration을 늘리는 것을 고려하세요.
  4. 리더 선출 매개변수 확인. 구성된 값을 확인해요. 
    kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].args}'
    --leader-election-renew-deadline이 --leader-election-lease-duration보다 작은지 확인하세요. 갱신 마감이 리스 기간을 초과하면 리더는 갱신하기 전에 리스를 잃어요. 자세한 내용은 리더 선출 튜닝을 참고하세요.

일반적인 오류 메시지

다음 표는 게이트웨이 Pod 로그에서 볼 수 있는 오류 메시지와 그 해결 방법을 나열해요.

오류 메시지 원인 해결 방법
IP forwarding is not enabled 게이트웨이 노드에서 커널 매개변수 net.ipv4.ip_forward가 1로 설정되지 않음. kubelet 구성으로 또는 sysctl -w net.ipv4.ip_forward=1 실행으로 IP 포워딩을 활성화하세요.
Failed to setup VXLAN 게이트웨이가 VXLAN 네트워크 인터페이스를 만들 수 없음. 일반적으로 Pod에 NET_ADMIN 기능(capability)이 없을 때 발생. Deployment spec의 securityContext.capabilities.add에 NET_ADMIN이 포함되었는지 확인하세요. Helm 차트가 올바르게 배포되었는지 확인하세요.
Failed to verify route table access 게이트웨이가 시작 시 하나 이상의 VPC 라우팅 테이블을 설명할 수 없음. IAM 역할에 ec2:DescribeRouteTables 권한이 있고 구성의 라우팅 테이블 ID가 올바른지 확인하세요.
Failed to update route tables 게이트웨이가 VPC 라우팅 테이블에서 경로를 만들거나 교체할 수 없음. IAM 역할에 ec2:CreateRoute 및 ec2:ReplaceRoute 권한이 있는지 확인하세요.
Failed to create route table manager 게이트웨이가 AWS EC2 클라이언트를 초기화하거나 인스턴스의 기본 ENI를 검색할 수 없음. IAM 역할에 ec2:DescribeInstances 권한이 있고 인스턴스 메타데이터 서비스(IMDS)에 접근 가능한지 확인하세요.
NODE_IP is required NODE_IP 환경 변수 또는 --node-ip 플래그가 설정되지 않음. Pod spec이 fieldRef를 사용해 status.hostIP에서 NODE_IP를 설정하는지 확인하세요. Helm 차트가 올바르게 배포되었는지 확인하세요.
Invalid NODE_IP NODE_IP에 제공된 값이 유효한 IP 주소가 아님. Pod spec의 NODE_IP 환경 변수 값을 확인하세요.
pod-cidrs and vpc-cidr are required POD_CIDRS 또는 VPC_CIDR 환경 변수가 비어 있음. 설치 중 podCIDRs 및 vpcCIDR Helm 값을 설정하세요.
No valid route table IDs provided ROUTE_TABLE_IDS 값이 설정되었지만 파싱 후 유효한 라우팅 테이블 ID가 없음. routeTableIDs Helm 값의 형식 오류를 확인하세요. 라우팅 테이블 ID는 쉼표로 구분해야 해요(예: rtb-abc123,rtb-def456).
Failed to auto-detect AWS region 게이트웨이가 EC2 인스턴스 메타데이터에서 AWS 리전을 검색할 수 없음. 인스턴스 메타데이터 서비스(IMDS)에 접근 가능한지 확인하세요. 또는 --aws-region 플래그나 AWS_REGION 환경 변수를 명시적으로 설정하세요.
Failed to auto-detect AWS instance ID 게이트웨이가 EC2 인스턴스 메타데이터에서 인스턴스 ID를 검색할 수 없음. 인스턴스 메타데이터 서비스(IMDS)에 접근 가능한지 확인하세요. 또는 --aws-instance-id 플래그나 AWS_INSTANCE_ID 환경 변수를 명시적으로 설정하세요.
CiliumNode has no internal IP 하이브리드 노드의 CiliumNode 객체에 spec에 내부 IP 주소가 없음. 하이브리드 노드가 올바르게 등록되었고 Cilium 에이전트가 실행 중인지 확인하세요. 해당 노드의 CiliumNode 리소스를 확인하세요.
CiliumNode has no pod CIDRs allocated 하이브리드 노드의 CiliumNode 객체에 Cilium IPAM이 할당한 Pod CIDR이 없음. 하이브리드 노드에서 Cilium IPAM이 올바르게 구성되었는지 확인하세요. 노드의 IPAM 상태에 대한 CiliumNode 리소스를 확인하세요.
Failed to upsert CiliumVTEPConfig 게이트웨이가 CiliumVTEPConfig 커스텀 리소스를 만들거나 업데이트할 수 없음. CRD가 클러스터에 설치되었고 게이트웨이 서비스 계정에 CiliumVTEPConfig 리소스를 관리할 권한이 있는지 확인하세요.
Unable to create manager controller-runtime 매니저가 초기화에 실패. 추가 콘텍스트에 대해 Pod 로그를 확인하세요. 일반적인 원인은 kubeconfig가 잘못되었거나 Kubernetes API 서버에 연결할 수 없는 것.
Failed to add gateway setup 리더 선출 실행 가능 항목이 컨트롤러 매니저에 등록될 수 없음. 일반적으로 내부 오류. 추가 콘텍스트에 대해 전체 Pod 로그를 확인하고 GitHub 저장소에 문제를 보고하세요.
Unable to create Node controller CiliumNode reconciler가 컨트롤러 매니저에 등록될 수 없음. 추가 콘텍스트에 대해 Pod 로그를 확인하세요. CiliumNode CRD가 클러스터에 설치되었는지 확인하세요.
Problem running manager 컨트롤러 매니저가 예기치 않게 종료. 근본 오류에 대해 Pod 로그를 확인하세요. 일반적인 원인은 Kubernetes API 서버에 대한 연결 손실 또는 메트릭/상태 프로브 바인드 주소의 포트 충돌.
failed to access route table 게이트웨이가 시작 확인 단계에서 특정 VPC 라우팅 테이블을 설명할 수 없음. IAM 역할에 ec2:DescribeRouteTables 권한이 있고 라우팅 테이블 ID가 올바른지 확인하세요. 라우팅 테이블은 게이트웨이 인스턴스와 같은 리전에 있어야 해요.

관련 주제

  • Amazon EKS Hybrid Nodes 게이트웨이 – 게이트웨이 아키텍처와 사용 사례 개요.
  • EKS Hybrid Nodes 게이트웨이 시작하기 – 사전 요구 사항 및 설치 지침.
  • Amazon EKS Hybrid Nodes 게이트웨이 구성 참조 – Helm 값, CLI 플래그, 환경 변수의 완전한 참조.
  • Amazon EKS Hybrid Nodes 게이트웨이 운영 – 모니터링, 장애 조치 동작, 확장 지침.

더 알아보기 (Learn more)