Add a node group

Add a set of compute instances of one server type that join the cluster as nodes, with labels, taints, zones and an optional IAM role for image pulls.

Last updated 18 November 2026View as Markdown

Replace my-cluster with your cluster's name or id, and workers with the node group's name: lowercase letters, digits and hyphens, starting with a letter, at most 32 characters.

Each node is billed as a compute instance from the moment it is created.

Prerequisites

  • Permission for eks:CreateNodegroup. With a node role, also iam:PassRole on that role.
  • In the console, also eks:DescribeCluster to open the cluster and eks:ListNodegroups on it: without it the Node groups tab shows neither the groups nor the form to add one. The console offers Add node group only with eks:CreateNodegroup on every cluster (eks:*).
  • The cluster is not being upgraded or deleted, and its Kubernetes minor is not past its end of support.
  • A server type with at least a 40 GB disk and 2 GiB of memory.

Add the node group

  1. Open Kubernetes, open the cluster, then choose Node groups.
  2. Under Add a node group, for Name, enter workers.
  3. For Server type, choose a type. Types too small for a node, and types sold out in every zone, are greyed.
  4. Enter Minimum, Desired and Maximum (0 to 20, maximum at least 1).
  5. (Optional) Turn on Autoscaling.
  6. (Optional) Under Zones, select the zones the nodes spread over. None selected: the region's default zone.
  7. (Optional) Enter labels (one key=value per line) and taints (one key=value:Effect per line).
  8. (Optional) For the node IAM role, enter the name of an IAM role.
  9. (Optional) Add Tags. The node group takes the cluster's tags; keys you enter win.
  10. Choose Add node group.

The node group appears in the table with status creating.

Pull private images without secrets

Give the node group an IAM role (nodeRole, Node IAM role in the console) that may pull from your Deutsche Cloud container registry. The nodes' kubelet then pulls images from the registry as that role, with credentials it fetches itself: no imagePullSecrets are needed. The node role cannot be changed after creation.

When the server type is sold out

New nodes go in those of the group's zones that sell its type. Opt in to more with instanceTypes (types to buy, in order, when instanceType is sold out; same CPU architecture) and capacityFallback: equivalentTypes lets Deutsche Cloud buy an equivalent type, otherZones lets nodes go in the region's zones outside zones. Both are off by default in the API. Each node keeps the type it was bought as. With nothing in stock, the group's error says so and nodes are added when the type is back.

Result

The answer is 201 with the node group and no nodes yet. Its nodes are built in the background, run the cluster's Kubernetes minor, and join within minutes; Activity records each one. A node that does not join within 20 minutes is replaced; after three failed nodes the group stops with status failed until you change it (see Change a node group).

Refusals

  • 400 for a type that cannot run a node (the message names the type and its disk or memory), a zone outside the cluster's region, a cluster minor past its end of support, or a missing required tag.
  • 404 for an unknown node role.
  • 409 "A node group named "workers" already exists", "The cluster is being deleted", "The control plane is being upgraded; add the node group once it is done", or a quota is full (the quotas count maxSize).
Did this page help you?