제어 플레인 이그레스 문제 해결하기

제어 플레인 이그레스 문제 해결하기

CUSTOMER_ROUTED 제어 플레인 이그레스 모드를 사용할 때 제어 플레인 ENI에서 네트워크 연결을 책임지는 방법과 일반적인 문제 및 해결책을 알아봐요.

출처: 문서

본문

CUSTOMER_ROUTED 제어 플레인 이그레스 모드를 사용할 때 제어 플레인 ENI에서 네트워크 연결을 책임져야 해요. 이 페이지는 일반적인 문제와 해결책을 다뤄요.

웹훅 오류 감지하기 (Detect a failing webhook)

제어 플레인이 웹훅 서버나 OIDC 프로바이더에 도달할 수 없을 때 증상은 보통 웹훅 타임아웃으로 표면화돼요. 확인하려면 웹훅을 트리거하는 리소스를 만들거나 수정하고 오류를 확인합니다:

kubectl apply -f my-resource.yaml

연결 또는 DNS 실패는 일반적으로 다음과 유사한 오류를 반환해요:

Error from server (InternalError): error when creating "my-resource.yaml": Internal error occurred:
failed calling webhook "my-webhook.example.com": failed to call webhook:
Post "https://my-webhook.example.com/validate?timeout=10s": context deadline exceeded

클러스터 전체에서 웹훅 오류에 대한 최근 이벤트를 확인할 수도 있어요:

kubectl get events --all-namespaces --field-selector reason=FailedCreate

오류가 타임아웃(context deadline exceeded)이나 connection refused라면 제어 플레인이 웹훅 엔드포인트에 도달할 수 없는 거예요. No egress route to the required endpoints, NACLs blocking webhook or control plane traffic, Security groups preventing access를 참고해 주세요.

오류가 DNS 또는 no such host 실패를 언급한다면 제어 플레인이 엔드포인트를 해석할 수 없는 거예요. DHCP option set refresh failure를 참고해 주세요.

필요한 엔드포인트로의 이그레스 라우트 없음 (No egress route to the required endpoints)

증상 (Symptoms):

• admission webhooks 시간 초과.
• OIDC 프로바이더 discovery 실패.
• 클러스터 생성 또는 업데이트가 지연됨.

원인 (Cause): 제어 플레인 네트워크 인터페이스 서브넷에 제어 플레인이 도달해야 하는 엔드포인트로 가는 작동하는 라우트가 없어요. 가장 흔하게 서브넷 라우트 테이블에 이그레스 디바이스로 가는 기본 라우트가 없어요. 또는 그 디바이스가 잘못 구성됐어요. 이그레스 디바이스는 보통 NAT 게이트웨이예요. 하지만 NAT 인스턴스, 방화벽 또는 프록시 어플라이언스, 중앙 집중식 이그레스 VPC로 가는 transit gateway일 수도 있어요.

해결책 (Solution):

클러스터가 제어 플레인 네트워크 인터페이스에 사용하는 서브넷을 식별합니다:

aws eks describe-cluster --name my-cluster \
    --query "cluster.resourcesVpcConfig.subnetIds"

각 서브넷에 대해 연결된 라우트 테이블을 확인합니다:

aws ec2 describe-route-tables \
    --filters "Name=association.subnet-id,Values=subnet-ExampleID1"

이그레스 디바이스를 가리키는 0.0.0.0/0(또는 엔드포인트를 포괄하는 라우트)에 대한 라우트가 있는지 확인합니다. 없다면 라우트를 추가합니다. 다음 예시는 NAT 게이트웨이 라우트를 추가하며, 자신의 이그레스 대상(예: transit gateway 또는 네트워크 인터페이스)으로 바꿔 주세요:

aws ec2 create-route \
    --route-table-id rtb-ExampleID \
    --destination-cidr-block 0.0.0.0/0 \
    --nat-gateway-id nat-ExampleID

웹훅 또는 제어 플레인 트래픽을 차단하는 NACL (NACLs blocking webhook or control plane traffic)

증상 (Symptoms):

