docs: add Kubernetes install guide, setup script, and manifests (#34492)
* add docs and manifests for k8s install Signed-off-by: sallyom <somalley@redhat.com> * changelog Signed-off-by: sallyom <somalley@redhat.com> --------- Signed-off-by: sallyom <somalley@redhat.com>
This commit is contained in:
Sally O'Malley
@@ -876,6 +876,7 @@
|
||||
"group": "Hosting and deployment",
|
||||
"pages": [
|
||||
"vps",
|
||||
"install/kubernetes",
|
||||
"install/fly",
|
||||
"install/hetzner",
|
||||
"install/gcp",
|
||||
|
||||
191
docs/install/kubernetes.md
Normal file
191
docs/install/kubernetes.md
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
summary: "Deploy OpenClaw Gateway to a Kubernetes cluster with Kustomize"
|
||||
read_when:
|
||||
- You want to run OpenClaw on a Kubernetes cluster
|
||||
- You want to test OpenClaw in a Kubernetes environment
|
||||
title: "Kubernetes"
|
||||
---
|
||||
|
||||
# OpenClaw on Kubernetes
|
||||
|
||||
A minimal starting point for running OpenClaw on Kubernetes — not a production-ready deployment. It covers the core resources and is meant to be adapted to your environment.
|
||||
|
||||
## Why not Helm?
|
||||
|
||||
OpenClaw is a single container with some config files. The interesting customization is in agent content (markdown files, skills, config overrides), not infrastructure templating. Kustomize handles overlays without the overhead of a Helm chart. If your deployment grows more complex, a Helm chart can be layered on top of these manifests.
|
||||
|
||||
## What you need
|
||||
|
||||
- A running Kubernetes cluster (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
|
||||
- `kubectl` connected to your cluster
|
||||
- An API key for at least one model provider
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
|
||||
export <PROVIDER>_API_KEY="..."
|
||||
./scripts/k8s/deploy.sh
|
||||
|
||||
kubectl port-forward svc/openclaw 18789:18789 -n openclaw
|
||||
open http://localhost:18789
|
||||
```
|
||||
|
||||
Retrieve the gateway token and paste it into the Control UI:
|
||||
|
||||
```bash
|
||||
kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d
|
||||
```
|
||||
|
||||
For local debugging, `./scripts/k8s/deploy.sh --show-token` prints the token after deploy.
|
||||
|
||||
## Local testing with Kind
|
||||
|
||||
If you don't have a cluster, create one locally with [Kind](https://kind.sigs.k8s.io/):
|
||||
|
||||
```bash
|
||||
./scripts/k8s/create-kind.sh # auto-detects docker or podman
|
||||
./scripts/k8s/create-kind.sh --delete # tear down
|
||||
```
|
||||
|
||||
Then deploy as usual with `./scripts/k8s/deploy.sh`.
|
||||
|
||||
## Step by step
|
||||
|
||||
### 1) Deploy
|
||||
|
||||
**Option A** — API key in environment (one step):
|
||||
|
||||
```bash
|
||||
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
|
||||
export <PROVIDER>_API_KEY="..."
|
||||
./scripts/k8s/deploy.sh
|
||||
```
|
||||
|
||||
The script creates a Kubernetes Secret with the API key and an auto-generated gateway token, then deploys. If the Secret already exists, it preserves the current gateway token and any provider keys not being changed.
|
||||
|
||||
**Option B** — create the secret separately:
|
||||
|
||||
```bash
|
||||
export <PROVIDER>_API_KEY="..."
|
||||
./scripts/k8s/deploy.sh --create-secret
|
||||
./scripts/k8s/deploy.sh
|
||||
```
|
||||
|
||||
Use `--show-token` with either command if you want the token printed to stdout for local testing.
|
||||
|
||||
### 2) Access the gateway
|
||||
|
||||
```bash
|
||||
kubectl port-forward svc/openclaw 18789:18789 -n openclaw
|
||||
open http://localhost:18789
|
||||
```
|
||||
|
||||
## What gets deployed
|
||||
|
||||
```
|
||||
Namespace: openclaw (configurable via OPENCLAW_NAMESPACE)
|
||||
├── Deployment/openclaw # Single pod, init container + gateway
|
||||
├── Service/openclaw # ClusterIP on port 18789
|
||||
├── PersistentVolumeClaim # 10Gi for agent state and config
|
||||
├── ConfigMap/openclaw-config # openclaw.json + AGENTS.md
|
||||
└── Secret/openclaw-secrets # Gateway token + API keys
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Agent instructions
|
||||
|
||||
Edit the `AGENTS.md` in `scripts/k8s/manifests/configmap.yaml` and redeploy:
|
||||
|
||||
```bash
|
||||
./scripts/k8s/deploy.sh
|
||||
```
|
||||
|
||||
### Gateway config
|
||||
|
||||
Edit `openclaw.json` in `scripts/k8s/manifests/configmap.yaml`. See [Gateway configuration](/gateway/configuration) for the full reference.
|
||||
|
||||
### Add providers
|
||||
|
||||
Re-run with additional keys exported:
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="..."
|
||||
export OPENAI_API_KEY="..."
|
||||
./scripts/k8s/deploy.sh --create-secret
|
||||
./scripts/k8s/deploy.sh
|
||||
```
|
||||
|
||||
Existing provider keys stay in the Secret unless you overwrite them.
|
||||
|
||||
Or patch the Secret directly:
|
||||
|
||||
```bash
|
||||
kubectl patch secret openclaw-secrets -n openclaw \
|
||||
-p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
|
||||
kubectl rollout restart deployment/openclaw -n openclaw
|
||||
```
|
||||
|
||||
### Custom namespace
|
||||
|
||||
```bash
|
||||
OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh
|
||||
```
|
||||
|
||||
### Custom image
|
||||
|
||||
Edit the `image` field in `scripts/k8s/manifests/deployment.yaml`:
|
||||
|
||||
```yaml
|
||||
image: ghcr.io/openclaw/openclaw:2026.3.1
|
||||
```
|
||||
|
||||
### Expose beyond port-forward
|
||||
|
||||
The default manifests bind the gateway to loopback inside the pod. That works with `kubectl port-forward`, but it does not work with a Kubernetes `Service` or Ingress path that needs to reach the pod IP.
|
||||
|
||||
If you want to expose the gateway through an Ingress or load balancer:
|
||||
|
||||
- Change the gateway bind in `scripts/k8s/manifests/configmap.yaml` from `loopback` to a non-loopback bind that matches your deployment model
|
||||
- Keep gateway auth enabled and use a proper TLS-terminated entrypoint
|
||||
- Configure the Control UI for remote access using the supported web security model (for example HTTPS/Tailscale Serve and explicit allowed origins when needed)
|
||||
|
||||
## Re-deploy
|
||||
|
||||
```bash
|
||||
./scripts/k8s/deploy.sh
|
||||
```
|
||||
|
||||
This applies all manifests and restarts the pod to pick up any config or secret changes.
|
||||
|
||||
## Teardown
|
||||
|
||||
```bash
|
||||
./scripts/k8s/deploy.sh --delete
|
||||
```
|
||||
|
||||
This deletes the namespace and all resources in it, including the PVC.
|
||||
|
||||
## Architecture notes
|
||||
|
||||
- The gateway binds to loopback inside the pod by default, so the included setup is for `kubectl port-forward`
|
||||
- No cluster-scoped resources — everything lives in a single namespace
|
||||
- Security: `readOnlyRootFilesystem`, `drop: ALL` capabilities, non-root user (UID 1000)
|
||||
- The default config keeps the Control UI on the safer local-access path: loopback bind plus `kubectl port-forward` to `http://127.0.0.1:18789`
|
||||
- If you move beyond localhost access, use the supported remote model: HTTPS/Tailscale plus the appropriate gateway bind and Control UI origin settings
|
||||
- Secrets are generated in a temp directory and applied directly to the cluster — no secret material is written to the repo checkout
|
||||
|
||||
## File structure
|
||||
|
||||
```
|
||||
scripts/k8s/
|
||||
├── deploy.sh # Creates namespace + secret, deploys via kustomize
|
||||
├── create-kind.sh # Local Kind cluster (auto-detects docker/podman)
|
||||
└── manifests/
|
||||
├── kustomization.yaml # Kustomize base
|
||||
├── configmap.yaml # openclaw.json + AGENTS.md
|
||||
├── deployment.yaml # Pod spec with security hardening
|
||||
├── pvc.yaml # 10Gi persistent storage
|
||||
└── service.yaml # ClusterIP on 18789
|
||||
```
|
||||
Reference in New Issue
Block a user