OpenClaw sur Kubernetes

Un point de depart minimal pour executer OpenClaw sur Kubernetes — pas un deploiement pret pour la production. Il couvre les ressources essentielles et est destine a etre adapte a votre environnement.

Pourquoi pas Helm ?

OpenClaw est un conteneur unique avec quelques fichiers de configuration. La personnalisation interessante est dans le contenu des agents (fichiers markdown, competences, surcharges de configuration), pas le templating d’infrastructure. Kustomize gere les overlays sans la surcharge d’un chart Helm. Si votre deploiement devient plus complexe, un chart Helm peut etre ajoute par-dessus ces manifests.

Ce dont vous avez besoin

  • Un cluster Kubernetes fonctionnel (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
  • kubectl connecte a votre cluster
  • Une cle API pour au moins un fournisseur de modeles

Demarrage rapide

# Remplacez par votre fournisseur : ANTHROPIC, GEMINI, OPENAI ou OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

Recuperez le token de passerelle et collez-le dans l’interface de controle :

kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d

Pour le debug local, ./scripts/k8s/deploy.sh --show-token affiche le token apres le deploiement.

Test local avec Kind

Si vous n’avez pas de cluster, creez-en un localement avec Kind :

./scripts/k8s/create-kind.sh           # detecte automatiquement docker ou podman
./scripts/k8s/create-kind.sh --delete  # supprimer

Puis deployez normalement avec ./scripts/k8s/deploy.sh.

Pas a pas

1) Deployer

Option A — Cle API dans l’environnement (une seule etape) :

# Remplacez par votre fournisseur : ANTHROPIC, GEMINI, OPENAI ou OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

Le script cree un Secret Kubernetes avec la cle API et un token de passerelle genere automatiquement, puis deploie. Si le Secret existe deja, il preserve le token de passerelle actuel et toutes les cles de fournisseur non modifiees.

Option B — creer le secret separement :

export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

Utilisez --show-token avec l’une ou l’autre commande si vous voulez que le token soit affiche dans stdout pour le test local.

2) Acceder a la passerelle

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

Ce qui est deploye

Namespace: openclaw (configurable via OPENCLAW_NAMESPACE)
├── Deployment/openclaw        # Pod unique, init container + passerelle
├── Service/openclaw           # ClusterIP sur le port 18789
├── PersistentVolumeClaim      # 10 Gi pour l'etat et la config de l'agent
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Token de passerelle + cles API

Personnalisation

Instructions de l’agent

Editez le AGENTS.md dans scripts/k8s/manifests/configmap.yaml et redeployez :

./scripts/k8s/deploy.sh

Configuration de la passerelle

Editez openclaw.json dans scripts/k8s/manifests/configmap.yaml. Consultez Configuration de la passerelle pour la reference complete.

Ajouter des fournisseurs

Relancez avec des cles supplementaires exportees :

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

Les cles de fournisseur existantes restent dans le Secret sauf si vous les ecrasez.

Ou patchez le Secret directement :

kubectl patch secret openclaw-secrets -n openclaw \
  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw

Namespace personnalise

OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh

Image personnalisee

Editez le champ image dans scripts/k8s/manifests/deployment.yaml :

image: ghcr.io/openclaw/openclaw:2026.3.1

Exposer au-dela du port-forward

Les manifests par defaut lient la passerelle au loopback dans le pod. Cela fonctionne avec kubectl port-forward, mais pas avec un Service Kubernetes ou un chemin Ingress qui doit atteindre l’IP du pod.

Si vous voulez exposer la passerelle via un Ingress ou un load balancer :

  • Changez la liaison de la passerelle dans scripts/k8s/manifests/configmap.yaml de loopback a une liaison non-loopback correspondant a votre modele de deploiement
  • Gardez l’authentification de la passerelle activee et utilisez un point d’entree TLS-terminated propre
  • Configurez l’interface de controle pour l’acces distant en utilisant le modele de securite web supporte (par exemple HTTPS/Tailscale Serve et origines autorisees explicites si necessaire)

Re-deployer

./scripts/k8s/deploy.sh

Cela applique tous les manifests et redemarrage le pod pour prendre en compte les changements de configuration ou de secrets.

Suppression

./scripts/k8s/deploy.sh --delete

Cela supprime le namespace et toutes les ressources qu’il contient, y compris le PVC.

Notes d’architecture

  • La passerelle ecoute sur loopback dans le pod par defaut, donc la configuration incluse est pour kubectl port-forward
  • Pas de ressources a portee cluster — tout reside dans un seul namespace
  • Securite : readOnlyRootFilesystem, drop: ALL capabilities, utilisateur non-root (UID 1000)
  • La configuration par defaut garde l’interface de controle sur le chemin d’acces local plus sur : liaison loopback plus kubectl port-forward vers http://127.0.0.1:18789
  • Si vous allez au-dela de l’acces localhost, utilisez le modele distant supporte : HTTPS/Tailscale plus la liaison de passerelle et les parametres d’origine de l’interface de controle appropries
  • Les secrets sont generes dans un repertoire temporaire et appliques directement au cluster — aucun materiel secret n’est ecrit dans le checkout du depot

Structure des fichiers

scripts/k8s/
├── deploy.sh                   # Cree le namespace + secret, deploie via kustomize
├── create-kind.sh              # Cluster Kind local (detecte automatiquement docker/podman)
└── manifests/
    ├── kustomization.yaml      # Base Kustomize
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # Spec du pod avec renforcement de la securite
    ├── pvc.yaml                # Stockage persistant 10 Gi
    └── service.yaml            # ClusterIP sur 18789
arrow_back
Précédent
VPS
Suivant
Fly
arrow_forward