Skip to Content
AgentsKubernetes / k3s

Kubernetes / k3s (PoC)

Die Coding-Agenten lassen sich auch als Pod in k3s/Kubernetes betreiben. Dies ist ein Proof of Concept: Es zeigt den tragfähigen Weg und die Stolpersteine gegenüber dem Docker-Compose-Setup.

In Entwicklung / PoC. Einzelinstanz ohne HA, kein Ingress/TLS enthalten — bewusst minimal. Teil der Preview-Phase (1.1.0-develop.x).

Betriebsmodell

  • Genau eine Instanz. Die Runtime ist stateful (OpenClaw-State-DB im WAL-Modus, Workspaces, Auth, Worktrees) und nicht horizontal skalierbar → StatefulSet mit replicas: 1.
  • Node-lokales Storage (ReadWriteOnce). SQLite-WAL kann auf NFS/Netz-Storage korrumpieren. Unter k3s passt der Default-Provisioner local-path.
  • Agenten-Registrierung beim Start, nicht im Image — siehe unten.

Der entscheidende Unterschied zu Docker

Die Agenten werden im Image (Dockerfile.agents) zur Build-Zeit in ~/.openclaw registriert. Zur Laufzeit gilt jedoch:

  • Docker: Ein frisches Named Volume wird beim ersten Mount aus dem Image geseedet — die Registrierung überlebt.
  • Kubernetes: Ein leeres PVC wird nicht geseedet. Es überdeckt ~/.openclaw vollständig → die eingebackene Registrierung ist weg, im Pod existierte nur Agent main.

Deshalb registriert ein initContainer die Agenten beim Start erneut, gegen das PVC-gemountete ~/.openclaw. install.mjs ist dafür geeignet: läuft ohne laufende Gateway und ist idempotent. Erst danach startet der Gateway-Container.

Voraussetzungen

  • k3s/Kubernetes-Cluster, kubectl
  • Default-StorageClass mit ReadWriteOnce (k3s: local-path ist gesetzt)
  • Zugriff auf ghcr.io/processcube-io/agents (ggf. imagePullSecret)
  • uid/gid verifizieren: Das Manifest nimmt 1000 (node-User) an — sonst sind die PVCs nicht beschreibbar.

Installation

# 1. Namespace (optional)
kubectl create namespace processcube-agents
kubectl config set-context --current --namespace=processcube-agents
 
# 2. Secret anlegen (NICHT committen)
kubectl create secret generic openclaw-agents \
  --from-literal=gateway-token="$(openssl rand -hex 32)" \
  --from-literal=gh-token="$GH_TOKEN"   # gh-token optional
 
# 3. StatefulSet + Service
kubectl apply -k deployment/
 
# 4. Hochlaufen abwarten
kubectl rollout status statefulset/openclaw-agents
kubectl logs statefulset/openclaw-agents -c register-agents   # Registrierungs-Log

Backend-Login (interaktiv, einmalig)

Subscription-Logins (claude auth login, Codex-Device-Code) brauchen ein TTY und gibt es nicht deklarativ. Einmalig per exec nachholen — die Credentials persistieren im claude/codex-PVC und überstehen Pod-Neustarts:

kubectl exec -it statefulset/openclaw-agents -c gateway -- pc-runtime setup

Prüfen:

kubectl exec -it statefulset/openclaw-agents -c gateway -- pc-runtime doctor --smoke
kubectl exec -it statefulset/openclaw-agents -c gateway -- openclaw agents list

openclaw agents list muss jetzt code-selector, coding-agent, coding-agent-worker, coding-agent-pr-watcher zeigen — nicht nur main.

Zugriff

In-Cluster (z. B. ProcessCube®-Engine im selben Cluster):

ws://openclaw-agents.<namespace>.svc:18789

Connect-Token = gateway-token aus dem Secret. Extern: Service auf LoadBalancer umstellen oder einen Ingress davorsetzen; für die Control-UI im Browser zusätzlich die Origin freigeben und die Gateway neu starten.

Support-Agent als zweite Instanz

Der Support-Agent liegt in einem eigenen Image (Dockerfile.support) und braucht zusätzlich Gmail-Credentials, eine Engine-URL und den Wissens-Index. Als eigenes StatefulSet ableiten:

  • image: → Support-Image, initContainer-Command → install.mjs support-agent
  • Gmail-/Engine-Env aus einem Secret (vgl. docker-compose.support.yml)
  • host.docker.internal gibt es in k8s nicht → ENGINE_URL auf die Engine-Service-DNS bzw. einen externen Endpoint setzen
  • Wissens-Index: der Compose-Bind-Mount ist nicht portabel → eigenes PVC, per initContainer/Job befüllen (RW, wegen SQLite-WAL)

Grenzen dieses PoC

  • Einzelinstanz, kein HA. Ein Pod-Neustart killt laufende Worker-/Watcher-Sessions; der Recovery-Cron (alle 5 min) fängt das ab.
  • Kein Ingress/TLS enthalten — bewusst minimal.
  • uid/gid 1000 ist eine Annahme — im Cluster verifizieren.
DockerEntwickler-Skills