• admission webhook 호출 시간 초과(오류: failed calling webhook).
• mutating 또는 validating webhook을 사용하는 Kubernetes 리소스를 만들거나 수정할 때 간헐적 실패.

원인 (Cause): 제어 플레인 ENI 서브넷의 네트워크 ACL이 웹훅 엔드포인트로의 아웃바운드 트래픽을 차단하거나 인바운드 임시 포트 반환 트래픽을 차단해요.

해결책 (Solution):

제어 플레인 서브넷과 연결된 NACL을 식별합니다:

aws ec2 describe-network-acls \
    --filters "Name=association.subnet-id,Values=subnet-ExampleID1"

다음 규칙이 존재하는지 확인합니다:

방향	프로토콜	포트 범위	대상/소스	동작
아웃바운드	TCP	443	0.0.0.0/0 (또는 webhook CIDR)	Allow
아웃바운드	TCP	10250	VPC CIDR	Allow
인바운드	TCP	1024–65535	0.0.0.0/0	Allow (임시 반환 트래픽)

참고: NACL은 무상태(stateless)예요. 인바운드 규칙에서 임시 포트(1024–65535)의 반환 트래픽을 명시적으로 허용해야 해요.

이 규칙들은 두 가지 다른 경로를 다뤄요. 포트 443 규칙은 이그레스 디바이스를 통해 VPC를 떠나는 웹훅 및 OIDC 엔드포인트로의 아웃바운드 트래픽용이에요. 포트 10250 규칙은 제어 플레인과 노드 사이에서 VPC 내에 머무는 kubelet API용이에요. 이그레스 디바이스가 없어도 포트 10250에는 영향이 없지만, 제한적인 네트워크 ACL은 이를 차단할 수 있어요.

접근을 방지하는 보안 그룹 (Security groups preventing access)

증상 (Symptoms):

• 웹훅 호출 실패.
• 제어 플레인이 노드의 kubelet API(포트 10250)에 도달할 수 없음.
• kubectl exec, kubectl logs, kubectl port-forward 실패.

원인 (Cause): 제어 플레인 ENI에 연결된 보안 그룹(클러스터 보안 그룹)이 필요한 포트의 아웃바운드 트래픽을 허용하지 않아요.

해결책 (Solution):

클러스터 보안 그룹을 식별합니다:

aws eks describe-cluster --name my-cluster \
    --query "cluster.resourcesVpcConfig.clusterSecurityGroupId"

아웃바운드 규칙이 다음을 허용하는지 확인합니다:

프로토콜	포트	대상
TCP	443	0.0.0.0/0 (webhook 엔드포인트, OIDC 프로바이더)
TCP	10250	노드 보안 그룹 또는 VPC CIDR (kubelet API)

아웃바운드 규칙이 제한적이면 필요한 트래픽에 대한 규칙을 추가합니다:

aws ec2 authorize-security-group-egress \
    --group-id sg-ExampleClusterSG \
    --protocol tcp \
    --port 443 \
    --cidr 0.0.0.0/0

참고: 엄격한 이그레스 요구 사항이 있고 웹훅 및 OIDC 엔드포인트의 IP 범위를 알고 있다면 포트 443 규칙을 0.0.0.0/0 대신 해당 특정 CIDR로 범위를 지정할 수 있어요. 포트 10250(kubelet API) 규칙은 VPC 내부용이므로 인터넷이 아닌 노드 보안 그룹이나 VPC CIDR로 범위를 지정해 주세요.

DHCP 옵션 세트 갱신 실패 (DHCP option set refresh failure)

증상 (Symptoms):

• 제어 플레인에서 DNS 해석 실패.
• DNS 조회가 필요한 클러스터 작업(OIDC discovery, webhook 해석) 실패.
• VPC DHCP 옵션이 변경되거나 제어 플레인 업데이트 후 문제 나타남.

원인 (Cause): VPC DHCP 옵션 세트가 변경됐어요. 또는 도메인 이름 서버에 AmazonProvidedDNS를 포함하지 않아요. 제어 플레인이 필요한 이름을 해석할 수 있는 다른 리졸버가 없을 수도 있어요. 제어 플레인은 DHCP 옵션 세트 변경을 자동으로 감지하고 보통 1시간 안에 새 DNS 설정을 적용해요. 제어 플레인은 클러스터 IAM 역할이 필요한 Amazon EC2 읽기 권한을 부여할 때만 이렇게 할 수 있어요.

