제어 플레인 이그레스 라우팅 구성하기

기본적으로 Amazon EKS는 Kubernetes 제어 플레인에서 VPC의 리소스로 나가는 이그레스 네트워킹을 관리해요. 제어 플레인 이그레스 라우팅을 사용해 이 동작을 변경하고 네트워크 경로를 직접 관리하는 방법을 알아봐요. 자체 NAT 게이트웨이, 방화벽, 검사 어플라이언스를 통해 라우팅할 수 있어요.

출처: 문서

본문

제어 플레인 이그레스 라우팅을 사용하면 제어 플레인 탄력적 네트워크 인터페이스(ENI)의 트래픽이 VPC 리소스에 도달하는 방식을 완전히 제어할 수 있어요.

이그레스 라우팅 모드 (Egress routing modes)

Amazon EKS는 다음 제어 플레인 이그레스 라우팅 모드를 지원해요:

모드 설명

AWS_MANAGED 기본 동작. Amazon EKS가 제어 플레인 ENI의 이그레스 경로를 관리해요. 제어 플레인 트래픽에 대해 NAT 게이트웨이 또는 기타 라우팅 인프라를 구성할 필요가 없어요.

CUSTOMER_ROUTED VPC 서브넷에서 제어 플레인의 이그레스 경로를 직접 관리해요. 제어 플레인이 필요한 엔드포인트(웹훅 서버, OIDC 프로바이더, 기타 리소스 등)에 도달할 수 있도록 보장할 책임이 있어요. NAT 게이트웨이, NAT 인스턴스, transit gateway, 방화벽 어플라이언스 같은 이그레스 경로를 제공합니다. 이 트래픽을 허용하는 라우트 테이블, 네트워크 ACL, 보안 그룹 규칙도 구성해요.

모드	설명
`AWS_MANAGED`	기본 동작. Amazon EKS가 제어 플레인 ENI의 이그레스 경로를 관리해요. 제어 플레인 트래픽에 대해 NAT 게이트웨이 또는 기타 라우팅 인프라를 구성할 필요가 없어요.
`CUSTOMER_ROUTED`	VPC 서브넷에서 제어 플레인의 이그레스 경로를 직접 관리해요. 제어 플레인이 필요한 엔드포인트(웹훅 서버, OIDC 프로바이더, 기타 리소스 등)에 도달할 수 있도록 보장할 책임이 있어요. NAT 게이트웨이, NAT 인스턴스, transit gateway, 방화벽 어플라이언스 같은 이그레스 경로를 제공합니다. 이 트래픽을 허용하는 라우트 테이블, 네트워크 ACL, 보안 그룹 규칙도 구성해요.

중요: CUSTOMER_ROUTED 모드에서 제어 플레인에서 적절한 네트워크 연결을 보장할 책임은 사용자에게 있어요. VPC 네트워킹의 잘못된 구성은 제어 플레인 운영을 실패하게 할 수 있어요. 이러한 잘못된 구성에는 누락된 이그레스 경로, 제한적인 네트워크 ACL, 잘못된 보안 그룹이 포함돼요. 영향받는 작업에는 admission webhook 호출과 OIDC 인증이 포함돼요.

사전 조건 (Prerequisites)

VPC와 서브넷은 표준 Amazon EKS 네트워킹 요구 사항을 충족해야 해요. 자세한 내용은 View Amazon EKS networking requirements for VPC and subnets 참고.

CUSTOMER_ROUTED 모드에서 Kubernetes API 서버는 크로스 계정 네트워크 인터페이스를 통해 고객 대상 트래픽을 아웃바운드로 보내요. Amazon EKS는 이미 제어 플레인-노드 통신을 위해 이러한 인터페이스를 서브넷에 만들어요. 이 트래픽에는 admission webhook과 OIDC 프로바이더에 대한 호출이 포함돼요. Amazon EKS는 별도의 이그레스 네트워크 인터페이스를 만들지 않아요. 이 모드는 기존 인터페이스가 사용되는 방식을 변경해요. 이 인터페이스를 보유한 서브넷은 다음 요구 사항을 충족해야 해요:

