KubeOne su Hetzner

Configura un cluster Kubernetes di produzione usando KubeOne come provisioner.

Prerequisiti

• La CLI lok8s installata
• La CLI hcloud installata e autenticata
• Una coppia di chiavi SSH aggiunta al tuo progetto Hetzner
• Token API di Hetzner Cloud esportato come HCLOUD_TOKEN

Configurazione del cluster

Crea clusters/example.com/cluster.lok8s.yaml con kind: KubeOne (la cartella prende il nome dal tuo dominio), poi esegui lo use example.com. Le macchine sono dichiarate nel descrittore del provider Hetzner: una voce server per nodo, con il ruolo nell’etichetta lok8s.dev/role. Vedi Primo cluster per ogni chiave.

# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: KubeOne
metadata:
  name: production
spec:
  kubernetes:
    version: "v1.35.5"
  cluster:
    # OBBLIGATORIO: un dominio che controlli; per l'endpoint API e i certificati
    domain: example.com
  provider:
    name: hetzner
    config:
      cluster_name: production
      sshUser: root
      sshPrivateKey: ~/.ssh/id_ed25519
      sshPublicKey: ~/.ssh/id_ed25519.pub
      ssh-key:
        - name: production
          public-key-from-file: ~/.ssh/id_ed25519.pub
      network:
        - name: production
          ip-range: 10.0.0.0/16
          "#subnets":
            - network-zone: eu-central
              type: cloud
              ip-range: 10.0.0.0/24
      server:
        - name: cp-1
          type: cx33
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=control-plane
        - name: cp-2
          type: cx33
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=control-plane
        - name: cp-3
          type: cx33
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=control-plane
        - name: worker-1
          type: cpx31
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=worker
        - name: worker-2
          type: cpx31
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=production,lok8s.dev/role=worker

Provisioning

lo provision

Questo comando:

1. Crea i server Hetzner Cloud per il control plane e i worker
2. Configura la rete privata
3. Installa Kubernetes tramite KubeOne
4. Scrive il kubeconfig in .kubeconfig/production.yaml nel progetto, con il nome di metadata.name, modo 0600. Il tuo ~/.kube/config non viene toccato.

La configurazione qui sopra chiede a Hetzner cinque server (3 di control plane e 2 worker), fatturati a ore ai prezzi pubblicati da Hetzner per quei tipi di server. Niente di tutto questo è irreversibile: lo destroy rimuove in qualsiasi momento ogni server creato da lok8s.

Verifica

kubectl punta ancora al contesto che usavi prima, quindi seleziona il nuovo cluster in modo esplicito; altrimenti get nodes risponde per il cluster precedente:

export KUBECONFIG=.kubeconfig/production.yaml
kubectl get nodes
# (AGE trimmed — VERSION is what to check)
# NAME       STATUS   ROLES           VERSION
# cp-1       Ready    control-plane   v1.35.5
# cp-2       Ready    control-plane   v1.35.5
# cp-3       Ready    control-plane   v1.35.5
# worker-1   Ready    <none>          v1.35.5
# worker-2   Ready    <none>          v1.35.5

Considerazioni sull’HA

• Dichiara tre server control-plane per la produzione
• I nodi del control plane vengono distribuiti automaticamente tra i fault domain
• La rete privata (network[].ip-range) isola il traffico del cluster

Aggiungere addon bootstrap

Gli addon cluster-infra (CNI, CCM, cert-manager, monitoring, …) sono elencati sotto spec.bootstrap e vengono applicati in ordine al momento del provisioning:

  bootstrap:
    - cilium
    - ccm
    - monitoring

Esegui lo bootstrap per applicare le modifiche al bootstrap a un cluster esistente: riapplica spec.bootstrap e salta la riconciliazione dell’infrastruttura. lo provision fa entrambe le cose ed è anch’esso sicuro da rieseguire.

Prossimi passi

• Registrazione: registrazione con la dashboard kubehz
• GitHub Actions: automatizza il provisioning in CI
• CAPI: provisioner alternativo basato su Cluster API

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-09-05