nodegroups

Creates, updates, deletes, gets or lists a nodegroups resource.

Overview

Name	`nodegroups`
Type	Resource
Id	`aws.eks.nodegroups`

Fields

The following fields are returned by SELECT queries:

describe_nodegroup
list_nodegroups

Name	Datatype	Description
`ami_type`	`string`	If the node group was deployed using a launch template with a custom AMI, then this is CUSTOM. For node groups that weren't deployed using a launch template, this is the AMI type that was specified in the node group configuration. (AL2_x86_64, AL2_x86_64_GPU, AL2_ARM_64, CUSTOM, BOTTLEROCKET_ARM_64, BOTTLEROCKET_x86_64, BOTTLEROCKET_ARM_64_FIPS, BOTTLEROCKET_x86_64_FIPS, BOTTLEROCKET_ARM_64_NVIDIA, BOTTLEROCKET_x86_64_NVIDIA, BOTTLEROCKET_ARM_64_NVIDIA_FIPS, BOTTLEROCKET_x86_64_NVIDIA_FIPS, WINDOWS_CORE_2019_x86_64, WINDOWS_FULL_2019_x86_64, WINDOWS_CORE_2022_x86_64, WINDOWS_FULL_2022_x86_64, WINDOWS_CORE_2025_x86_64, WINDOWS_FULL_2025_x86_64, AL2023_x86_64_STANDARD, AL2023_ARM_64_STANDARD, AL2023_x86_64_NEURON, AL2023_x86_64_NVIDIA, AL2023_ARM_64_NVIDIA)
`capacity_type`	`string`	The capacity type of your managed node group. (ON_DEMAND, SPOT, CAPACITY_BLOCK)
`cluster_name`	`string`	The name of your cluster.
`created_at`	`string (date-time)`	The Unix epoch timestamp at object creation.
`disk_size`	`integer`	If the node group wasn't deployed with a launch template, then this is the disk size in the node group configuration. If the node group was deployed with a launch template, then this is null.
`health`	`object`	The health status of the node group. If there are issues with your node group's health, they are listed here.
`instance_types`	`array`	If the node group wasn't deployed with a launch template, then this is the instance type that is associated with the node group. If the node group was deployed with a launch template, then this is null.
`labels`	`object`	The Kubernetes labels applied to the nodes in the node group. Only labels that are applied with the Amazon EKS API are shown here. There may be other Kubernetes labels applied to the nodes in this group.
`launch_template`	`object`	An object representing a node group launch template specification. The launch template can't include SubnetId , IamInstanceProfile , RequestSpotInstances , HibernationOptions , or TerminateInstances , or the node group deployment or update will fail. For more information about launch templates, see CreateLaunchTemplate in the Amazon EC2 API Reference. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide. You must specify either the launch template ID or the launch template name in the request, but not both.
`modified_at`	`string (date-time)`	The Unix epoch timestamp for the last modification to the object.
`node_repair_config`	`object`	The node auto repair configuration for the node group.
`node_role`	`string`	The IAM role associated with your node group. The Amazon EKS node kubelet daemon makes calls to Amazon Web Services APIs on your behalf. Nodes receive permissions for these API calls through an IAM instance profile and associated policies.
`nodegroup_arn`	`string`	The Amazon Resource Name (ARN) associated with the managed node group.
`nodegroup_name`	`string`	The name associated with an Amazon EKS managed node group.
`release_version`	`string`	If the node group was deployed using a launch template with a custom AMI, then this is the AMI ID that was specified in the launch template. For node groups that weren't deployed using a launch template, this is the version of the Amazon EKS optimized AMI that the node group was deployed with.
`remote_access`	`object`	An object representing the remote access configuration for the managed node group.
`resources`	`object`	The resources associated with the node group, such as Auto Scaling groups and security groups for remote access.
`scaling_config`	`object`	An object representing the scaling configuration details for the Auto Scaling group that is associated with your node group. When creating a node group, you must specify all or none of the properties. When updating a node group, you can specify any or none of the properties.
`status`	`string`	The current status of the managed node group. (CREATING, ACTIVE, UPDATING, DELETING, CREATE_FAILED, DELETE_FAILED, DEGRADED)
`subnets`	`array`	The subnets that were specified for the Auto Scaling group that is associated with your node group.
`tags`	`object`	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 Amazon Web Services resources.
`taints`	`array`	The Kubernetes taints to be applied to the nodes in the node group when they are created. Effect is one of No_Schedule, Prefer_No_Schedule, or No_Execute. Kubernetes taints can be used together with tolerations to control how workloads are scheduled to your nodes. For more information, see Node taints on managed node groups.
`update_config`	`object`	The node group update configuration. An Amazon EKS managed node group updates by replacing nodes with new nodes of newer AMI versions in parallel. You choose the maximum unavailable and the update strategy.
`version`	`string`	The Kubernetes version of the managed node group.
`warm_pool_config`	`object`	The configuration for an Amazon EC2 Auto Scaling warm pool attached to an Amazon EKS managed node group. Warm pools maintain pre-initialized EC2 instances alongside your Auto Scaling group that have already completed the bootup initialization process and can be kept in a Stopped, Running, or Hibernated state.

