Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors Examples See Also

CreateNodegroup

Creates a managed node group for an Amazon EKS cluster.

You can only create a node group for your cluster that is equal to the current Kubernetes version for the cluster. All node groups are created with the latest AMI release version for the respective minor Kubernetes version of the cluster, unless you deploy a custom AMI using a launch template. For more information about using launch templates, see Customizing managed nodes with launch templates.

An Amazon EKS managed node group is an Amazon EC2 Auto Scaling group and associated Amazon EC2 instances that are managed by AWS for an Amazon EKS cluster. For more information, see Managed node groups in the Amazon EKS User Guide.

Note

Windows AMI types are only supported for commercial AWS Regions that support Windows on Amazon EKS.

Request Syntax


POST /clusters/name/node-groups HTTP/1.1
Content-type: application/json

{
   "amiType": "string",
   "capacityType": "string",
   "clientRequestToken": "string",
   "diskSize": number,
   "instanceTypes": [ "string" ],
   "labels": { 
      "string" : "string" 
   },
   "launchTemplate": { 
      "id": "string",
      "name": "string",
      "version": "string"
   },
   "nodegroupName": "string",
   "nodeRole": "string",
   "releaseVersion": "string",
   "remoteAccess": { 
      "ec2SshKey": "string",
      "sourceSecurityGroups": [ "string" ]
   },
   "scalingConfig": { 
      "desiredSize": number,
      "maxSize": number,
      "minSize": number
   },
   "subnets": [ "string" ],
   "tags": { 
      "string" : "string" 
   },
   "taints": [ 
      { 
         "effect": "string",
         "key": "string",
         "value": "string"
      }
   ],
   "updateConfig": { 
      "maxUnavailable": number,
      "maxUnavailablePercentage": number
   },
   "version": "string"
}

URI Request Parameters

The request uses the following URI parameters.

name

The name of your cluster.

Required: Yes

Request Body

The request accepts the following data in JSON format.

amiType

The AMI type for your node group. If you specify launchTemplate, and your launch template uses a custom AMI, then don't specify amiType, or the node group deployment will fail. If your launch template uses a Windows custom AMI, then add eks:kube-proxy-windows to your Windows nodes rolearn in the aws-auth ConfigMap. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: String

Required: No

capacityType

The capacity type for your node group.

Type: String

Valid Values: ON_DEMAND | SPOT

Required: No

clientRequestToken

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

Type: String

Required: No

diskSize

The root device disk size (in GiB) for your node group instances. The default disk size is 20 GiB for Linux and Bottlerocket. The default disk size is 50 GiB for Windows. If you specify launchTemplate, then don't specify diskSize, or the node group deployment will fail. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: Integer

Required: No

instanceTypes

Specify the instance types for a node group. If you specify a GPU instance type, make sure to also specify an applicable GPU AMI type with the amiType parameter. If you specify launchTemplate, then you can specify zero or one instance type in your launch template or you can specify 0-20 instance types for instanceTypes. If however, you specify an instance type in your launch template and specify any instanceTypes, the node group deployment will fail. If you don't specify an instance type in a launch template or for instanceTypes, then t3.medium is used, by default. If you specify Spot for capacityType, then we recommend specifying multiple values for instanceTypes. For more information, see Managed node group capacity types and Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: Array of strings

Required: No

labels

The Kubernetes labels to apply to the nodes in the node group when they are created.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 63.

Value Length Constraints: Minimum length of 1. Maximum length of 63.

Required: No

launchTemplate

An object representing a node group's launch template specification. When using this object, don't directly specify instanceTypes, diskSize, or remoteAccess. Make sure that the launch template meets the requirements in launchTemplateSpecification. Also refer to Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: LaunchTemplateSpecification object

Required: No

nodegroupName

The unique name to give your node group.

Type: String

Required: Yes

nodeRole

The Amazon Resource Name (ARN) of the IAM role to associate with your node group. The Amazon EKS worker node kubelet daemon makes calls to AWS APIs on your behalf. Nodes receive permissions for these API calls through an IAM instance profile and associated policies. Before you can launch nodes and register them into a cluster, you must create an IAM role for those nodes to use when they are launched. For more information, see Amazon EKS node IAM role in the Amazon EKS User Guide . If you specify launchTemplate, then don't specify IamInstanceProfile in your launch template, or the node group deployment will fail. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: String

Required: Yes

releaseVersion

The AMI version of the Amazon EKS optimized AMI to use with your node group. By default, the latest available AMI version for the node group's current Kubernetes version is used. For information about Linux versions, see Amazon EKS optimized Amazon Linux AMI versions in the Amazon EKS User Guide. Amazon EKS managed node groups support the November 2022 and later releases of the Windows AMIs. For information about Windows versions, see Amazon EKS optimized Windows AMI versions in the Amazon EKS User Guide.

If you specify launchTemplate, and your launch template uses a custom AMI, then don't specify releaseVersion, or the node group deployment will fail. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: String

Required: No

