View a markdown version of this page

Deploy an Amazon EKS local cluster on AWS Outposts configured with EC2 instance store - Amazon EKS
Create a local clusterConnect to your clusterDeploy worker nodesInternal resources

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.

Deploy an Amazon EKS local cluster on AWS Outposts configured with EC2 instance store

This topic provides instructions for deploying a local Amazon EKS cluster on an AWS Outpost configured with EC2 instance store.

Note

If your Outpost is configured with Amazon EBS instead of EC2 instance store, the architecture described in this topic isn’t available for your Outpost. Outposts configured with EBS will continue to use the existing local clusters implementation. For more information, see Deploy an Amazon EKS cluster on AWS Outposts.

If you are interested in creating a local cluster on an EBS-backed Outpost using the updated local clusters architecture, contact your AWS account team.

Important

Prerequisites

Note

When you create a local cluster, the IAM principal that creates the cluster is permanently added to the Kubernetes RBAC authorization table as an administrator with system:masters permissions. Make sure you never delete this principal.

Create a local cluster

You can create a local cluster using the AWS Management Console, AWS CLI, Amazon EKS API, or AWS CloudFormation.

When you create a local cluster, note the following:

AWS CLI

aws eks create-cluster \
  --name my-cluster \
  --role-arn arn:aws:iam::111122223333:role/myEKSClusterRole \
  --kubernetes-version 1.36 \
  --resources-vpc-config subnetIds=subnet-ExampleID1,endpointPrivateAccess=true,endpointPublicAccess=true \
  --logging '{"clusterLogging":[{"types":["api","audit","authenticator","controllerManager","scheduler"],"enabled":true}]}' \
  --access-config authenticationMode=API_AND_CONFIG_MAP,bootstrapClusterCreatorAdminPermissions=true \
  --outpost-config outpostArns=arn:aws:outposts:region-code:111122223333:outpost/op-uniqueid,controlPlaneInstanceType=m5.large,controlPlanePlacement={spreadLevel=host},etcdInstanceType=m5.large,etcdPlacement={spreadLevel=host}

AWS Management Console

  1. Open the Amazon EKS console.

  2. Choose Create cluster.

  3. For Kubernetes control plane location, choose AWS Outposts.

  4. Configure the following:

    • Name — A name for your cluster.

    • Kubernetes version — The version to use.

    • Cluster service role — The IAM role with AmazonEKSClusterPolicy and AmazonEKSServicePolicy.

    • Outpost ID — The logical Outpost to deploy to.

    • Control plane instance type — The instance type for the Kubernetes API server, scheduler, and controller manager.

    • etcd instance type — The instance type for etcd.

    • Spread level — host or rack for control plane and etcd placement.

  5. Configure networking: VPC, subnets, security groups. Enable private endpoint access.

  6. Configure observability: control plane logging.

  7. Review and create.

CreateCluster API

{
    "name": "my-cluster",
    "roleArn": "arn:aws:iam::111122223333:role/myEKSClusterRole",
    "version": "1.36",
    "resourcesVpcConfig": {
        "subnetIds": ["subnet-ExampleID1"],
        "endpointPublicAccess": true,
        "endpointPrivateAccess": true
    },
    "logging": {
        "clusterLogging": [{
            "types": ["api", "audit", "authenticator", "controllerManager", "scheduler"],
            "enabled": true
        }]
    },
    "accessConfig": {
        "authenticationMode": "API_AND_CONFIG_MAP",
        "bootstrapClusterCreatorAdminPermissions": true
    },
    "outpostConfig": {
        "outpostArns": ["arn:aws:outposts:region-code:111122223333:outpost/op-uniqueid"],
        "controlPlaneInstanceType": "m5.large",
        "controlPlanePlacement": {
            "spreadLevel": "host"
        },
        "etcdInstanceType": "m5.large",
        "etcdPlacement": {
            "spreadLevel": "host"
        }
    }
}

The controlPlaneInstanceType and etcdInstanceType parameters are required when you create a local cluster on Outposts configured with EC2 instance store. The controlPlanePlacement and etcdPlacement parameters are optional. If you don’t specify them, no placement spread strategy is applied.

Note

outpostConfig is a create-only property. To change the control plane instance type, etcd instance type, placement, or Outpost, you must create a new cluster.

Connect to your cluster

Configure kubectl to communicate with your cluster:

aws eks update-kubeconfig --region region-code --name my-cluster
Note

If you created your cluster using AWS CLI versions below 2.35.3, you must update your kubeconfig to specify --cluster-name (instead of --cluster-id) in the exec args

The cluster’s Kubernetes API server endpoint is hosted in Amazon Route 53. The endpoint resolves to the private IP addresses of the cross-account elastic network interfaces (ENIs) that Amazon EKS creates in your subnets. These ENIs have fixed private IP addresses that don’t change throughout the cluster lifecycle.

When you create a cluster, Amazon EKS creates 3 elastic network interfaces in the subnets that you specify. These network interfaces enable communication between your cluster and your VPC. Each network interface has the text Amazon EKS cluster-name in its description.

Deploy worker nodes

Deploy worker nodes to your local cluster using self-managed node groups.

  1. Deploy the worker node AWS CloudFormation template or create individual EC2 instances on your Outpost.

    curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2025-11-24/amazon-eks-outpost-nodegroup.yaml

  2. Grant the node instance role access to your cluster. Create an access entry for the node’s IAM role:

    aws eks create-access-entry \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::111122223333:role/myNodeRole \
  --type EC2_LINUX

    Alternatively, if you are using the aws-auth ConfigMap for authentication, add the node instance role to the ConfigMap. See Grant IAM users and roles access to Kubernetes APIs.

  3. Verify that your nodes are in Ready state:

    kubectl get nodes

Internal resources

When you create a local cluster, Amazon EKS automatically installs the self-managed versions of the following add-ons in the kube-system namespace: coredns, kube-proxy, and aws-node (VPC CNI). You can optionally install the managed versions of these add-ons through the Amazon EKS add-ons API. For more information, see Amazon EKS add-ons for local clusters on AWS Outposts configured with EC2 instance store.

Amazon EKS also creates cross-account elastic network interfaces (ENIs) in your subnets for cluster-VPC communication. Do not delete these network interfaces. If a cross-account ENI is deleted or its IP address changes, every node and every administrator using static IP-based access must be updated manually.