Name	Datatype	Description
`nodegroup`	`string`	A list of all of the node groups associated with the specified cluster.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`describe_nodegroup`	`select`	`name`, `nodegroup_name`, `region`		Describes a managed node group.
`list_nodegroups`	`select`	`name`, `region`	`maxResults`, `nextToken`	Lists the managed node groups associated with the specified cluster in your Amazon Web Services account in the specified Amazon Web Services Region. Self-managed node groups aren't listed.
`create_nodegroup`	`insert`	`name`, `region`, `nodegroupName`, `subnets`, `nodeRole`		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 later updates, you will only be able to update a node group using a launch template only if it was originally deployed with a launch template. Additionally, the launch template ID or name must match what was used when the node group was created. You can update the launch template version with necessary changes. 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 Amazon Web Services for an Amazon EKS cluster. For more information, see Managed node groups in the Amazon EKS User Guide. Windows AMI types are only supported for commercial Amazon Web Services Regions that support Windows on Amazon EKS.
`update_nodegroup_config`	`update`	`name`, `nodegroup_name`, `region`		Updates an Amazon EKS managed node group configuration. Your node group continues to function during the update. The response output includes an update ID that you can use to track the status of your node group update with the DescribeUpdate API operation. You can update the Kubernetes labels and taints for a node group and the scaling and version update configuration.
`delete_nodegroup`	`delete`	`name`, `nodegroup_name`, `region`		Deletes a managed node group.
`update_nodegroup_version`	`exec`	`name`, `nodegroup_name`, `region`		Updates the Kubernetes version or AMI version of an Amazon EKS managed node group. You can update a node group using a launch template only if the node group was originally deployed with a launch template. Additionally, the launch template ID or name must match what was used when the node group was created. You can update the launch template version with necessary changes. If you need to update a custom AMI in a node group that was deployed with a launch template, then update your custom AMI, specify the new ID in a new version of the launch template, and then update the node group to the new version of the launch template. If you update without a launch template, then you can update to the latest available AMI version of a node group's current Kubernetes version by not specifying a Kubernetes version in the request. You can update to the latest AMI version of your cluster's current Kubernetes version by specifying your cluster's Kubernetes version in the request. For information about Linux versions, see Amazon EKS optimized Amazon Linux AMI versions in the Amazon EKS User Guide. For information about Windows versions, see Amazon EKS optimized Windows AMI versions in the Amazon EKS User Guide. You cannot roll back a node group to an earlier Kubernetes version or AMI version. When a node in a managed node group is terminated due to a scaling action or update, every Pod on that node is drained first. Amazon EKS attempts to drain the nodes gracefully and will fail if it is unable to do so. You can force the update if Amazon EKS is unable to drain the nodes as a result of a Pod disruption budget issue.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`name`	`string`	The name of your cluster.
`nodegroup_name`	`string`	The name of the managed node group to update.
`region`	`string`	AWS region (default: us-east-1)
`maxResults`	`integer`	The maximum number of results, returned in paginated output. You receive maxResults in a single page, along with a nextToken response element. You can see the remaining results of the initial request by sending another request with the returned nextToken value. This value can be between 1 and 100. If you don't use this parameter, 100 results and a nextToken value, if applicable, are returned.
`nextToken`	`string`	The nextToken value returned from a previous paginated request, where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value. This value is null when there are no more results to return. This token should be treated as an opaque identifier that is used only to retrieve the next items in a list and not for other programmatic purposes.