remoteAccess

The remote access configuration to use with your node group. For Linux, the protocol is SSH. For Windows, the protocol is RDP. If you specify launchTemplate, then don't specify remoteAccess, or the node group deployment will fail. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: RemoteAccessConfig object

Required: No

scalingConfig

The scaling configuration details for the Auto Scaling group that is created for your node group.

Type: NodegroupScalingConfig object

Required: No

subnets

The subnets to use for the Auto Scaling group that is created for your node group. If you specify launchTemplate, then don't specify SubnetId in your launch template, or the node group deployment will fail. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: Array of strings

Required: Yes

tags

Metadata that assists with categorization and organization. Each tag consists of a key and an optional value. You define both. Tags don't propagate to any other cluster or AWS resources.

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Maximum length of 256.

Required: No

taints

The Kubernetes taints to be applied to the nodes in the node group. For more information, see Node taints on managed node groups.

Type: Array of Taint objects

Required: No

updateConfig

The node group update configuration.

Type: NodegroupUpdateConfig object

Required: No

version

The Kubernetes version to use for your managed nodes. By default, the Kubernetes version of the cluster is used, and this is the only accepted specified value. If you specify launchTemplate, and your launch template uses a custom AMI, then don't specify version, or the node group deployment will fail. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide.

Type: String

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "nodegroup": { 
      "amiType": "string",
      "capacityType": "string",
      "clusterName": "string",
      "createdAt": number,
      "diskSize": number,
      "health": { 
         "issues": [ 
            { 
               "code": "string",
               "message": "string",
               "resourceIds": [ "string" ]
            }
         ]
      },
      "instanceTypes": [ "string" ],
      "labels": { 
         "string" : "string" 
      },
      "launchTemplate": { 
         "id": "string",
         "name": "string",
         "version": "string"
      },
      "modifiedAt": number,
      "nodegroupArn": "string",
      "nodegroupName": "string",
      "nodeRole": "string",
      "releaseVersion": "string",
      "remoteAccess": { 
         "ec2SshKey": "string",
         "sourceSecurityGroups": [ "string" ]
      },
      "resources": { 
         "autoScalingGroups": [ 
            { 
               "name": "string"
            }
         ],
         "remoteAccessSecurityGroup": "string"
      },
      "scalingConfig": { 
         "desiredSize": number,
         "maxSize": number,
         "minSize": number
      },
      "status": "string",
      "subnets": [ "string" ],
      "tags": { 
         "string" : "string" 
      },
      "taints": [ 
         { 
            "effect": "string",
            "key": "string",
            "value": "string"
         }
      ],
      "updateConfig": { 
         "maxUnavailable": number,
         "maxUnavailablePercentage": number
      },
      "version": "string"
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

nodegroup

The full description of your new node group.

Type: Nodegroup object

Errors

For information about the errors that are common to all actions, see Common Errors.

ClientException

These errors are usually caused by a client action. Actions can include using an action or resource on behalf of an IAM principal that doesn't have permissions to use the action or resource or specifying an identifier that is not valid.

HTTP Status Code: 400

InvalidParameterException

The specified parameter is invalid. Review the available parameters for the API request.

HTTP Status Code: 400

InvalidRequestException

The request is invalid given the state of the cluster. Check the state of the cluster and the associated operations.

HTTP Status Code: 400

ResourceInUseException

The specified resource is in use.

HTTP Status Code: 409

ResourceLimitExceededException

You have encountered a service limit on the specified resource.

HTTP Status Code: 400

ServerException

These errors are usually caused by a server-side issue.

HTTP Status Code: 500

ServiceUnavailableException

The service is unavailable. Back off and retry the operation.

HTTP Status Code: 503

Examples

In the following example or examples, the Authorization header contents (AUTHPARAMS) must be replaced with an AWS Signature Version 4 signature. For more information about creating these signatures, see Signature Version 4 Signing Process in the Amazon EKS General Reference.

You need to learn how to sign HTTP requests only if you intend to manually create them. When you use the AWS Command Line Interface (AWS CLI) or one of the AWS SDKs to make requests to AWS, these tools automatically sign the requests for you with the access key that you specify when you configure the tools. When you use these tools, you don't need to learn how to sign requests yourself.

Example 1

This example creates a managed node group without a launch template that uses an Amazon EKS optimized AMI with GPU support on p2.xlarge instances.

Sample Request


POST /clusters/my-cluster/node-groups HTTP/1.1
Host: eks.us-west-2.amazonaws.com
Accept-Encoding: identity
User-Agent: aws-cli/1.16.298 Python/3.6.0 Windows/10 botocore/1.13.34
X-Amz-Date: 20200812T151423Z
Authorization: AUTHPARAMS
Content-Length: 454

{
	"nodegroupName": "my-nodegroup-gpu",
	"scalingConfig": {
		"minSize": 2,
		"maxSize": 2,
		"desiredSize": 2
	},
	"subnets": ["subnet-nnnnnnnnnnnnnnnnn", "subnet-xxxxxxxxxxxxxxxxx", "subnet-yyyyyyyyyyyyyyyyy", "subnet-zzzzzzzzzzzzzzzzz"],
	"instanceTypes": ["p2.xlarge"],
	"amiType": "AL2_x86_64_GPU",
        "remoteAccess": {
          "ec2SshKey": "id_rsa"
         },
	"nodeRole": "arn:aws:iam::012345678910:role/NodeInstanceRole",
	"clientRequestToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Sample Response


HTTP/1.1 200 OK
Date: Wed, 12 Aug 2020 15:14:24 GMT
Content-Type: application/json
Content-Length: 951
x-amzn-RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
x-amz-apigw-id: DAc5BGsWvHcF_bw=
X-Amzn-Trace-Id: Root=1-xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx
Connection: keep-alive

{
	"nodegroup": {
		"nodegroupName": "my-nodegroup-gpu2",
		"nodegroupArn": "arn:aws:eks:us-west-2:012345678910:nodegroup/my-cluster/my-nodegroup-gpu2/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"clusterName": "lt-testing",
		"version": "1.17",
		"releaseVersion": "1.17.9-20200804",
		"createdAt": 1.597245264844E9,
		"modifiedAt": 1.597245264844E9,
		"status": "CREATING",
		"scalingConfig": {
			"minSize": 2,
			"maxSize": 2,
			"desiredSize": 2
		},
		"instanceTypes": ["p2.xlarge"],
		"subnets": ["subnet-nnnnnnnnnnnnnnnnn", "subnet-xxxxxxxxxxxxxxxxx", "subnet-yyyyyyyyyyyyyyyyy", "subnet-zzzzzzzzzzzzzzzzz"],
		"remoteAccess": {
                  "ec2SshKey": "id_rsa",
                  "sourceSecurityGroups": null
                },
		"amiType": "AL2_x86_64_GPU",
		"nodeRole": "arn:aws:iam::012345678910:role/NodeInstanceRole",
		"labels": null,
		"resources": null,
		"diskSize": 20,
		"health": {
			"issues": []
		},
		"launchTemplate": null,
		"tags": {}
	}
}

Example 2

This example creates a managed node group with an Amazon EKS optimized AMI using version 2 of a launch template named my-launch-template.

Sample Request


POST /clusters/lt-testing/node-groups HTTP/1.1
Host: eks.us-west-2.amazonaws.com
Accept-Encoding: identity
User-Agent: aws-cli/1.16.298 Python/3.6.0 Windows/10 botocore/1.13.34
X-Amz-Date: 20200812T135927Z
Authorization: AUTHPARAMS
Content-Length: 433

{
	"nodegroupName": "my-nodegroup",
	"scalingConfig": {
		"minSize": 2,
		"maxSize": 2,
		"desiredSize": 2
	},
	"subnets": ["subnet-nnnnnnnnnnnnnnnnn", "subnet-xxxxxxxxxxxxxxxxx", "subnet-yyyyyyyyyyyyyyyyy", "subnet-zzzzzzzzzzzzzzzzz"],
	"amiType": "AL2_x86_64",
	"nodeRole": "arn:aws:iam::012345678910:role/NodeInstanceRole",
	"launchTemplate": {
		"name": "my-launch-template",
		"version": "2"
	},
	"clientRequestToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Sample Response


HTTP/1.1 200 OK
Date: Wed, 12 Aug 2020 13:59:32 GMT
Content-Type: application/json
Content-Length: 1028
x-amzn-RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
x-amz-apigw-id: DAc5BGsWvHcF_bw=
X-Amzn-Trace-Id: Root=1-xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx
Connection: keep-alive

{
	"nodegroup": {
		"nodegroupName": "my-nodegroup",
		"nodegroupArn": "arn:aws:eks:us-west-2:012345678910:nodegroup/my-cluster/my-nodegroup/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"clusterName": "my-cluster",
		"version": "1.17",
		"releaseVersion": "1.17.9-20200804",
		"createdAt": 1.597240771904E9,
		"modifiedAt": 1.597240771904E9,
		"status": "CREATING",
		"scalingConfig": {
			"minSize": 2,
			"maxSize": 2,
			"desiredSize": 2
		},
		"instanceTypes": null,
		"subnets": ["subnet-nnnnnnnnnnnnnnnnn", "subnet-xxxxxxxxxxxxxxxxx", "subnet-yyyyyyyyyyyyyyyyy", "subnet-zzzzzzzzzzzzzzzzz"],
		"remoteAccess": null,
		"amiType": "AL2_x86_64",
		"nodeRole": "arn:aws:iam::012345678910:role/NodeInstanceRole",
		"labels": null,
		"resources": null,
		"diskSize": null,
		"health": {
			"issues": []
		},
		"launchTemplate": {
			"name": "my-template",
			"version": "2",
			"id": "lt-xxxxxxxxxxxxxxxxx"
		},
		"tags": {}
	}
}