Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Configuring control plane egress routing

By default, Amazon EKS manages the egress networking from the Kubernetes control plane to resources in your VPC. Use control plane egress routing to change this behavior and manage the network path yourself. This gives you full control over how traffic from the control plane elastic network interfaces (ENIs) reaches your VPC resources. You can route through your own NAT gateways, firewalls, or inspection appliances.

Egress routing modes

Amazon EKS supports the following control plane egress routing modes:

Prerequisites

Your VPC and subnets must meet the standard Amazon EKS networking requirements. For more information, see View Amazon EKS networking requirements for VPC and subnets.

In CUSTOMER_ROUTED mode, the Kubernetes API server sends customer-facing traffic outbound through the cross-account network interfaces. Amazon EKS already creates these interfaces in your subnets for control plane to node communication. This traffic includes calls to admission webhooks and OIDC providers. Amazon EKS doesn’t create separate egress network interfaces. This mode changes how the existing interfaces are used. The subnets that hold these interfaces must meet the following requirements:

In CUSTOMER_ROUTED mode, the control plane resolves hostnames using your VPC’s DNS configuration. This enables the control plane to reach endpoints in Route 53 private hosted zones and on-premises DNS forwarded through Route 53 Resolver endpoints.

The following table summarizes the traffic the control plane sends through your VPC in CUSTOMER_ROUTED mode:

Create a cluster with customer-routed egress

You can specify the control plane egress mode when you create a new cluster.

You can use ipFamily=ipv6 for IPv6 clusters. When using IPv6 with CUSTOMER_ROUTED mode, ensure your subnets have an egress-only internet gateway for IPv6 traffic in addition to a NAT gateway for IPv4 traffic.

For AWS CloudFormation, set ControlPlaneEgressMode: CUSTOMER_ROUTED in ResourcesVpcConfig. Terraform support for this field will be available in a future release of the AWS Provider.

Update an existing cluster

You can change the control plane egress mode on an existing cluster using the update-cluster-config command.

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

Monitor the update status:

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

The update is complete when the status shows Successful. The update type is ControlPlaneEgressUpdate. The update typically completes within 10 minutes.

IPv6 considerations

If you run an IPv6 cluster with customer-routed egress, you need to configure both IPv4 and IPv6 egress paths.

When running an IPv6 cluster (ipFamily=ipv6) with CUSTOMER_ROUTED egress:

Considerations

Keep the following points in mind when you use customer-routed control plane egress:

IAM condition key

Amazon EKS supports the eks:controlPlaneEgressMode condition key. You can use this key in IAM policies or service control policies (SCPs) to control which egress mode callers can specify when they create or update clusters.

The condition key applies to the following actions:

For example, the following SCP denies cluster creation and configuration updates unless the caller specifies CUSTOMER_ROUTED:

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

Use this policy to enforce that all new and updated clusters in your organization use the CUSTOMER_ROUTED egress mode.

OIDC provider configuration

If your cluster uses an OIDC identity provider, the control plane must be able to reach the OIDC discovery endpoint over HTTPS (port 443). This applies to IAM roles for service accounts, or an OIDC identity provider you associate for cluster authentication. There is no OIDC-specific setting; it uses the same egress path you configure in Prerequisites. To allow it:

The endpoint depends on your provider:

If OIDC authentication fails, for troubleshooting steps see OIDC provider unreachable.

Verify connectivity

After configuring CUSTOMER_ROUTED egress, verify that the control plane can reach your VPC resources:

For troubleshooting common issues, see Troubleshooting control plane egress issues.

📝 Edit this page on GitHub