Cluster API (CAPI) su Hetzner

Esegui il provisioning di cluster Kubernetes usando Cluster API con il provider di infrastruttura Hetzner (CAPH).

Prerequisiti

• La CLI lok8s installata
• Un management cluster CAPI (oppure usa lo per crearne uno)
• clusterctl installato
• Token API di Hetzner Cloud esportato come HCLOUD_TOKEN

Configurazione del cluster

Crea un cluster.lok8s.yaml con kind: Capi:

apiVersion: cluster.lok8s.dev/v1beta1
kind: Capi
metadata:
  name: capi-cluster
spec:
  kubernetes:
    version: "v1.35.5"
  provider: hetzner
  hcloud:
    region: fsn1
    sshPublicKeyFile: "~/.ssh/id_ed25519.pub"
    network:
      cidr: "10.0.0.0/16"
  controlPlane:
    replicas: 3
    type: cx33
  workers:
    platform:
      replicas: 2
      type: cpx31

Come funziona il provisioning CAPI

Quando esegui lo provision con kind: Capi, lok8s:

1. Genera i manifest CAPI Cluster e MachineDeployment
2. Li applica al management cluster
3. CAPH crea i server Hetzner Cloud
4. Kubeadm esegue il bootstrap di Kubernetes sui nodi
5. Il kubeconfig viene estratto e salvato localmente

Provisioning

lo provision

Struttura dei template

lok8s genera queste risorse CAPI dalla tua configurazione:

• Cluster — impostazioni a livello di cluster (rete, regione)
• HetznerCluster — infrastruttura specifica di Hetzner
• KubeadmControlPlane — macchine del control plane
• MachineDeployment — pool di worker node
• HetznerMachineTemplate — tipo di server e immagine

Verifica

# Controlla lo stato del cluster CAPI
kubectl get clusters -A

# Controlla i nodi del workload cluster
kubectl --kubeconfig=kubeconfig get nodes

Quando usare CAPI e quando KubeOne

Aspetto	KubeOne	CAPI
Management cluster	Non richiesto	Richiesto
Ciclo di vita dichiarativo	Parziale	Completo
Multi-cluster	Manuale	Nativo
Complessita	Inferiore	Superiore

Usa KubeOne per cluster singoli con requisiti semplici. Usa CAPI per ambienti multi-cluster o infrastrutture gestite via GitOps.

Prossimi passi

• GitHub Actions — automatizza il provisioning CAPI in CI
• Registrazione — registrazione con la dashboard kubehz
• KubeOne — provisioner alternativo piu semplice

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-07-10