# Clusters and node groups

What a cluster and a node group are, the two control-plane tiers, zones, the network ranges and the statuses you see.

## Clusters

A cluster is a Kubernetes control plane that Deutsche Cloud runs on its own machines, and an API
endpoint `https://<cluster id>.k8s.apps.<Deutsche Cloud domain>:6443` (the domain of the
Deutsche Cloud installation, not one of yours). You address a cluster by its id
(`ewk-` and twelve hex digits) or by its name, which is unique in the organization: lowercase
letters, digits and hyphens, starting with a letter, at most 40 characters.

| Tier       | Control plane                                                         | SLA                     |
| ---------- | --------------------------------------------------------------------- | ----------------------- |
| `dev`      | One machine. The default.                                             | none                    |
| `standard` | Three machines behind a load balancer, spread over the region's zones | 99.9 % API availability |

The control-plane machines are Deutsche Cloud's: they are not in Compute, are not billed as
machines (the cluster's hourly fee covers them), and are not nodes of the cluster. The tier cannot
be changed after creation.

| Item            | Value                                                                     |
| --------------- | ------------------------------------------------------------------------- |
| Versions        | Kubernetes 1.36 and 1.37; see [Version support](version-support.md)       |
| Pod network     | `100.64.0.0/14`                                                           |
| Service network | `100.68.0.0/16`                                                           |
| Endpoint access | public (to the networks you allow), private (inside the network), or both |

## Node groups

A node group is a set of compute instances of one server type that join the cluster as nodes;
when that type is sold out, a stock fallback you set (`instanceTypes`, or `capacityFallback`
with `equivalentTypes`) can buy another type. Its
name is unique in the cluster: lowercase letters, digits and hyphens, starting with a letter, at
most 32 characters. It has three sizes, with `minSize ≤ desiredSize ≤ maxSize`: the group runs
`desiredSize` nodes, and the cluster autoscaler, when it is on, moves `desiredSize` between the other
two. The quotas count `maxSize`.

- Each node is a compute instance in the cluster's network. It appears in Compute, locked to its
  node group: scale or delete the node group instead.
- A node's server type needs at least a 40 GB disk and 2 GiB of memory. Smaller types are refused.
- Every node carries the label `eks.ews.cloud/nodegroup=<name>`, plus the group's own labels and
  taints. Label keys under `kubernetes.io/`, `k8s.io/` and `eks.ews.cloud/` are Deutsche Cloud's and
  refused.
- Nodes run the node group's Kubernetes minor, which may be up to three minors behind the control
  plane and never ahead of it.

## Zones

A node group spreads its nodes over the zones you list for it: each new node goes to the listed
zone with the fewest of the group's nodes among those that have one of its server types in stock.
With no zones listed, nodes go to the region's default zone (`de1a` in `de1`). With
`capacityFallback.otherZones` on, a node can go to another zone of the region when the listed ones
are sold out. A change of zones applies to nodes created from then on; nothing moves.

PersistentVolumes are zonal: a volume is created in the zone of the node its first pod is scheduled
to, and pods using it are scheduled in that zone afterwards.

## Statuses

| Cluster     | Meaning                                                                    |
| ----------- | -------------------------------------------------------------------------- |
| `creating`  | The endpoint and the control-plane machines are being built.               |
| `active`    | The control plane is up.                                                   |
| `updating`  | A control-plane upgrade is replacing the machines one at a time.           |
| `restoring` | The control plane is being rebuilt from an etcd snapshot.                  |
| `deleting`  | Machines, endpoint and firewalls are being removed.                        |
| `failed`    | Provisioning stopped; the reason is on the cluster's page and in Activity. |

| Node group | Meaning                                                                     |
| ---------- | --------------------------------------------------------------------------- |
| `creating` | Its first nodes are being made.                                             |
| `active`   | `desiredSize` nodes, all Ready.                                             |
| `updating` | Nodes are being added, removed or replaced.                                 |
| `degraded` | A node is NotReady.                                                         |
| `paused`   | An upgrade stopped at a node a PodDisruptionBudget holds.                   |
| `failed`   | Three nodes in a row failed; no node is created until you change the group. |
| `deleting` | Its nodes are drained and removed.                                          |

## Related

- [Create a cluster](create-a-cluster.md)
- [Add a node group](add-a-node-group.md)
- [What runs on your machines](what-runs-on-your-machines.md)
