First Cluster

A detailed walkthrough of the cluster.lok8s.yaml configuration file.

Prerequisites

• lok8s CLI installed
• A Hetzner Cloud account with an API token
• An SSH key pair (Ed25519 recommended)

Full configuration reference

# cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: KubeOne
metadata:
  name: my-cluster
spec:
  kubernetes:
    version: "v1.35.5"
  cluster:
    domain: example.com          # cluster domain for ingress/certs
    namespace: default           # default namespace for workloads
  provider: hetzner
  hcloud:
    region: fsn1                 # fsn1, nbg1, or hel1
    sshPublicKeyFile: "~/.ssh/id_ed25519.pub"
    network:
      cidr: "10.0.0.0/16"       # private network range
  ssh:
    user: root
    publicKeyFile: "~/.ssh/id_ed25519.pub"
    privateKeyFile: "~/.ssh/id_ed25519"
  controlPlane:
    replicas: 3                  # 1 for dev, 3 for HA production
    type: cx33                   # Hetzner server type
  workers:
    platform:
      replicas: 2
      type: cpx31                # or 'dedicated' for bare metal
  bootstrap:                     # cluster-infra addons, applied in order
    - cilium                     # CNI (the default if omitted)
    - ccm                        # Hetzner cloud-controller-manager
    - cert-manager
    - monitoring
  kubehz:
    hosting: self                # 'self' (available) or 'hosted' (early access)
    access: registered           # 'none', 'registered', or 'managed' (Supporter+)
    apiUrl: https://api.kubehz.cloud

Key sections

spec.kubernetes

Set the Kubernetes version. Supported versions: v1.33 through v1.35.

spec.hcloud

Hetzner Cloud settings. region determines datacenter location. The network.cidr defines the private network for pod-to-pod communication.

spec.controlPlane

Use replicas: 1 for development clusters and replicas: 3 for production HA. The type field maps to Hetzner server types.

spec.workers

Define one or more worker pools. Each pool specifies replicas and type. Use dedicated for bare metal servers.

spec.bootstrap

An ordered list of cluster-infra addons (CNI, CCM, cert-manager, monitoring, …) applied at provision time, before any workloads land. Each entry is applied and waited on before the next. Bare names resolve to lok8s framework addons; ./path entries point at your own kustomize directories. If omitted, it defaults to cilium — every cluster needs a CNI. See the lok8s addons guide for the full list.

spec.kubehz

Optional kubehz platform integration, on two independent axes. Available today:hosting: self with access: registered — you run the cluster on your own account and kubehz gives you read-only dashboard visibility. hosting: hosted (kubehz runs the control plane) is in early access; access: managed adds kubehz's management features on top of registered — healing policies, capacity watches, and desired-state management driven from the dashboard — and requires a Supporter subscription or higher. Acting is pull-based: the in-cluster agent fetches desired state from the platform and applies it with your cluster's own credentials — kubehz never holds inbound access. See How it works for the full model and the trust boundary, and Registration to turn on visibility.

Provision your cluster

lo provision

Verify

kubectl get nodes
kubectl get pods -A

Next steps

• Dashboard setup — monitor your cluster
• Registration — connect to the kubehz dashboard
• KubeOne guide — advanced KubeOne configuration

---

Doc status

Aspect	Detail
State	active
Last reviewed	2026-07-10