Kubernetes

Un punto di partenza minimale per eseguire OpenClaw su Kubernetes, non una distribuzione pronta per la produzione. Include le risorse principali ed è pensato per essere adattato al proprio ambiente.

Perché non Helm

OpenClaw è un singolo container con alcuni file di configurazione. La personalizzazione più rilevante riguarda i contenuti dell’agente (file Markdown, Skills, sostituzioni della configurazione), non i modelli dell’infrastruttura. Kustomize gestisce le sovrapposizioni senza il sovraccarico di un chart Helm. Se la distribuzione diventa più complessa, è possibile aggiungere un chart Helm sopra questi manifest.

Requisiti

Un cluster Kubernetes in esecuzione (AKS, EKS, GKE, k3s, kind, OpenShift, ecc.)
kubectl connesso al cluster
Una chiave API per almeno un fornitore di modelli

Avvio rapido

# Sostituire con il proprio fornitore: ANTHROPIC, GEMINI, OPENAI o OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

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

Per impostazione predefinita, deploy.sh crea l’autenticazione tramite token. Recuperare il token del Gateway generato per l’interfaccia di controllo:

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

Per il debug locale, ./scripts/k8s/deploy.sh --show-token stampa il token dopo la distribuzione.

Test locale con Kind

Se non si dispone di un cluster, crearne uno localmente con Kind:

./scripts/k8s/create-kind.sh           # rileva automaticamente docker o podman
./scripts/k8s/create-kind.sh --delete  # elimina il cluster

Quindi eseguire normalmente la distribuzione con ./scripts/k8s/deploy.sh.

Procedura dettagliata

1) Distribuzione

Opzione A: chiave API nell’ambiente (un solo passaggio)

# Sostituire con il proprio fornitore: ANTHROPIC, GEMINI, OPENAI o OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

Lo script crea un Secret Kubernetes con la chiave API e un token del Gateway generato automaticamente, quindi esegue la distribuzione. Se il Secret esiste già, mantiene il token del Gateway corrente e tutte le chiavi dei fornitori che non vengono modificate. Opzione B: creare il Secret separatamente

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

Aggiungere --show-token a uno dei comandi per stampare il token su stdout durante i test locali.

2) Accesso al Gateway

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

Risorse distribuite

Spazio dei nomi: openclaw (configurabile tramite OPENCLAW_NAMESPACE)
├── Deployment/openclaw        # Singolo pod, container di inizializzazione + Gateway
├── Service/openclaw           # ClusterIP sulla porta 18789
├── PersistentVolumeClaim      # 10 GiB per stato e configurazione dell'agente
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Token del Gateway + chiavi API

Personalizzazione

Istruzioni dell’agente

Modificare AGENTS.md in scripts/k8s/manifests/configmap.yaml e ridistribuire:

./scripts/k8s/deploy.sh

Configurazione del Gateway

Modificare openclaw.json in scripts/k8s/manifests/configmap.yaml. Consultare Configurazione del Gateway per il riferimento completo.

Aggiunta di fornitori

Eseguire nuovamente i comandi dopo aver esportato le chiavi aggiuntive:

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

Le chiavi dei fornitori esistenti rimangono nel Secret, a meno che non vengano sovrascritte. In alternativa, modificare direttamente il Secret:

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

Spazio dei nomi personalizzato

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

Immagine personalizzata

Modificare il campo image in scripts/k8s/manifests/deployment.yaml:

image: ghcr.io/openclaw/openclaw:slim # principale; mirror ufficiale su Docker Hub: openclaw/openclaw

Esposizione oltre il port forwarding

I manifest predefiniti associano il Gateway al local loopback all’interno del pod. Questa configurazione funziona con kubectl port-forward, ma non con un Service Kubernetes o un percorso Ingress che debba raggiungere direttamente l’indirizzo IP del pod. Per esporre il Gateway tramite un Ingress o un bilanciatore del carico:

