Cluster API (CAPI) su Hetzner

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

Un solo cluster, requisiti semplici? KubeOne è più semplice: vedi quando usare quale →

Prerequisiti

• La CLI lok8s installata
• Un management cluster CAPI, oppure lascia che lo ne crei uno locale con kind impostando managementCluster.local: true nella spec (vedi la guida CAPI di lok8s). In ogni caso managementCluster.domain è obbligatorio: dà il nome al management cluster, e local: true decide solo se lok8s lo crea invece di aspettarsi che esista già.
• clusterctl installato
• Token API di Hetzner Cloud esportato come HCLOUD_TOKEN

Configurazione del cluster

Crea clusters/example.com/cluster.lok8s.yaml con kind: Capi (la cartella prende il nome dal tuo dominio), poi esegui lo use example.com. A differenza di KubeOne, il driver Capi mantiene controlPlane e workers nello spec, perché genera da solo le risorse macchina di CAPI; il blocco del provider porta solo ciò che serve a CAPH:

# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: Capi
metadata:
  name: capi-cluster
spec:
  kubernetes:
    version: "v1.35.5"
  cluster:
    # OBBLIGATORIO: un dominio che controlli; per l'endpoint API e i certificati
    domain: example.com
  managementCluster:
    # OBBLIGATORIO per CAPI self-hosted: `lo provision` non parte senza
    domain: mgmt.example.com
    # Crealo come cluster kind locale invece di aspettarne uno esistente
    local: true
  provider:
    name: hetzner
    config:
      # fsn1, nbg1 o hel1
      region: fsn1
      # una chiave SSH che esiste nel tuo progetto Hetzner
      sshKeyName: my-key
      # immagine standard; Kubernetes viene installato via cloud-init
      image: ubuntu-24.04
      network:
        # rete privata hcloud
        enabled: true
      # distribuisci control plane e worker su host diversi
      placementGroups: true
    credentials:
      envVars:
        - HCLOUD_TOKEN
      secretRef: capi-cluster-credentials
  controlPlane:
    # numero dispari per il quorum di etcd
    replicas: 3
    type: cx33
  workers:
    platform:
      replicas: 2
      type: cpx31
  bootstrap:
    - cilium
    - ccm: {networking: {enabled: true}}

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 del workload cluster viene scritto in .kubeconfig/capi-cluster.yaml nel progetto, con il nome di metadata.name. Quello del management cluster è .kubeconfig/mgmt.example.com.yaml, con il nome di managementCluster.domain. Il tuo ~/.kube/config non viene toccato.

Provisioning

lo provision

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.

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

Le risorse CAPI vivono sul cluster di management, i tuoi nodi sul cluster di workload. Nessuno dei due è il tuo contesto kubectl predefinito, quindi indica ogni kubeconfig in modo esplicito:

# Stato del cluster CAPI — sul management cluster
kubectl --kubeconfig=.kubeconfig/mgmt.example.com.yaml get clusters -A

# Nodi del workload cluster
kubectl --kubeconfig=.kubeconfig/capi-cluster.yaml 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
Complessità	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 più semplice

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-09-05