Primo cluster

Una guida dettagliata al file di configurazione cluster.lok8s.yaml.

Prerequisiti

• CLI lok8s installata
• Un account Hetzner Cloud con un token API
• Una coppia di chiavi SSH (Ed25519 consigliata)

Riferimento completo di configurazione

# 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

Sezioni principali

spec.kubernetes

Imposta la versione di Kubernetes. Versioni supportate: da v1.33 a v1.35.

spec.hcloud

Impostazioni di Hetzner Cloud. region determina la posizione del datacenter. Il valore network.cidr definisce la rete privata per la comunicazione pod-to-pod.

spec.controlPlane

Usa replicas: 1 per i cluster di sviluppo e replicas: 3 per la produzione HA. Il campo type corrisponde ai tipi di server Hetzner.

spec.workers

Definisci uno o più pool di worker. Ogni pool specifica replicas e type. Usa dedicated per i server bare metal.

spec.bootstrap

Un elenco ordinato di addon cluster-infra (CNI, CCM, cert-manager, monitoring, …) applicati al momento del provisioning, prima che arrivi qualsiasi workload. Ogni voce viene applicata e attesa prima della successiva. I nomi semplici si risolvono negli addon del framework lok8s; le voci ./percorso puntano alle tue directory kustomize. Se omesso, il default è cilium — ogni cluster ha bisogno di una CNI. Vedi la guida agli addon di lok8s per l'elenco completo.

spec.kubehz

Integrazione facoltativa con la piattaforma kubehz, su due assi indipendenti. Disponibile oggi:hosting: self con access: registered — esegui il cluster sul tuo account e kubehz ti offre la visibilità in sola lettura dalla dashboard. hosting: hosted (kubehz gestisce il control plane) è in early access; access: managed aggiunge le funzionalità di gestione di kubehz sopra registered — politiche di self-healing, monitoraggio della capacità e gestione dello stato desiderato guidate dalla dashboard — e richiede un abbonamento Supporter o superiore. L'azione è pull-based: l'agent nel cluster recupera lo stato desiderato dalla piattaforma e lo applica con le credenziali del tuo cluster — kubehz non detiene mai accesso in ingresso. Vedi Come funziona per il modello completo e il confine di fiducia, e Registrazione per attivare la visibilità.

Esegui il provisioning del tuo cluster

lo provision

Verifica

kubectl get nodes
kubectl get pods -A

Prossimi passi

• Setup della dashboard — monitora il tuo cluster
• Registrazione — collega alla dashboard kubehz
• Guida KubeOne — configurazione avanzata di KubeOne

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-07-10