GitHub Actions

Automatisiere Cluster-Bereitstellung und Konfigurations-Sync mit GitHub Actions.

Der schnelle Weg — der wiederverwendbare Workflow

lok8s liefert einen fertigen Workflow mit, der einen eingecheckten Cluster provisioniert und, wenn der Cluster kubehz-Sichtbarkeit aktiviert (spec.kubehz.access ist registered oder managed), ihn registriert und den Claim-Fingerprint in die Job-Zusammenfassung schreibt (den Claim-Schlüssel, den lo in dein Hetzner-Projekt hochlädt; siehe Cluster beanspruchen). Er braucht genau ein 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 ist eine bewegliche Referenz

Dies ruft den wiederverwendbaren Workflow unter @main auf; er ändert sich also, wenn sich lok8s ändert. Das ist praktisch, solange lok8s jung ist, bedeutet aber, dass sich ein Lauf anders verhalten kann als der letzte, ohne dass du etwas geändert hast. Ein Commit-SHA (spinup.yml@<sha>) fixiert das getestete Verhalten und ist die sicherere Wahl für alles, was echte Infrastruktur erzeugt. Ermittle den SHA, auf den main gerade zeigt, und setze ihn in uses: ein:

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

Auf das aktuelle Release zu pinnen (@v0.2.0, August 2026) wird noch nicht empfohlen: Der Workflow hat seit diesem Tag die Provisionierung mit Claim-Schlüssel erhalten, das Release liegt also hinter dem zurück, was diese Seite beschreibt.

Die cluster.lok8s.yaml für die Domain muss unter clusters/<domain>/ im Repo eingecheckt sein. Es wird kein Plattform-Token benötigt: Der Besitz wird später interaktiv nachgewiesen, wenn du den Cluster beanspruchst.

Nimm diesen Weg, sofern du keine eigenen Schritte brauchst; die Workflows unten zeigen die vollständige manuelle Einrichtung.

Eigene Workflows schreiben

Voraussetzungen

• Ein Repository, das deine clusters/<domain>/cluster.lok8s.yaml enthält
• Konfigurierte GitHub-Repository-Secrets (unten)

Erforderliche Secrets

Füge diese in den Repository-Einstellungen unter Settings > Secrets and variables > Actions hinzu:

Secret	Beschreibung
HCLOUD_TOKEN	Hetzner-Cloud-API-Token
SSH_PRIVATE_KEY	Privater SSH-Schlüssel, der zu sshPrivateKey in deinem Provider-Deskriptor passt (Node-Zugriff)
KUBECONFIG	Base64-kodierte kubeconfig (für Sync-Workflows)

lok8s in CI installieren

lok8s wird als b-Umgebung ausgeliefert, ein Runner braucht also zuerst b und dann die gepinnte Toolchain. Committet dein Repo bereits .bin/b.yaml (der lok8s-Installer legt sie an), stellt b install allein exakt dieselbe Toolchain wieder her; die b env add-Zeile entfällt dann.

      - 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:
          # vermeidet GitHub-API-Ratelimits bei Binary-Downloads
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          b env add github.com/kernpilot/lok8s#kubeone
          b install
          echo "$PWD/.bin" >> "$GITHUB_PATH"

Provision-Workflow

Erstelle .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 }}

Die Dispatch-Eingabe wählt lo provision oder lo destroy, ein Workflow deckt also Aufbau und Abbau ab.

Sync-Workflow

Erstelle .github/workflows/sync.yml, um Konfigurationsänderungen bei einem Push anzuwenden:

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 ist idempotent: Erneutes Ausführen gleicht den Cluster an deine Spezifikation an. lo build rendert deine Services und Addons nach clusters/<domain>/artifacts.yaml, und lo deploy wendet diese Datei an. lo deploy läuft nicht, bevor lo build sie erzeugt hat.

Nächste Schritte

• Registrierung: beim kubehz-Dashboard registrieren
• KubeOne: Provisioner-Details
• CAPI: Cluster-API-Provisioner

---

Doku-Status

Aspekt	Detail
Zustand	aktiv
Zuletzt geprüft	2026-09-05