서브넷에는 제어 플레인이 도달해야 하는 엔드포인트(웹훅 서버, OIDC 프로바이더 등)로 가는 라우트가 있어야 해요. VPC 밖의 엔드포인트의 경우 일반적으로 이그레스 디바이스로 가는 기본 라우트를 의미해요. 기본 라우트는 IPv4의 경우 0.0.0.0/0, IPv6의 경우 ::/0이에요. 이그레스 디바이스는 NAT 게이트웨이, NAT 인스턴스, 방화벽, 또는 중앙 집중식 이그레스 VPC로 가는 transit gateway일 수 있어요. 이그레스 디바이스의 선택은 사용자 몫이며, Amazon EKS는 경로가 작동하기만 하면 돼요.
크로스 계정 네트워크 인터페이스의 보안 그룹은 워크로드가 요구하는 포트(예: 웹훅과 OIDC 프로바이더의 포트 443)의 아웃바운드 트래픽을 허용해야 해요.
서브넷의 네트워크 ACL은 아웃바운드 트래픽과 반환 트래픽용 해당 인바운드 임시 포트 범위를 허용해야 해요.
CUSTOMER_ROUTED 모드에서 제어 플레인은 VPC의 DNS 구성을 사용해 호스트명을 해석해요. 이를 통해 제어 플레인이 Route 53 프라이빗 호스팅 영역의 엔드포인트와 Route 53 Resolver 엔드포인트를 통해 전달된 온프레미스 DNS에 도달할 수 있어요.
VPC DHCP 옵션 세트는 도메인 이름 서버 목록에 AmazonProvidedDNS를 포함해야 해요. 제어 플레인이 VPC 내에서 DNS 이름을 해석하는 데 필요해요. 클러스터가 공용 DNS 이름이 있는 외부 웹훅 엔드포인트나 OIDC 프로바이더를 사용한다면 리졸버도 공용 호스트명을 해석해야 해요. 리졸버가 VPC와 공용 DNS 해석을 모두 처리할 수 있는지 확인해 주세요.

다음 표는 CUSTOMER_ROUTED 모드에서 제어 플레인이 VPC를 통해 보내는 트래픽을 요약해요:

트래픽	대상	포트	비고
Admission webhooks	웹훅 엔드포인트 (고객 정의 URL)	443 (일반적으로)	웹훅이 구성된 경우에만. 엔드포인트가 외부면 이그레스 디바이스를 통해 VPC를 떠남.
OIDC discovery	OIDC issuer URL	443	OIDC 프로바이더가 구성된 경우에만. issuer가 외부면 이그레스 디바이스를 통해 VPC를 떠남.
Aggregated API servers	고객 API 서버 엔드포인트	443	구성된 경우에만. 엔드포인트가 외부면 이그레스 디바이스를 통해 VPC를 떠남.
Kubelet API	워커 노드 IP 주소	10250	제어 플레인과 노드 간 클러스터 ENI를 통한 트래픽. 이그레스 디바이스를 통과하지 않음. 라우트 테이블, 보안 그룹, 네트워크 ACL이 클러스터 ENI를 통해 제어 플레인과 노드 간 트래픽을 허용해야 함.

참고: 이 표에 나열된 트래픽만 이그레스 구성의 영향을 받아요. EKS 관리형 제어 플레인 트래픽(etcd, CloudWatch Logs, 내부 EKS 서비스와의 통신 등)은 AWS 관리형 네트워크 경로를 통해 계속 진행되며 VPC 구성의 영향을 받지 않아요.

고객 라우팅 이그레스로 클러스터 만들기 (Create a cluster with customer-routed egress)

새 클러스터를 만들 때 제어 플레인 이그레스 모드를 지정할 수 있어요.

IPv6 클러스터에는 ipFamily=ipv6을 사용할 수 있어요. CUSTOMER_ROUTED 모드와 함께 IPv6를 사용할 때 서브넷이 IPv4 트래픽용 NAT 게이트웨이 외에도 IPv6 트래픽용 egress-only 인터넷 게이트웨이를 갖추도록 확인해 주세요.

AWS Management Console:

