Skip to main content

Create a cluster

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 , 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 and . 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 . For how cloud and bare-metal servers compare, see .

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.

Open the Cluster Configurator

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

Define a Cluster

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:

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

Watch it come up 

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

				$ 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.
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:

				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 Ctrl+ C to stop watching. Then check the cluster as a whole:

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

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:

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

Edit the file directly, or load it into the 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:

Next step 

Your cluster is running. Continue with to connect to it.

Related 

Run It Yourself, or With Help

Every service on Syself Autopilot is standard Kubernetes objects in your own cluster, so you can run it yourself, have Syself operate it, or move between the two per service without migrating anything.

Get the kubeconfig of a cluster

Fetch the kubeconfig of a workload cluster from the management cluster, point kubectl at it, and confirm every node is Ready.