Modificare l’associazione del Gateway in scripts/k8s/manifests/configmap.yaml da loopback a un’associazione non loopback compatibile con il proprio modello di distribuzione.
Mantenere abilitata l’autenticazione del Gateway e utilizzare un punto di ingresso appropriato con terminazione TLS.
Configurare l’interfaccia di controllo per l’accesso remoto utilizzando il modello di sicurezza web supportato (ad esempio HTTPS/Tailscale Serve e origini consentite esplicite, quando necessarie).

Ridistribuzione

./scripts/k8s/deploy.sh

Questo comando applica tutti i manifest e riavvia il pod per caricare eventuali modifiche alla configurazione o ai Secret.

Rimozione

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

Questo comando elimina lo spazio dei nomi e tutte le risorse al suo interno, incluso il PVC.

Note sull’architettura

Per impostazione predefinita, il Gateway è associato al local loopback all’interno del pod, quindi la configurazione inclusa è destinata a kubectl port-forward.
Non vengono utilizzate risorse con ambito cluster; tutto risiede in un singolo spazio dei nomi.
Rafforzamento della sicurezza: readOnlyRootFilesystem, funzionalità drop: ALL, utente non root (UID 1000).
La configurazione predefinita mantiene l’interfaccia di controllo sul percorso di accesso locale più sicuro: associazione al loopback più kubectl port-forward verso http://127.0.0.1:18789.
Se si estende l’accesso oltre localhost, utilizzare il modello remoto supportato: HTTPS/Tailscale insieme all’associazione appropriata del Gateway e alle impostazioni delle origini dell’interfaccia di controllo.
I segreti vengono generati in una directory temporanea e applicati direttamente al cluster; nessun materiale segreto viene scritto nel checkout del repository.

Struttura dei file

scripts/k8s/
├── deploy.sh                   # Crea lo spazio dei nomi e il Secret, distribuisce tramite kustomize
├── create-kind.sh              # Cluster Kind locale (rileva automaticamente docker/podman)
└── manifests/
    ├── kustomization.yaml      # Base Kustomize
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # Specifica del pod con rafforzamento della sicurezza
    ├── pvc.yaml                # 10 GiB di spazio di archiviazione persistente
    └── service.yaml            # ClusterIP sulla porta 18789

Install overview

Maintenance

Containers

Hosting

Advanced setup

Perché non Helm

Requisiti

Avvio rapido

Test locale con Kind

Procedura dettagliata

1) Distribuzione

2) Accesso al Gateway

Risorse distribuite

Personalizzazione

Istruzioni dell’agente

Configurazione del Gateway

Aggiunta di fornitori

Spazio dei nomi personalizzato

Immagine personalizzata

Esposizione oltre il port forwarding

Ridistribuzione

Rimozione

Note sull’architettura

Struttura dei file

Contenuti correlati

​Perché non Helm

​Requisiti

​Avvio rapido

​Test locale con Kind

​Procedura dettagliata

​1) Distribuzione

​2) Accesso al Gateway

​Risorse distribuite

​Personalizzazione

​Istruzioni dell’agente

​Configurazione del Gateway

​Aggiunta di fornitori

​Spazio dei nomi personalizzato

​Immagine personalizzata

​Esposizione oltre il port forwarding

​Ridistribuzione

​Rimozione

​Note sull’architettura

​Struttura dei file

​Contenuti correlati

Perché non Helm

Requisiti

Avvio rapido

Test locale con Kind

Procedura dettagliata

1) Distribuzione

2) Accesso al Gateway

Risorse distribuite

Personalizzazione

Istruzioni dell’agente

Configurazione del Gateway

Aggiunta di fornitori

Spazio dei nomi personalizzato

Immagine personalizzata

Esposizione oltre il port forwarding

Ridistribuzione

Rimozione

Note sull’architettura

Struttura dei file

Contenuti correlati