`SELECT` examples

describe_nodegroup
list_nodegroups

Describes a managed node group.

SELECT
ami_type,
capacity_type,
cluster_name,
created_at,
disk_size,
health,
instance_types,
labels,
launch_template,
modified_at,
node_repair_config,
node_role,
nodegroup_arn,
nodegroup_name,
release_version,
remote_access,
resources,
scaling_config,
status,
subnets,
tags,
taints,
update_config,
version,
warm_pool_config
FROM aws.eks.nodegroups
WHERE name = '{{ name }}' -- required
AND nodegroup_name = '{{ nodegroup_name }}' -- required
AND region = '{{ region }}' -- required
;

Lists the managed node groups associated with the specified cluster in your Amazon Web Services account in the specified Amazon Web Services Region. Self-managed node groups aren't listed.

SELECT
nodegroup
FROM aws.eks.nodegroups
WHERE name = '{{ name }}' -- required
AND region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

`INSERT` examples

create_nodegroup
Manifest

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 later updates, you will only be able to update a node group using a launch template only if it was originally deployed with a launch template. Additionally, the launch template ID or name must match what was used when the node group was created. You can update the launch template version with necessary changes. 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 Amazon Web Services for an Amazon EKS cluster. For more information, see Managed node groups in the Amazon EKS User Guide. Windows AMI types are only supported for commercial Amazon Web Services Regions that support Windows on Amazon EKS.

INSERT INTO aws.eks.nodegroups (
nodegroupName,
scalingConfig,
diskSize,
subnets,
instanceTypes,
amiType,
remoteAccess,
nodeRole,
labels,
taints,
tags,
clientRequestToken,
launchTemplate,
updateConfig,
nodeRepairConfig,
capacityType,
version,
releaseVersion,
warmPoolConfig,
name,
region
)
SELECT 
'{{ nodegroupName }}' /* required */,
'{{ scalingConfig }}',
{{ diskSize }},
'{{ subnets }}' /* required */,
'{{ instanceTypes }}',
'{{ amiType }}',
'{{ remoteAccess }}',
'{{ nodeRole }}' /* required */,
'{{ labels }}',
'{{ taints }}',
'{{ tags }}',
'{{ clientRequestToken }}',
'{{ launchTemplate }}',
'{{ updateConfig }}',
'{{ nodeRepairConfig }}',
'{{ capacityType }}',
'{{ version }}',
'{{ releaseVersion }}',
'{{ warmPoolConfig }}',
'{{ name }}',
'{{ region }}'
RETURNING
nodegroup
;

