Skip to content

AWS Outposts Support

AWS Outposts support in eksctl lets you create local clusters with the entire Kubernetes cluster, including the EKS control plane and worker nodes, running locally on AWS Outposts. Customers can either create a local cluster with both the EKS control plane and worker nodes running locally on AWS Outposts, or they can extend an existing EKS cluster running in an AWS region to AWS Outposts by creating worker nodes on Outposts.

Warning

EKS Managed Nodegroups are not supported on Outposts.

Info

Local clusters support Outpost racks only.

Creating a local cluster on AWS Outposts

To create the EKS control plane and nodegroups on AWS Outposts, set outpost.controlPlaneOutpostARN to the Outpost ARN, as in:

# outpost.yaml
---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: outpost
  region: us-west-2
  version: "1.21"

outpost:
  # Required.
  controlPlaneOutpostARN: "arn:aws:outposts:us-west-2:1234:outpost/op-1234"
  # Optional, defaults to the smallest available instance type on the Outpost.
  controlPlaneInstanceType: m5d.large
$ eksctl create cluster -f outpost.yaml

This instructs eksctl to create the EKS control plane and subnets on the specified Outpost. Since an Outposts rack exists in a single availability zone, eksctl creates only one public and private subnet. eksctl does not associate the created VPC with a local gateway and, as such, eksctl will lack connectivity to the API server and will be unable to create nodegroups. Therefore, if the ClusterConfig contains any nodegroups during cluster creation, the command must be run with --without-nodegroup, as in:

eksctl create cluster -f outpost.yaml --without-nodegroup

It is the customer's responsibility to associate the eksctl-created VPC with the local gateway after cluster creation to enable connectivity to the API server. After this step, nodegroups can be created using eksctl create nodegroup.

You can optionally specify the instance type for the control plane nodes in outpost.controlPlaneInstanceType or for the nodegroups in nodeGroup.instanceType, but the instance type must exist on Outpost or eksctl will return an error. By default, eksctl attempts to choose the smallest available instance type on Outpost for the control plane nodes and nodegroups.

When the control plane is on Outposts, nodegroups are created on that Outpost. You can optionally specify the Outpost ARN for the nodegroup in nodeGroup.outpostARN but it must match the control plane's Outpost ARN.

Warning

Local clusters support EKS 1.21 only. Support for newer versions will be added later.

Existing VPC

Customers with an existing VPC can create local clusters on AWS Outposts by specifying the subnet configuration in vpc.subnets, as in:

# outpost-existing-vpc.yaml
---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: outpost
  region: us-west-2

vpc:
  id: vpc-1234
  subnets:
    private:
      outpost-subnet-1:
        id: subnet-1234

nodeGroups:
  - name: outpost-ng
    privateNetworking: true

outpost:
    # Required.
    controlPlaneOutpostARN: "arn:aws:outposts:us-west-2:1234:outpost/op-1234"
    # Optional, defaults to the smallest available instance type on the Outpost.
    controlPlaneInstanceType: m5d.large
$ eksctl create cluster -f outpost-existing-vpc.yaml

The subnets must exist on the Outpost specified in outpost.controlPlaneOutpostARN or eksctl will return an error. You can also specify nodegroups during cluster creation if you have access to the local gateway for the subnet, or have connectivity to VPC resources.

Extending existing clusters to AWS Outposts

Customers can extend an existing EKS cluster running in an AWS region to AWS Outposts by setting nodeGroup.outpostARN for new nodegroups to create nodegroups on Outposts, as in:

# extended-cluster.yaml
---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: existing-cluster
  region: us-west-2
  version: "1.21"

nodeGroups:
  # Nodegroup will be created in an AWS region.
  - name: ng

  # Nodegroup will be created on the specified Outpost.
  - name: outpost-ng
    privateNetworking: true
    outpostARN: "arn:aws:outposts:us-west-2:1234:outpost/op-1234"
$ eksctl create nodegroup -f extended-cluster.yaml

In this setup, the EKS control plane runs in an AWS region while nodegroups with outpostARN set run on the specified Outpost. When a nodegroup is being created on Outposts for the first time, eksctl extends the VPC by creating subnets on the specified Outpost. These subnets are used to create nodegroups that have outpostARN set.

Customers with a pre-existing VPC are required to create the subnets on Outposts and pass them in nodeGroup.subnets, as in:

# extended-cluster-vpc.yaml
---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: extended-cluster-vpc
  region: us-west-2
  version: "1.21"

vpc:
  id: vpc-1234
    subnets:
      private:
        outpost-subnet-1:
          id: subnet-1234

nodeGroups:
  # Nodegroup will be created in an AWS region.
  - name: ng

  # Nodegroup will be created on the specified Outpost.
  - name: outpost-ng
    privateNetworking: true
    # Subnet IDs for subnets created on Outpost.
    subnets: [subnet-5678]
    outpostARN: "arn:aws:outposts:us-west-2:1234:outpost/op-1234"

Note

Only Amazon Linux 2 is supported for nodegroups when the control plane is on Outposts.

Note

Only EBS gp2 volume types are supported for nodegroups on Outposts.

Features unsupported on local clusters

Further information

Back to top