# 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.

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

**Console**
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`.

**CLI**
```sh
dcloud eks nodegroups create my-cluster --name workers \
  --instance-type performance-4 --min-size 1 --desired-size 2 --max-size 5 \
  --zones de1a --zones de1b --labels workload=web
```

**API**
```http
POST /eks/api/clusters/my-cluster/nodegroups
{
  "name": "workers",
  "instanceType": "performance-4",
  "minSize": 1,
  "desiredSize": 2,
  "maxSize": 5,
  "zones": ["de1a", "de1b"],
  "labels": { "workload": "web" },
  "taints": [{ "key": "dedicated", "value": "batch", "effect": "NoSchedule" }]
}
```

**Terraform**
```hcl
resource "dcloud_eks_nodegroup" "workers" {
  cluster_id    = dcloud_eks_cluster.main.id
  name          = "workers"
  instance_type = "performance-4"
  min_size      = 1
  desired_size  = 2
  max_size      = 5
  zones         = ["de1a", "de1b"]
}
```

## 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](change-a-node-group.md)).

## 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`).

## Related

- [Clusters and node groups](clusters-and-node-groups.md)
- [Turn on autoscaling](turn-on-autoscaling.md)
- `eks.nodegroups.create` · `dcloud eks nodegroups create` · `dcloud_eks_nodegroup`