# Description fields are for documentation purposes
- name: nodegroups
props:
  - name: name
    value: "{{ name }}"
    description: Required parameter for the nodegroups resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the nodegroups resource.
  - name: nodegroupName
    value: "{{ nodegroupName }}"
  - name: scalingConfig
    description: |
      An object representing the scaling configuration details for the Auto Scaling group that is associated with your node group. When creating a node group, you must specify all or none of the properties. When updating a node group, you can specify any or none of the properties.
    value:
      minSize: {{ minSize }}
      maxSize: {{ maxSize }}
      desiredSize: {{ desiredSize }}
  - name: diskSize
    value: {{ diskSize }}
  - name: subnets
    value:
      - "{{ subnets }}"
  - name: instanceTypes
    value:
      - "{{ instanceTypes }}"
  - name: amiType
    value: "{{ amiType }}"
    valid_values: ['AL2_x86_64', 'AL2_x86_64_GPU', 'AL2_ARM_64', 'CUSTOM', 'BOTTLEROCKET_ARM_64', 'BOTTLEROCKET_x86_64', 'BOTTLEROCKET_ARM_64_FIPS', 'BOTTLEROCKET_x86_64_FIPS', 'BOTTLEROCKET_ARM_64_NVIDIA', 'BOTTLEROCKET_x86_64_NVIDIA', 'BOTTLEROCKET_ARM_64_NVIDIA_FIPS', 'BOTTLEROCKET_x86_64_NVIDIA_FIPS', 'WINDOWS_CORE_2019_x86_64', 'WINDOWS_FULL_2019_x86_64', 'WINDOWS_CORE_2022_x86_64', 'WINDOWS_FULL_2022_x86_64', 'WINDOWS_CORE_2025_x86_64', 'WINDOWS_FULL_2025_x86_64', 'AL2023_x86_64_STANDARD', 'AL2023_ARM_64_STANDARD', 'AL2023_x86_64_NEURON', 'AL2023_x86_64_NVIDIA', 'AL2023_ARM_64_NVIDIA']
  - name: remoteAccess
    description: |
      An object representing the remote access configuration for the managed node group.
    value:
      ec2SshKey: "{{ ec2SshKey }}"
      sourceSecurityGroups:
        - "{{ sourceSecurityGroups }}"
  - name: nodeRole
    value: "{{ nodeRole }}"
  - name: labels
    value: "{{ labels }}"
  - name: taints
    value:
      - key: "{{ key }}"
        value: "{{ value }}"
        effect: "{{ effect }}"
  - name: tags
    value: "{{ tags }}"
    description: |
      The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them. The following basic restrictions apply to tags: Maximum number of tags per resource – 50 For each resource, each tag key must be unique, and each tag key can have only one value. Maximum key length – 128 Unicode characters in UTF-8 Maximum value length – 256 Unicode characters in UTF-8 If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @. Tag keys and values are case-sensitive. Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
  - name: clientRequestToken
    value: "{{ clientRequestToken }}"
  - name: launchTemplate
    description: |
      An object representing a node group launch template specification. The launch template can't include SubnetId , IamInstanceProfile , RequestSpotInstances , HibernationOptions , or TerminateInstances , or the node group deployment or update will fail. For more information about launch templates, see CreateLaunchTemplate in the Amazon EC2 API Reference. For more information about using launch templates with Amazon EKS, see Customizing managed nodes with launch templates in the Amazon EKS User Guide. You must specify either the launch template ID or the launch template name in the request, but not both.
    value:
      name: "{{ name }}"
      version: "{{ version }}"
      id: "{{ id }}"
  - name: updateConfig
    description: |
      The node group update configuration. An Amazon EKS managed node group updates by replacing nodes with new nodes of newer AMI versions in parallel. You choose the maximum unavailable and the update strategy.
    value:
      maxUnavailable: {{ maxUnavailable }}
      maxUnavailablePercentage: {{ maxUnavailablePercentage }}
      updateStrategy: "{{ updateStrategy }}"
  - name: nodeRepairConfig
    description: |
      The node auto repair configuration for the node group.
    value:
      enabled: {{ enabled }}
      maxUnhealthyNodeThresholdCount: {{ maxUnhealthyNodeThresholdCount }}
      maxUnhealthyNodeThresholdPercentage: {{ maxUnhealthyNodeThresholdPercentage }}
      maxParallelNodesRepairedCount: {{ maxParallelNodesRepairedCount }}
      maxParallelNodesRepairedPercentage: {{ maxParallelNodesRepairedPercentage }}
      nodeRepairConfigOverrides:
        - nodeMonitoringCondition: "{{ nodeMonitoringCondition }}"
          nodeUnhealthyReason: "{{ nodeUnhealthyReason }}"
          minRepairWaitTimeMins: {{ minRepairWaitTimeMins }}
          repairAction: "{{ repairAction }}"
  - name: capacityType
    value: "{{ capacityType }}"
    valid_values: ['ON_DEMAND', 'SPOT', 'CAPACITY_BLOCK']
  - name: version
    value: "{{ version }}"
  - name: releaseVersion
    value: "{{ releaseVersion }}"
  - name: warmPoolConfig
    description: |
      The configuration for an Amazon EC2 Auto Scaling warm pool attached to an Amazon EKS managed node group. Warm pools maintain pre-initialized EC2 instances alongside your Auto Scaling group that have already completed the bootup initialization process and can be kept in a Stopped, Running, or Hibernated state.
    value:
      enabled: {{ enabled }}
      minSize: {{ minSize }}
      maxGroupPreparedCapacity: {{ maxGroupPreparedCapacity }}
      poolState: "{{ poolState }}"
      reuseOnScaleIn: {{ reuseOnScaleIn }}