Amazon EKS 콘솔을 엽니다.
Add cluster를 선택한 다음 Create를 선택합니다.
Networking 페이지의 Control plane egress에서 Customer routed를 선택합니다.
나머지 클러스터 구성을 완료하고 Create를 선택합니다.

AWS CloudFormation의 경우 ResourcesVpcConfig에서 ControlPlaneEgressMode: CUSTOMER_ROUTED를 설정합니다. 이 필드의 Terraform 지원은 향후 AWS Provider 릴리스에서 제공될 예정이에요.

참고: CUSTOMER_ROUTED로 전환하는 것은 단방향 작업이에요. 클러스터에서 고객 라우팅 이그레스를 활성화한 후에는 AWS_MANAGED로 되돌릴 수 없어요.

기존 클러스터 업데이트하기 (Update an existing cluster)

update-cluster-config 명령으로 기존 클러스터의 제어 플레인 이그레스 모드를 변경할 수 있어요.

aws eks update-cluster-config \
    --name my-cluster \
    --resources-vpc-config "controlPlaneEgressMode=CUSTOMER_ROUTED" \
    --region region-code

업데이트 상태를 모니터링합니다:

aws eks describe-update \
    --name my-cluster \
    --update-id update-id \
    --region region-code

상태가 Successful로 표시되면 업데이트가 완료된 거예요. 업데이트 유형은 ControlPlaneEgressUpdate예요. 업데이트는 일반적으로 10분 안에 완료돼요.

중요: CUSTOMER_ROUTED로 전환하는 것은 단방향 작업이에요. 클러스터에서 고객 라우팅 이그레스를 활성화한 후에는 AWS_MANAGED로 되돌릴 수 없어요.

전환 전에 VPC가 사전 조건의 요구 사항을 충족하는지 확인해 주세요. 업데이트 후 제어 플레인이 필요한 엔드포인트에 대한 연결을 잃으면 admission webhook 호출과 OIDC 인증 같은 작업이 실패할 수 있어요.

IPv6 고려 사항 (IPv6 considerations)

고객 라우팅 이그레스로 IPv6 클러스터를 실행한다면 IPv4와 IPv6 이그레스 경로를 모두 구성해야 해요.

CUSTOMER_ROUTED 이그레스로 IPv6 클러스터(ipFamily=ipv6)를 실행할 때:

제어 플레인 ENI에 IPv4와 IPv6 주소가 모두 할당됩니다.
IPv4와 IPv6 이그레스 경로를 모두 구성해야 해요:
- IPv4: 이그레스 디바이스(예: NAT 게이트웨이)로 가는 기본 라우트(0.0.0.0/0).
- IPv6: IPv6 이그레스 디바이스(예: egress-only 인터넷 게이트웨이)로 가는 ::/0 라우트.
보안 그룹과 NACL이 두 IP 버전의 트래픽을 모두 허용해야 해요.
OIDC 프로바이더나 웹훅 엔드포인트가 IPv4 전용이면 IPv4 NAT가 작동하는지 확인해 주세요.

고려 사항 (Considerations)

고객 라우팅 제어 플레인 이그레스를 사용할 때 다음 사항을 기억해 주세요:

사용자 책임 — CUSTOMER_ROUTED 모드에서 제어 플레인에서 외부 엔드포인트까지의 네트워크 경로를 소유해요. 그 경로가 끊기면 그에 의존하는 제어 플레인 작업(admission webhook 호출, OIDC 인증 등)이 연결을 복원할 때까지 실패할 수 있어요.
VPC 내부 트래픽은 영향받지 않음 — 클러스터 ENI를 통한 제어 플레인과 노드 간 트래픽(예: 포트 10250의 kubelet API)은 이그레스 디바이스에 의존하지 않아요.
EKS Auto Mode — 제어 플레인 아키텍처가 동일하므로 제어 플레인 이그레스 라우팅은 Standard와 Auto Mode 클러스터에서 동일하게 동작해요.
EKS Capabilities — EKS Capabilities(ArgoCD, ACK, KRO 등)는 별도의 AWS 관리형 인프라에서 실행돼요. EKS Capabilities 컨트롤러의 트래픽은 이 기능으로 VPC를 통해 라우팅되지 않아요.
관측성 — VPC나 클러스터 서브넷에서 VPC Flow Logs를 활성화하면 VPC를 통해 라우팅되는 이그레스 트래픽을 관찰할 수 있어요. 여기에는 webhook 및 OIDC 엔드포인트에 대한 호출이 포함돼요. VPC Flow Logs가 활성화되지 않으면 이 트래픽은 로깅되지 않아요.

