kubehz

Italiano

English
Deutsch
Slovenščina
Nederlands

Italiano

English
Deutsch
Slovenščina
Nederlands

Appearance

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):

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

  • La CLI lok8s lo, un unico binario Go statico. Scaricalo da una release di lok8s, verificalo con checksums.txt e poi installalo. Scegli l’archivio per il tuo sistema (linux o darwin, amd64 o arm64):

    bash
    V=v0.12.0; A=lo-linux-amd64.tar.gz
curl -fsSLO "https://github.com/kernpilot/lok8s/releases/download/${V}/${A}"
curl -fsSLO "https://github.com/kernpilot/lok8s/releases/download/${V}/checksums.txt"
sha256sum --ignore-missing -c checksums.txt   # macOS: shasum -a 256 --ignore-missing -c checksums.txt
tar -xzf "${A}" lo && mkdir -p "$HOME/.local/bin" && install -m 0755 lo "$HOME/.local/bin/lo"

    Poi crea il progetto e installa la toolchain KubeOne bloccata nella sua cartella .bin/. Niente tocca il tuo sistema:

    bash
    mkdir my-project && cd my-project
lo init project
lo toolchain install --groups core,local,cloud

    Usi già b? Questi due installano lo e la stessa toolchain:

    bash
    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:

bash
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.

yaml
# 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: cpx32
          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: cpx32
          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: cpx32
          image: ubuntu-24.04
          location: fsn1
          ssh-key: [0]
          network: 0
          label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=worker

L’esempio usa cpx32 (4 vCPU, 8 GB di RAM) per ogni server. Va bene anche qualsiasi tipo con almeno le stesse vCPU e la stessa RAM che il tuo account Hetzner offre nella località.

La disponibilità varia da account ad account e cambia di ora in ora: se Hetzner rifiuta un tipo, usa un altro tipo o un’altra località (fsn1, nbg1 o hel1).

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 ​

bash
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 tre server a ore, secondo il suo listino pubblicato. 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:

bash
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é. La registrazione è aperta per i primi 25 account, poi solo su invito (vedi Dashboard e account).

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.

bash
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 ​

Stato del documento ​

AspettoDettaglio
Statolive: corrisponde al flusso CLI rilasciato; la durata del provisioning è un limite conservativo, non ancora cronometrato su questa topologia
Ultima revisione2026-09-05