`UPDATE` examples

update_nodegroup_config

Updates an Amazon EKS managed node group configuration. Your node group continues to function during the update. The response output includes an update ID that you can use to track the status of your node group update with the DescribeUpdate API operation. You can update the Kubernetes labels and taints for a node group and the scaling and version update configuration.

UPDATE aws.eks.nodegroups
SET 
labels = '{{ labels }}',
taints = '{{ taints }}',
scalingConfig = '{{ scalingConfig }}',
updateConfig = '{{ updateConfig }}',
nodeRepairConfig = '{{ nodeRepairConfig }}',
warmPoolConfig = '{{ warmPoolConfig }}',
clientRequestToken = '{{ clientRequestToken }}'
WHERE 
name = '{{ name }}' --required
AND nodegroup_name = '{{ nodegroup_name }}' --required
AND region = '{{ region }}' --required
RETURNING
update;

`DELETE` examples

delete_nodegroup

Deletes a managed node group.

DELETE FROM aws.eks.nodegroups
WHERE name = '{{ name }}' --required
AND nodegroup_name = '{{ nodegroup_name }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

update_nodegroup_version

Updates the Kubernetes version or AMI version of an Amazon EKS managed node group. You can update a node group using a launch template only if the node group was originally deployed with a launch template. Additionally, the launch template ID or name must match what was used when the node group was created. You can update the launch template version with necessary changes. If you need to update a custom AMI in a node group that was deployed with a launch template, then update your custom AMI, specify the new ID in a new version of the launch template, and then update the node group to the new version of the launch template. If you update without a launch template, then you can update to the latest available AMI version of a node group's current Kubernetes version by not specifying a Kubernetes version in the request. You can update to the latest AMI version of your cluster's current Kubernetes version by specifying your cluster's Kubernetes version in the request. For information about Linux versions, see Amazon EKS optimized Amazon Linux AMI versions in the Amazon EKS User Guide. For information about Windows versions, see Amazon EKS optimized Windows AMI versions in the Amazon EKS User Guide. You cannot roll back a node group to an earlier Kubernetes version or AMI version. When a node in a managed node group is terminated due to a scaling action or update, every Pod on that node is drained first. Amazon EKS attempts to drain the nodes gracefully and will fail if it is unable to do so. You can force the update if Amazon EKS is unable to drain the nodes as a result of a Pod disruption budget issue.

EXEC aws.eks.nodegroups.update_nodegroup_version 
@name='{{ name }}' --required, 
@nodegroup_name='{{ nodegroup_name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"version": "{{ version }}", 
"releaseVersion": "{{ releaseVersion }}", 
"launchTemplate": "{{ launchTemplate }}", 
"force": {{ force }}, 
"clientRequestToken": "{{ clientRequestToken }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​