How do I add new subnets to an existing Amazon EKS cluster?

Short description

If you add subnets to new Availability Zones or remove subnets from existing Availability Zones, then you might receive an error message that's similar to the following:

“An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Provided subnets belong to the AZs 'us-west-2a,us-west-2c,us-west-2d'. But they should belong to the exact set of AZs 'us-west-2a,us-west-2c' in which subnets were provided during cluster creation.”

Your subnets must be in the same set of Availability Zones that AWS chose for you when you created the cluster. The subnets must also be in the same Amazon Virtual Private Cloud (Amazon VPC) that AWS provided when you created the cluster. The VPC must have enough available IP addresses for the cluster. For more information, see Create a subnet and VPC requirements and considerations.

Resolution

To modify Amazon EKS cluster subnets, you can use the Amazon EKS console, AWS CLI, or eksctl CLI.

Use the Amazon EKS console

Complete the following steps:

1. Open the Amazon EKS console.
2. In the navigation pane, choose Cluster.
3. Choose Network, and then choose Manage VPC resources.
4. On the Subnets menu, select the subnets to add.
5. Choose Save.
6. In the Network section, confirm that the subnets were added.

Use the AWS CLI

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

The AWS CLI command replaces the existing cluster subnets with the subnets that you include in the command. To add subnets, specify the existing subnets and the additional subnets.

1. Run the describe-subnets command to identify the Availability Zones that you configured for your EKS cluster:

   aws ec2 describe-subnets --subnet-ids $(aws eks describe-cluster --name your-cluster-name --query 'cluster.resourcesVpcConfig.subnetIds' --output text) --query 'Subnets[*].AvailabilityZone'

   Note: Replace your-cluster-name with your cluster name and the example subnet IDs with your subnet IDs.
   Example output:

   [
       "us-west-2c",
       "us-west-2d",
       "us-west-2a"
   ]

2. Run the update-cluster-config command to update the cluster control plane subnets:

   aws eks update-cluster-config --name your-cluster-name \
   --resources-vpc-config subnetIds=subnet-1234,subnet-5678,subnet-9101

   Note: Replace your-cluster-name with your cluster name and the example subnet IDs with your subnet IDs. When you add new subnets, make sure that you represent each Availability Zone from the original set by at least one subnet. To keep an existing subnet for an Availability Zone, include the subnet in the command.
   The following example gets the EKS cluster's current Availability Zones and adds new subnets to the existing zones. The update-cluster-config command includes the original and new subnets to maintain the cluster's Availability Zone configuration and expand the subnets in each zone:

   aws eks describe-cluster --name gpusharing-demo --query 'cluster.resourcesVpcConfig.subnetIds'
   [
       "subnet-03d59dfc8d9380b4c",
       "subnet-0c4f51f27d109fa32",
       "subnet-037b42db1a08da5ae"
   ]
   
   aws eks update-cluster-config --name gpusharing-demo --resources-vpc-config subnetIds=subnet-xxxxxxx80b4c,subnet-xxxxxxx8da5ae,subnet-xxxxxxx9fa32,subnet-xxxxxxee3bb,subnet-xxxxxxa761ac,subnet-xxxxxxde8b8
   {
   "update": {
   "id": "e7ed1fbf-01ab-3472-8204-149cdc3337be",
   "status": "InProgress",
   "type": "VpcConfigUpdate",
   "params": [
   {
   "type": "Subnets",
   "value": "[subnet-xxxxxxx80b4c, subnet-xxxxxxx8da5ae, subnet-xxxxxxxx9fa32, subnet-xxxxxxxee3bb, subnet-xxxxxxxxa761ac, subnet-xxxxxxde8b8]"
   }
   ],
   "createdAt": "2024-09-09T18:06:16.493000+00:00",
   "errors": []
   }
   }

Use the eksctl CLI

The eksctl CLI command replaces the existing cluster subnets with the subnets that you include in the command. To add subnets, specify the existing subnets and the additional subnets.

Run the following eksctl command to update cluster control plane subnets:

eksctl utils update-cluster-vpc-config --cluster=your-cluster-name \
--control-plane-subnet-ids=subnet-1234,subnet-5678 --approve

The following example output shows that the cluster updated to one subnet for each Availability Zone:

eksctl utils update-cluster-vpc-config --cluster=gpusharing-demo  --control-plane-subnet-ids=subnet-03d59dfc8d9380b4c,subnet-0c4f51f27d109fa32,subnet-037b42db1a08da5ae --approve
2024-09-09 18:23:54 [ℹ]  using region us-west-2
2024-09-09 18:23:54 [ℹ]  will update control plane subnet IDs for cluster "gpusharing-demo" in "us-west-2" to: [subnet-xxxxxxx80b4c subnet-xxxxxxx9fa32 subnet-xxxxxx8da5ae]
2024-09-09 18:32:07 [✔]  control plane subnets and security groups for cluster "gpusharing-demo" in "us-west-2" have been updated to: controlPlaneSubnetIDs=[subnet-xxxxxxx80b4c subnet-xxxxxxxx9fa32 subnet-xxxxxxxx8da5ae], controlPlaneSecurityGroupIDs=[sg-xxxxx31d2]

To use the config.yaml file to update subnets, run the following command:

eksctl utils update-cluster-vpc-config -f config.yaml

Example output:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: cluster
  region: us-west-2

vpc:
  controlPlaneSubnetIDs: [subnet-1234, subnet-5678, subnet-9101]
  controlPlaneSecurityGroupIDs: [sg-1234, sg-5678]

Related information:

Enhanced VPC flexibility: modify subnets and security groups in Amazon EKS

Updating control plane subnets and security groups on the eksctl website