Private clusters - Amazon EKS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Private clusters

This topic describes how to deploy an Amazon EKS private cluster without outbound internet access. If you're not familiar with Amazon EKS networking, see De-mystifying cluster networking for Amazon EKS worker nodes.


The following requirements must be met to run Amazon EKS in a private cluster without outbound internet access.

  • A container image must be in or copied to Amazon Elastic Container Registry (Amazon ECR) or to a registry inside the VPC to be pulled. For more information, see Creating local copies of container images.

  • Endpoint private access is required for nodes to register with the cluster endpoint. Endpoint public access is optional. For more information, see Amazon EKS cluster endpoint access control.

  • You may need to include the VPC endpoints found at VPC endpoints for private clusters.

  • For Linux and Windows nodes, you must include bootstrap arguments when launching self-managed nodes. This text bypasses the Amazon EKS introspection and doesn't require access to the Amazon EKS API from within the VPC. Replace <api-server-endpoint> and <certificate-authority> with the values from your Amazon EKS cluster.

    • For Linux nodes:

      --apiserver-endpoint <api-server-endpoint> --b64-cluster-ca <certificate-authority>

      For additional arguments, see the bootstrap script on GitHub.

    • For Windows nodes:

      -APIServerEndpoint <api-server-endpoint> -Base64ClusterCA <certificate-authority>

      For additional arguments, see Amazon EKS optimized Windows AMI.

  • The aws-auth ConfigMap must be created from within the VPC. For more information about create the aws-auth ConfigMap, see Enabling IAM user and role access to your cluster.


Here are some things to consider when running Amazon EKS in a private cluster without outbound internet access.

Creating local copies of container images

Because a private cluster has no outbound internet access, container images can't be pulled from external sources such as Docker Hub. Instead, container images must be copied locally to Amazon ECR or to an alternative registry accessible in the VPC. A container image can be copied to Amazon ECR from outside the private VPC. The private cluster accesses the Amazon ECR repository using the Amazon ECR VPC endpoints. You must have Docker and the Amazon CLI installed on the workstation that you use to create the local copy.

To create a local copy of a container image

  1. Create an Amazon ECR repository. For more information, see Creating a repository.

  2. Pull the container image from the external registry using docker pull.

  3. Tag your image with the Amazon ECR registry, repository, and the optional image tag name combination using docker tag.

  4. Authenticate to the registry. For more information, see Registry authentication.

  5. Push the image to Amazon ECR using docker push.


    Make sure to update your resource configuration to use the new image location.

    The following example pulls the amazon/aws-node-termination-handler image, using tag v1.3.1-linux-amd64, from Docker Hub and creates a local copy in Amazon ECR.

    aws ecr create-repository --repository-name amazon/aws-node-termination-handler docker pull amazon/aws-node-termination-handler:v1.3.1-linux-amd64 docker tag amazon/aws-node-termination-handler <111122223333>.dkr.ecr.<region-code> aws ecr get-login-password --region <region-code> | docker login --username Amazon --password-stdin <111122223333>.dkr.ecr.<region-code> docker push <111122223333>.dkr.ecr.<region-code>

VPC endpoints for private clusters

The following VPC endpoints might be required.

  •<region>.sts – If using Cluster Autoscaler or IAM roles for service accounts

  •<region>.autoscaling – If using Cluster Autoscaler

  •<region>.xray – If using Amazon X-Ray

Amazon STS endpoints for IAM roles for service accounts

Pods configured with IAM roles for service accounts acquire credentials from an Amazon Security Token Service (Amazon STS) API call. If there is no outbound internet access, you must create and use an Amazon STS VPC endpoint in your VPC. Most Amazon v1 SDKs use the global Amazon STS endpoint by default (, which doesn't use the Amazon STS VPC endpoint. To use the Amazon STS VPC endpoint, you may need to configure the SDK to use the regional Amazon STS endpoint ( You can do this by setting the AWS_STS_REGIONAL_ENDPOINTS environment variable with a value of regional, along with the Amazon Region.

For example, in a pod spec:

... containers: - env: - name: ' value: region-code - name: AWS_STS_REGIONAL_ENDPOINTS value: regional ... ```

Replace region-code with the Region that your cluster is in (us-west-2 for example).