실패한 웹후크 감지 필수 엔드포인트로 송신 경로 없음 웹후크 또는 컨트롤 플레인 트래픽을 차단하는 NACL 액세스를 차단하는 보안 그룹 DHCP 옵션 세트 새로 고침 실패 IPv6 라우팅 문제 OIDC 공급자에 연결할 수 없음

컨트롤 플레인 송신 문제 해결

CUSTOMER_ROUTED 컨트롤 플레인 송신 모드를 사용하는 경우 컨트롤 플레인 ENI의 네트워크 연결을 직접 관리해야 합니다. 이 페이지에서는 일반적인 문제 및 해결 방법을 다룹니다.

실패한 웹후크 감지

컨트롤 플레인이 웹후크 서버 또는 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) 또는 연결 거부인 경우 컨트롤 플레인이 웹후크 엔드포인트에 도달할 수 없습니다. 필수 엔드포인트로 송신 경로 없음, 웹후크 또는 컨트롤 플레인 트래픽을 차단하는 NACL 및 액세스를 차단하는 보안 그룹 섹션을 참조하세요.
오류에 DNS 또는 해당 호스트 없음 오류가 언급된 경우 컨트롤 플레인이 엔드포인트를 확인할 수 없습니다. DHCP 옵션 세트 새로 고침 실패을(를) 참조하세요.

필수 엔드포인트로 송신 경로 없음

증상:

승인 웹후크 제한 시간이 초과됩니다.
OIDC 공급자 검색이 실패합니다.
클러스터 생성 또는 업데이트가 중지됩니다.

원인:

컨트롤 플레인 네트워크 인터페이스 서브넷에 컨트롤 플레인이 도달해야 하는 엔드포인트에 대한 유효한 경로가 없습니다. 가장 일반적으로는 서브넷 라우팅 테이블에 송신 디바이스에 대한 기본 경로가 없습니다. 또는 해당 디바이스가 잘못 구성되었습니다. 송신 디바이스는 일반적으로 NAT 게이트웨이입니다. 그러나 송신 디바이스가 NAT 인스턴스, 방화벽 또는 프록시 어플라이언스, 또는 중앙 집중식 송신 VPC로의 전송 게이트웨이일 수 있습니다.

해결 방법:

클러스터가 컨트롤 플레인 네트워크 인터페이스에 사용하는 서브넷을 식별합니다.
```
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 게이트웨이 경로를 추가합니다. 자체 송신 대상(예: 전송 게이트웨이 또는 네트워크 인터페이스)으로 대체합니다.
```
aws ec2 create-route \
    --route-table-id rtb-ExampleID \
    --destination-cidr-block 0.0.0.0/0 \
    --nat-gateway-id nat-ExampleID
