# Create a cluster

Create a Kubernetes cluster with a dev or standard control plane, in a network you choose, optionally with a first node group.

Replace _my-cluster_ with the cluster's name: lowercase letters, digits and hyphens, starting with
a letter, at most 40 characters, unique in the organization.

**Important:**
The tier and the network cannot be changed after creation. You pay the control-plane fee from the
moment the cluster is active.

## Prerequisites

- Permission for `eks:CreateCluster`. With a first node group, also `eks:CreateNodegroup`, and
  `iam:PassRole` on its node role if you set one. With add-ons (by default `metrics-server`), also
  `eks:CreateAddon`, and for `external-dns` or `cert-manager` with zones, `dns:ChangeRecords` on
  each zone listed.
- In the console, also `eks:ListClusters` to open **Kubernetes**, and `eks:DescribeCluster` for
  the cluster's page the console opens afterwards. Without `eks:CreateNodegroup` the form has no
  **Nodes** section.
- To create in `fi1`, your organization must allow EU locations outside Germany; otherwise the
  create answers `403`.

## Create the cluster

**Console**
1. Open **Kubernetes**, then choose **Create cluster**.
2. Under **Basics**, for **Name**, enter my-cluster.
3. For **Kubernetes version**, keep the version marked **(recommended)** or choose another.
4. For **Control plane**, choose **Dev** (one machine, no SLA) or **Standard** (three machines).
5. (Optional) Select **Deletion protection**.
6. Under **Network**, for **Network**, choose the network the nodes join. Without a default network,
   **Default network** creates one with the cluster.
7. For **API endpoint access**, choose **Public and private**, **Public only** or **Private only**.
   With public access, for **Allowed networks**, enter the IPv4 CIDRs that may reach the endpoint,
   one per line (`0.0.0.0/0` is everywhere).
8. Under **Nodes**, keep **Add a first node group now** selected, or clear it to add nodes later.
9. For **Server type**, choose the node type; for **Nodes**, enter 1 to 20.
10. (Optional) Under **Node options**, enter **Labels**, **Taints** and a **Node IAM role**.
11. (Optional) Under **Capacity**, select or clear **Use an equivalent type when this one is sold
    out** (selected by default) and **Use another zone of … that has it**.
12. Choose **Create cluster**.

The console opens the cluster's page. The first node group is named `default`, with a minimum of 1
and a maximum of the node count or 3, whichever is larger. The console installs
`metrics-server` and sends no zones, so the nodes go in the region's default zone, unless you
selected **Use another zone of … that has it** and the server type is sold out there.

**CLI**
```sh
dcloud eks clusters create --name my-cluster --tier standard \
  --allowed-cidrs 203.0.113.0/24 \
  --nodegroup '{"name":"workers","instanceType":"performance-4","minSize":1,"desiredSize":2,"maxSize":3,"zones":["de1a","de1b"]}'
```

**API**
```http
POST /eks/api/clusters
{
  "name": "my-cluster",
  "tier": "standard",
  "allowedCidrs": ["203.0.113.0/24"],
  "nodegroup": {
    "name": "workers",
    "instanceType": "performance-4",
    "minSize": 1,
    "desiredSize": 2,
    "maxSize": 3,
    "zones": ["de1a", "de1b"]
  }
}
```

**Terraform**
```hcl
resource "dcloud_eks_cluster" "main" {
  name          = "my-cluster"
  tier          = "standard"
  allowed_cidrs = ["203.0.113.0/24"]
}
```

Add nodes with a `dcloud_eks_nodegroup`; see [Add a node group](add-a-node-group.md).

## Defaults

| Field                                            | API default                                    |
| ------------------------------------------------ | ---------------------------------------------- |
| `tier`                                           | `dev`                                          |
| `version`                                        | `defaultVersion` of `eks versions list`        |
| `vpcId`                                          | the region's default network (created if none) |
| `endpointPublicAccess` / `endpointPrivateAccess` | both `true`                                    |
| `allowedCidrs`                                   | `0.0.0.0/0`                                    |
| `addons`                                         | `metrics-server`; `[]` installs none           |
| `logging`                                        | `audit` only                                   |
| `deletionProtection`                             | `false`                                        |
| `nodegroup.capacityFallback`                     | off (the console turns `equivalentTypes` on)   |

A first node group created with the cluster always starts with autoscaling off and the default
drain settings; change them afterwards with `dcloud eks nodegroups update`.

## Result

The answer is `201` with the cluster in status `creating`. Deutsche Cloud builds the endpoint load
balancer and the control-plane machines, then the first node group and the add-ons. Each step is in
the cluster's **Activity** (`dcloud eks clusters events my-cluster`). You get a
`ClusterAdmin` access entry on the cluster.

## Refusals

- `400`: a version past its end of support, a network in another region, a node type that cannot
  run a node, an unknown zone, an add-on listed twice or not offered, a missing required tag.
- `403`: `fi1` without the organization setting, or a missing permission named above.
- `404`: an unknown `vpcId` or node role, or an add-on zone that is not a hosted zone of the
  organization.
- `409` "A cluster named "_my-cluster_" already exists", a quota is full, or an add-on version that
  does not support the cluster's Kubernetes minor.

## Related

- [Clusters and node groups](clusters-and-node-groups.md)
- [Connect with kubectl](connect-with-kubectl.md)
- `eks.clusters.create` · `dcloud eks clusters create` · `dcloud_eks_cluster`
