Quickstart

Avvia un cluster Kubernetes su Hetzner in circa 15 minuti.

Prerequisiti

• Un account Hetzner Cloud e un token API di progetto con permessi di lettura e scrittura (Hetzner Console → Security → API tokens):

  export HCLOUD_TOKEN="<il-tuo-token>"

• La CLI lok8s: un solo comando autonomo (installa la toolchain bloccata nel tuo progetto, niente tocca il tuo sistema):

  curl -fsSL https://get.lok8s.io | sh -s -- -p kubeone

  Usi già b? Questi due fanno lo stesso:

  b env add github.com/kernpilot/lok8s#kubeone
  b install

• Una coppia di chiavi SSH (Ed25519 consigliata)

• Un dominio che controlli: l’endpoint API del cluster e i nomi dei certificati derivano da lì. Lo imposti al passo 1; la configurazione di riferimento riporta example.com come segnaposto, non come valore predefinito.

1. Crea la configurazione del cluster

lo tiene una cartella per cluster, con il nome del dominio del cluster: clusters/<domain>/cluster.lok8s.yaml. Crea la cartella dentro il tuo progetto e salva lì il file:

mkdir -p clusters/example.com
# incolla il file qui sotto in clusters/example.com/cluster.lok8s.yaml
lo use example.com

lo use segna il dominio come attivo, così ogni comando successivo sa a quale cluster ti riferisci.

# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: KubeOne
metadata:
  name: my-cluster
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
    # Le macchine, nei termini di Hetzner: ogni voce `server` diventa un
    # `hcloud server create` e le sue chiavi sono flag di hcloud. Il ruolo
    # viene dall'etichetta lok8s.dev/role.
    config:
      cluster_name: my-cluster
      sshUser: root
      sshPrivateKey: ~/.ssh/id_ed25519
      sshPublicKey: ~/.ssh/id_ed25519.pub
      ssh-key:
        - name: my-cluster
          public-key-from-file: ~/.ssh/id_ed25519.pub
      network:
        - name: my-cluster
          ip-range: 10.0.0.0/16
          "#subnets":
            - network-zone: eu-central
              type: cloud
              ip-range: 10.0.0.0/24
      server:
        # 1 control plane per dev; aggiungine altri due per l'HA
        - name: cp-1
          type: cx33
          image: ubuntu-24.04
          # fsn1, nbg1 o hel1
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=my-cluster,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=my-cluster,lok8s.dev/role=worker
        - name: worker-2
          type: cpx31
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=worker

Cambia domain (e il nome della cartella) con un dominio che controlli prima del passo successivo: niente in questo file può indovinarlo per te. I tre percorsi SSH presuppongono una chiave Ed25519 con il nome predefinito (~/.ssh/id_ed25519); se la tua ha un nome diverso o si trova altrove, aggiorna anche quelli.

2. Provisioning

lo provision

Questo crea il control plane e i worker node su Hetzner Cloud. Il kubeconfig viene scritto in .kubeconfig/my-cluster.yaml nel progetto, con il nome di metadata.name. Il tuo ~/.kube/config non viene toccato.

Il provisioning richiede di norma 10–15 minuti. Hetzner fattura i server a ore (un piccolo setup di sviluppo costa circa 0,03 €/ora) e con lo destroy puoi cancellare tutto in qualsiasi momento.

3. Verifica

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

export KUBECONFIG=.kubeconfig/my-cluster.yaml
kubectl get nodes

Dovresti vedere il control plane e i worker node nello stato Ready.

4. Registrazione con kubehz (opzionale)

Solo questo passo richiede un account kubehz gratuito; i prerequisiti sopra sono tutto ciò che serve al cluster in sé.

Collega il tuo cluster alla dashboard kubehz per la visibilità della salute in sola lettura. La registrazione è solo in uscita: kubehz non ottiene mai accesso dentro il tuo cluster.

lo kubehz register

Questo annuncia il cluster con lo stato Creating. Poi rivendicalo (claim) su app.kubehz.cloud per dimostrare la proprietà e collegarlo al tuo account (register → claim → owned). Vedi Registrazione per i dettagli e cosa mostra la dashboard.

Prossimi passi

• Guida al primo cluster: riferimento dettagliato della configurazione
• Dashboard e account: esplora la dashboard, l’accesso e l’account
• Come funziona: il modello, il confine di fiducia e i tuoi dati
• Guida Self-Hosted: configurazione self-hosted avanzata
• Control plane hosted: il percorso delegato

Stato del documento

Aspetto	Dettaglio
Stato	live: corrisponde al flusso CLI rilasciato; la durata del provisioning è un limite conservativo, non ancora cronometrato su questa topologia
Ultima revisione	2026-09-05