```

웹후크 또는 컨트롤 플레인 트래픽을 차단하는 NACL

증상:

승인 웹후크 직접 호출 제한 시간 초과(오류: failed calling webhook).
변형 또는 검증 웹후크를 사용하는 Kubernetes 리소스를 생성하거나 수정할 때 간헐적으로 실패합니다.

원인:

컨트롤 플레인 ENI 서브넷의 네트워크 ACL이 웹후크 엔드포인트로의 아웃바운드 트래픽을 차단하거나 인바운드 임시 포트 반환 트래픽을 차단합니다.

해결 방법:

컨트롤 플레인 서브넷과 연결된 NACL을 식별합니다.


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

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

Direction	프로토콜	포트 범위	대상/소스	작업
아웃바운드	TCP	443	0.0.0.0/0(또는 웹후크 CIDR)	허용
아웃바운드	TCP	10250	VPC CIDR	허용
인바운드	TCP	1024–65535	0.0.0.0/0	허용(임시 반환 트래픽)

참고

NACL은 스테이트리스입니다. 인바운드 규칙에서 임시 포트(1024~65535)의 반환 트래픽을 명시적으로 허용해야 합니다.

이러한 규칙은 두 가지 경로를 다룹니다. 포트 443 규칙은 송신 디바이스를 통해 VPC를 벗어나는 웹후크 및 OIDC 엔드포인트 측 아웃바운드 트래픽에 적용됩니다. 포트 10250 규칙은 VPC 내에서 컨트롤 플레인과 노드 간에 유지되는 kubelet API에 적용됩니다. 누락된 송신 디바이스는 포트 10250에 영향을 주지 않지만 제한적인 네트워크 ACL은 이를 차단할 수 있습니다.

액세스를 차단하는 보안 그룹

증상:

웹후크 직접 호출이 실패합니다.
컨트롤 플레인이 노드(포트 10250)의 kubelet API에 도달하지 못합니다.
kubectl exec, kubectl logs 또는 kubectl port-forward가 실패합니다.

원인:

컨트롤 플레인 ENI에 연결된 보안 그룹(클러스터 보안 그룹)이 필요한 포트에서 아웃바운드 트래픽을 허용하지 않습니다.

해결 방법:

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


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

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

프로토콜	포트	Destination
TCP	443	0.0.0.0/0(웹후크 엔드포인트, 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 옵션 세트 새로 고침 실패

증상:

컨트롤 플레인에서 DNS 확인이 실패합니다.
DNS 조회(OIDC 검색, 웹후크 확인)가 필요한 클러스터 작업이 실패합니다.
VPC DHCP 옵션을 변경하거나 컨트롤 플레인을 업데이트한 후 문제가 나타납니다.

원인:

VPC DHCP 옵션 세트가 변경되었습니다. 또는 해당 도메인 이름 서버에 AmazonProvidedDNS가 포함되어 있지 않습니다. 컨트롤 플레인에 필요한 이름을 확인할 수 있는 다른 해석기가 없을 수도 있습니다. 컨트롤 플레인은 DHCP 옵션 세트 변경을 자동으로 감지하고 일반적으로 1시간 이내에 새 DNS 설정을 적용합니다. 컨트롤 플레인은 클러스터 IAM 역할이 필요한 Amazon EC2 읽기 권한을 부여하는 경우에만 이 작업을 수행할 수 있습니다.

해결 방법:

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 클러스터 IAM 역할을 참조하세요.
DHCP 옵션을 변경한 후 컨트롤 플레인이 새 설정을 자동으로 감지하고 적용하는 데 최대 1시간이 걸립니다. 클러스터 업데이트나 인스턴스 교체는 필요하지 않습니다. 위의 권한이 있지만 1시간 후에도 여전히 DNS 확인이 실패하는 경우 AWS Support에 문의하세요.

IPv6 라우팅 문제

증상:

IPv6 클러스터가 외부 OIDC 또는 웹후크 엔드포인트에 연결할 수 없습니다.
노드 등록이 IPv4를 통해서는 작동하지만 IPv6 서비스는 실패합니다.

원인:

서브넷 라우팅 테이블에 송신 전용 인터넷 게이트웨이에 대한 ::/0 경로가 없거나 보안 그룹/NACL이 IPv6 트래픽을 허용하지 않습니다.

해결 방법:

송신 전용 인터넷 게이트웨이가 존재하고 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 및 보안 그룹이 포트 443에서 IPv6 아웃바운드 및 인바운드 임시 포트를 허용하는지 확인합니다.

OIDC 공급자에 연결할 수 없음

증상:

IAM roles for service accounts(IRSA) 실패 - 포드가 역할을 수임할 수 없습니다.
클러스터 이벤트에 OIDC 검색 오류가 표시됩니다.

원인:

송신이 차단되어 있기 때문에 컨트롤 플레인이 OIDC 공급자 엔드포인트(예: oidc.eks.region-code.amazonaws.com)에 도달할 수 없습니다.

해결 방법:

송신 경로 및 라우팅 테이블이 아웃바운드 HTTPS 트래픽을 허용하는지 확인합니다. 송신 경로가 누락 또는 잘못 구성된 경우의 문제 해결 단계는 필수 엔드포인트로 송신 경로 없음 섹션을 참조하세요.
클러스터 보안 그룹이 0.0.0.0/0에 대한 아웃바운드 TCP 443을 허용하는지 확인합니다(액세스를 차단하는 보안 그룹 참조).

📝 GitHub에서 이 페이지 편집

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

컨트롤 플레인 송신

AutoScaling