GitHub Actions

Automatizza il provisioning dei cluster e la sincronizzazione della configurazione con GitHub Actions.

La via rapida — il workflow riutilizzabile

lok8s include un workflow già pronto che fa il provisioning di un cluster committato e, quando il cluster attiva la visibilità kubehz (spec.kubehz.access è registered o managed), lo registra e stampa il fingerprint di claim nel riepilogo del job (la chiave di rivendicazione che lo carica nel tuo progetto Hetzner; vedi Rivendicazione). Richiede esattamente un secret:

# .github/workflows/spinup.yml
name: Spin up cluster
on: workflow_dispatch

jobs:
  spinup:
    uses: kernpilot/lok8s/.github/workflows/spinup.yml@main
    with:
      domain: my-cluster.example.com
    secrets:
      HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}

@main è un riferimento mobile

Questo richiama il workflow riutilizzabile su @main, quindi cambia quando cambia lok8s. È comodo finché lok8s è giovane, ma significa che un’esecuzione può comportarsi diversamente dalla precedente senza che tu abbia modificato nulla. Indicare uno SHA di commit (spinup.yml@<sha>) fissa il comportamento che hai testato ed è la scelta più sicura per tutto ciò che crea infrastruttura reale. Ricava lo SHA a cui main punta adesso e incollalo in uses::

gh api repos/kernpilot/lok8s/commits/main --jq .sha

Fissare la release attuale (@v0.2.0, agosto 2026) non è ancora consigliato: da quel tag il workflow ha acquisito il provisioning con chiave di rivendicazione, quindi la release è indietro rispetto a quanto descrive questa pagina.

Il cluster.lok8s.yaml del dominio deve essere committato sotto clusters/<domain>/ nel tuo repo. Non serve alcun token di piattaforma: la proprietà si dimostra dopo, in modo interattivo, quando rivendichi il cluster.

Preferisci questa via a meno che tu non abbia bisogno di passi personalizzati; i workflow qui sotto mostrano la configurazione manuale completa.

Scrivere i propri workflow

Prerequisiti

• Un repository che contiene il tuo clusters/<domain>/cluster.lok8s.yaml
• I secret del repository GitHub configurati (sotto)

Secret richiesti

Aggiungili nelle impostazioni del repository in Settings > Secrets and variables > Actions:

Secret	Descrizione
HCLOUD_TOKEN	Token API di Hetzner Cloud
SSH_PRIVATE_KEY	Chiave privata SSH corrispondente a sshPrivateKey nel tuo descrittore del provider (accesso ai nodi)
KUBECONFIG	Kubeconfig codificato in Base64 (per i workflow di sincronizzazione)

Installare lok8s in CI

lok8s è distribuito come ambiente b, quindi un runner ha bisogno prima di b e poi della toolchain fissata. Se il tuo repo committa già .bin/b.yaml (lo crea l’installer di lok8s), b install da solo ripristina esattamente la stessa toolchain; salta la riga b env add.

      - name: Install b (binary manager)
        run: |
          curl -fsSL https://raw.githubusercontent.com/fentas/b/v4.18.4/install.sh \
            -o /tmp/b-install.sh
          B_INSTALL_DIR="$HOME/.local/bin" bash /tmp/b-install.sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Install the lok8s toolchain
        env:
          # evita i rate limit dell'API GitHub sui download dei binari
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          b env add github.com/kernpilot/lok8s#kubeone
          b install
          echo "$PWD/.bin" >> "$GITHUB_PATH"

Workflow di provisioning

Crea .github/workflows/provision.yml:

name: Provision Cluster
on:
  workflow_dispatch:
    inputs:
      action:
        description: 'Action to perform'
        required: true
        default: 'provision'
        type: choice
        options:
          - provision
          - destroy

jobs:
  provision:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install b (binary manager)
        run: |
          curl -fsSL https://raw.githubusercontent.com/fentas/b/v4.18.4/install.sh \
            -o /tmp/b-install.sh
          B_INSTALL_DIR="$HOME/.local/bin" bash /tmp/b-install.sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Install the lok8s toolchain
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          b env add github.com/kernpilot/lok8s#kubeone
          b install
          echo "$PWD/.bin" >> "$GITHUB_PATH"

      - name: Setup SSH key
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519

      - name: Run lo
        env:
          HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
        run: lo --domain my-cluster.example.com ${{ inputs.action }}

L’input del dispatch seleziona lo provision o lo destroy, così un solo workflow copre creazione e smantellamento.

Workflow di sincronizzazione

Crea .github/workflows/sync.yml per applicare le modifiche alla configurazione a ogni push:

name: Sync Cluster
on:
  push:
    branches: [main]
    paths:
      - 'clusters/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install b (binary manager)
        run: |
          curl -fsSL https://raw.githubusercontent.com/fentas/b/v4.18.4/install.sh \
            -o /tmp/b-install.sh
          B_INSTALL_DIR="$HOME/.local/bin" bash /tmp/b-install.sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Install the lok8s toolchain
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          b env add github.com/kernpilot/lok8s#kubeone
          b install
          echo "$PWD/.bin" >> "$GITHUB_PATH"

      - name: Setup kubeconfig
        run: |
          mkdir -p ~/.kube
          echo "${{ secrets.KUBECONFIG }}" | base64 -d > ~/.kube/config

      - name: Reconcile infrastructure
        env:
          HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
        run: lo --domain my-cluster.example.com provision

      - name: Render the manifests
        run: lo --domain my-cluster.example.com build

      - name: Deploy platform
        run: lo --domain my-cluster.example.com deploy

lo provision è idempotente: rieseguirlo riconcilia il cluster con il tuo spec. lo build renderizza i tuoi servizi e addon in clusters/<domain>/artifacts.yaml, e lo deploy applica quel file. lo deploy si rifiuta di partire prima che lo build lo abbia prodotto.

Prossimi passi

• Registrazione: registrazione con la dashboard kubehz
• KubeOne: dettagli sul provisioner
• CAPI: provisioner Cluster API

---

Stato del documento

Aspetto	Dettaglio
Stato	attivo
Ultima revisione	2026-09-05