해결책 (Solution):

VPC의 DHCP 옵션 세트를 확인합니다:

aws ec2 describe-vpcs --vpc-ids vpc-ExampleID \
    --query "Vpcs[0].DhcpOptionsId" \
    --region region-code

aws ec2 describe-dhcp-options --dhcp-options-ids dopt-ExampleID --region region-code

domain-name-servers가 AmazonProvidedDNS(VPC IPv4 CIDR 기본 주소에 2를 더한 Amazon 제공 DNS 리졸버) 또는 제어 플레인이 필요한 이름을 해석할 수 있는 다른 리졸버를 포함하는지 확인합니다.

클러스터 IAM 역할이 ec2:DescribeVpcs와 ec2:DescribeDhcpOptions를 부여하는지 확인합니다. 이 권한이 없으면 제어 플레인이 업데이트된 DHCP 옵션을 읽을 수 없고 DNS 설정을 갱신할 수 없어요. 자세한 내용은 Amazon EKS cluster IAM role 참고.

DHCP 옵션 변경 후 제어 플레인이 새 설정을 자동으로 감지해 적용할 때까지 최대 1시간을 기다려 주세요. 클러스터 업데이트나 인스턴스 교체는 필요 없어요. 1시간 후에도 DNS 해석이 여전히 실패하고 위 권한이 갖춰졌다면 AWS Support에 문의해 주세요.

IPv6 라우팅 문제 (IPv6 routing issues)

증상 (Symptoms):

• IPv6 클러스터가 외부 OIDC 또는 webhook 엔드포인트에 도달할 수 없음.
• 노드 등록은 IPv4에서 동작하지만 IPv6 서비스가 실패.

원인 (Cause): 서브넷 라우트 테이블에 egress-only 인터넷 게이트웨이로 가는 ::/0 라우트가 없거나, 보안 그룹/NACL이 IPv6 트래픽을 허용하지 않아요.

해결책 (Solution):

egress-only 인터넷 게이트웨이가 존재하고 VPC에 연결되어 있는지 확인합니다:

aws ec2 describe-egress-only-internet-gateways \
    --filters "Name=attachment.vpc-id,Values=vpc-ExampleID"

제어 플레인 서브넷의 라우트 테이블에 ::/0 라우트가 있는지 확인합니다:

aws ec2 describe-route-tables \
    --filters "Name=association.subnet-id,Values=subnet-ExampleID1" \
    --query "RouteTables[0].Routes[?DestinationIpv6CidrBlock=='::/0']"

없다면 라우트를 추가합니다:

aws ec2 create-route \
    --route-table-id rtb-ExampleID \
    --destination-ipv6-cidr-block ::/0 \
    --egress-only-internet-gateway-id eigw-ExampleID

NACL과 보안 그룹이 IPv6 아웃바운드 포트 443과 인바운드 임시 포트를 허용하는지 확인합니다.

OIDC 프로바이더에 도달할 수 없음 (OIDC provider unreachable)

증상 (Symptoms):

• IAM roles for service accounts(IRSA) 실패 — 파드가 역할을 가정할 수 없음.
• 클러스터 이벤트에 OIDC discovery 오류 표시.

원인 (Cause): 이그레스가 차단되어 제어 플레인이 OIDC 프로바이더 엔드포인트(예: oidc.eks.region-code.amazonaws.com)에 도달할 수 없어요.

해결책 (Solution):

이그레스 경로와 라우트 테이블이 아웃바운드 HTTPS 트래픽을 허용하는지 확인합니다. 이그레스 라우트가 없거나 잘못 구성된 경우 문제 해결 단계는 No egress route to the required endpoints 참고.

클러스터 보안 그룹이 0.0.0.0/0에 대한 아웃바운드 TCP 443을 허용하는지 확인합니다 (Security groups preventing access 참고).

더 알아보기 (Learn more)

• 공식 문서