IAM 조건 키 (IAM condition key)

Amazon EKS는 eks:controlPlaneEgressMode 조건 키를 지원해요. 이 키를 IAM 정책이나 서비스 제어 정책(SCP)에서 사용해 호출자가 클러스터를 만들거나 업데이트할 때 지정할 수 있는 이그레스 모드를 제어할 수 있어요.

조건 키는 다음 작업에 적용됩니다:

eks:CreateCluster
eks:UpdateClusterConfig

예를 들어 다음 SCP는 호출자가 CUSTOMER_ROUTED를 지정하지 않으면 클러스터 생성과 구성 업데이트를 거부해요:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RequireCustomerRoutedControlPlane",
      "Effect": "Deny",
      "Action": [
        "eks:CreateCluster",
        "eks:UpdateClusterConfig"
      ],
      "Resource": "*",
      "Condition": {
        "StringNotEquals": {
          "eks:controlPlaneEgressMode": "CUSTOMER_ROUTED"
        }
      }
    }
  ]
}

이 정책을 사용해 조직의 모든 신규 및 업데이트 클러스터가 CUSTOMER_ROUTED 이그레스 모드를 사용하도록 강제할 수 있어요.

OIDC 프로바이더 구성 (OIDC provider configuration)

클러스터가 OIDC identity provider를 사용한다면 제어 플레인이 HTTPS(포트 443)로 OIDC discovery 엔드포인트에 도달할 수 있어야 해요. 이는 서비스 계정용 IAM 역할 또는 클러스터 인증을 위해 연결하는 OIDC identity provider에 적용됩니다. OIDC 전용 설정은 없어요. 사전 조건에서 구성한 것과 같은 이그레스 경로를 사용해요. 이를 허용하려면:

제어 플레인 서브넷에 OIDC 엔드포인트를 포괄하는 라우트가 있는지 확인합니다 (일반적으로 이그레스 디바이스, 예: NAT 게이트웨이로 가는 기본 라우트).
클러스터 보안 그룹이 아웃바운드 TCP 443을 허용하는지 확인합니다.
서브넷 NACL이 아웃바운드 TCP 443과 인바운드 임시 반환 트래픽(포트 1024–65535)을 허용하는지 확인합니다.

엔드포인트는 프로바이더에 따라 다릅니다:

Amazon EKS OIDC 프로바이더(기본): oidc.eks.region-code.amazonaws.com
사용자 지정 OIDC 프로바이더: 구성한 issuer URL.

OIDC 인증이 실패하면 문제 해결 단계는 OIDC provider unreachable 참고.

연결 확인하기 (Verify connectivity)

CUSTOMER_ROUTED 이그레스를 구성한 후 제어 플레인이 VPC 리소스에 도달할 수 있는지 확인합니다:

현재 이그레스 모드 확인 — 클러스터가 예상하는 모드를 사용 중인지 확인합니다.

aws eks describe-cluster --name my-cluster \
    --query "cluster.resourcesVpcConfig.controlPlaneEgressMode" \
    --region region-code

클러스터 상태 확인 — 클러스터가 ACTIVE 상태여야 해요.

aws eks describe-cluster --name my-cluster --query "cluster.status" --region region-code

웹훅 연결 테스트 — admission webhook이 구성되어 있다면 webhook을 트리거하는 리소스를 만들어 성공하는지 확인합니다.
노드 등록 확인 — 노드를 시작해 클러스터에 성공적으로 조인하는지 확인합니다.

kubectl get nodes

OIDC 확인 — IAM roles for service accounts(IRSA)를 사용한다면 파드가 IAM 역할을 가정할 수 있는지 확인합니다.

일반적인 문제 문제 해결은 Troubleshooting control plane egress issues 참고.

더 알아보기 (Learn more)

공식 문서