To create a cluster, you describe it in a `Cluster` object and apply that object to the management cluster. Syself Autopilot then provisions the Kubernetes cluster on your Hetzner account. You can write the `Cluster` object yourself, or generate it with the [Cluster Configurator](/docs/hetzner/apalla/cluster-configurator), which guides you through every option. When the cluster is ready, you fetch its kubeconfig to connect to it.

## Before you start

You need access to the management cluster, with your Hetzner credentials stored there. See [Access the management cluster](/docs/hetzner/apalla/platform/setup/access-the-management-cluster) and [Connect your Hetzner account](/docs/hetzner/apalla/platform/setup/connect-your-hetzner-account). To confirm the connection works, run `kubectl get clusters`. It lists every cluster in your organization, so an empty list just means you have not created one yet.

If you plan to use bare-metal servers, register them as hosts first. See [Add bare-metal servers](/docs/hetzner/apalla/servers-and-nodes/bare-metal/add-bare-metal-servers). For how cloud and bare-metal servers compare, see [Servers and nodes](/docs/hetzner/apalla/servers-and-nodes/overview).

In the commands below, `<namespace>` is your organization's namespace on the management cluster, in the format `org-<company-name>`.

## Configure the cluster

The Cluster Configurator generates a `Cluster` object as you fill in the fields, and validates each field as you go. Download or copy the result, then apply it yourself or commit it to Git for a GitOps tool to apply.

<Card title="Open the Cluster Configurator" href="/docs/hetzner/apalla/cluster-configurator" cta={true} ctaLabel="Define a Cluster">

Fill in the fields, then download or copy the `Cluster` object.

</Card>

The rest of this page calls the manifest file `<name>.yaml`, where `<name>` is the cluster name.

### Create referenced secrets first

The manifest only references secrets by name. A secret you reference, such as the etcd encryption key, must exist in `<namespace>` on the management cluster before you apply the manifest.

## Create the cluster

Apply the file to the management cluster:

```console
$ kubectl apply -f <name>.yaml
cluster.cluster.x-k8s.io/<name> created
```

The command returns as soon as the manifest is stored. The real work starts now, in the background. Syself Autopilot orders the servers from Hetzner, boots each one from the node image, and joins them into one cluster. This takes five to ten minutes.

If you manage clusters from Git, commit the file instead and let your GitOps tool apply it. See [Introduction to GitOps](/docs/hetzner/apalla/clusters/gitops/overview).

## Watch it come up

Each server appears as a Machine object in the management cluster. Watch them:

```console
$ kubectl get machines -n <namespace> --watch
```

Every machine moves through the same phases:

- `Pending`: the Machine object exists, the server is not created yet.
- `Provisioning`: Hetzner is creating and booting the server.
- `Provisioned`: the server is up and joining the cluster.
- `Running`: the node joined the cluster and is healthy.

```mermaid
flowchart LR
  P["Pending<br/>server not created yet"]:::platform --> V["Provisioning<br/>Hetzner creates and boots it"]:::platform --> D["Provisioned<br/>joining the cluster"]:::platform --> R["Running<br/>healthy node"]:::platform
```

The first control plane machine reaches `Running` first. The remaining control plane machines follow one at a time, and the workers join once the Kubernetes API is available. A machine sitting in `Pending` while an earlier one provisions is normal, not a failure.

When all machines are up, every row shows `Running`:

```console vars
NAME                         CLUSTER     NODE NAME                    READY   AVAILABLE   UP-TO-DATE   PHASE     AGE   VERSION
mycluster-abc12-xyz01        mycluster   mycluster-abc12-xyz01        True    True        True         Running   10m   v1.36.6
mycluster-abc12-xyz02        mycluster   mycluster-abc12-xyz02        True    True        True         Running   9m    v1.36.6
mycluster-abc12-xyz03        mycluster   mycluster-abc12-xyz03        True    True        True         Running   8m    v1.36.6
mycluster-md-0-def34-xyz04   mycluster   mycluster-md-0-def34-xyz04   True    True        True         Running   7m    v1.36.6
```

Press <Kbd keys="Ctrl+C" /> to stop watching. Then check the cluster as a whole:

```console
$ kubectl get cluster <name> -n <namespace>
```

The cluster is ready when the `AVAILABLE` column shows `True`. Machines can all run while the cluster still finishes its own checks, so wait for both.

If a machine stays in `Provisioning` for more than a few minutes, something is wrong. See [Cluster creation fails](/docs/hetzner/apalla/clusters/troubleshooting/cluster-creation-fails) for the checks, starting with the Hetzner secret and your project quota.

## Connect to the cluster

The new cluster has its own credentials, separate from the management cluster. To fetch them and point `kubectl` at the cluster, see [Get the kubeconfig of a cluster](/docs/hetzner/apalla/clusters/create/get-the-kubeconfig).

## Change the cluster later

The `Cluster` object is where you define what you want your cluster to look like: its configuration and its node pools. To change the cluster, change that object and apply it to the management cluster again. Syself Autopilot sees the difference and carries out the change.

Start from the manifest you applied, or export the current one:

```console
$ kubectl get cluster <name> -n <namespace> -o yaml > <name>.yaml
```

Edit the file directly, or load it into the [Cluster Configurator](/docs/hetzner/apalla/cluster-configurator) with **Import YAML** and edit it there. Then apply it with `kubectl apply -f <name>.yaml`, or commit it and let your GitOps tool apply it.

The most common changes have their own guides:

- [Upgrade the cluster to a new Kubernetes version](/docs/hetzner/apalla/clusters/upgrades/upgrade-to-a-new-kubernetes-version) to move to a newer Kubernetes release.
- [Scale a node pool](/docs/hetzner/apalla/servers-and-nodes/pools/scale-a-pool) to add or remove workers.
- [Add cloud servers](/docs/hetzner/apalla/servers-and-nodes/cloud/add-cloud-servers) for a new cloud pool.
- [Add bare-metal servers](/docs/hetzner/apalla/servers-and-nodes/bare-metal/add-bare-metal-servers) for dedicated servers.
- [Using Cluster Autoscaler](/docs/hetzner/apalla/servers-and-nodes/scale/autoscale-node-pools) to let a pool grow and shrink with demand.
- [Introduction to GitOps](/docs/hetzner/apalla/clusters/gitops/overview) once several people change the cluster.

## Next step

Your cluster is running. Continue with [Get the kubeconfig of a cluster](/docs/hetzner/apalla/clusters/create/get-the-kubeconfig) to connect to it.

## Related

- [Get the kubeconfig of a cluster](/docs/hetzner/apalla/clusters/create/get-the-kubeconfig)
- [Cluster Configurator](/docs/hetzner/apalla/cluster-configurator)
- [Concepts: declarative cluster management](/docs/hetzner/apalla/concepts/foundations/declarative-cluster-management)
- [Concepts: self-healing and node replacement](/docs/hetzner/apalla/concepts/operations/self-healing-and-node-replacement)
- [Troubleshooting: cluster creation fails](/docs/hetzner/apalla/clusters/troubleshooting/cluster-creation-fails)