110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# OpenClaw Operations Guide (Operator-Managed)
|
|
|
|
This directory manages the deployment of the **OpenClaw** stateful AI agent on the single-node `haumdaucher` cluster.
|
|
|
|
The deployment is managed by the official **OpenClaw Operator** (`openclaw-operator`) using an `OpenClawInstance` Custom Resource, replacing the legacy 571-line manual deployment with a modern, zero-drift GitOps-friendly framework.
|
|
|
|
---
|
|
|
|
## 🏗️ Architecture Layout
|
|
|
|
* **Operator System**: Watches the `openclaw` namespace and reconciles the `OpenClawInstance` resource.
|
|
* **Deep-Merge Config**: Configured with `mergeMode: merge` to prevent configuration clobbering. Declarative settings from Git are safely merged with dynamic configurations (such as linked Telegram accounts or runtime credentials) mutated by the agent on the PVC.
|
|
* **Built-in Sidecars**:
|
|
* **Headless Chromium**: Auto-injected and wired to `http://127.0.0.1:9222` for browser automation and tools.
|
|
* **Gateway Proxy**: Handles token-based authentication and secure WebSocket forwarding natively.
|
|
* **Custom Sidecars**:
|
|
* **git-sync**: Pulls custom skills dynamically from your private repository `git.moritzgraf.de/moritz/mop-skills`.
|
|
* **skill-stabilizer**: Continuously copies checked-out skills into the flat `/home/openclaw/.openclaw/skills` workspace.
|
|
|
|
---
|
|
|
|
## 🚀 Installation & Setup
|
|
|
|
### 1. Install the Operator (One-time)
|
|
|
|
The operator is installed globally via Helm:
|
|
|
|
```bash
|
|
helm install openclaw-operator \
|
|
oci://ghcr.io/openclaw-rocks/charts/openclaw-operator \
|
|
--namespace openclaw-operator-system \
|
|
--create-namespace
|
|
```
|
|
|
|
### 2. Apply Custom Secrets and CRD Instance
|
|
|
|
The deployment resources are applied directly via `kubectl`:
|
|
|
|
```bash
|
|
# Apply raw secrets (git-crypt encrypted in the repository)
|
|
kubectl apply -f k8s/openclaw/openclaw.secret.yaml
|
|
|
|
# Apply the custom resource definition instance
|
|
kubectl apply -f k8s/openclaw/openclaw-instance.secret.yaml
|
|
```
|
|
|
|
---
|
|
|
|
## 🔑 Gateway Access (Token Auth)
|
|
|
|
Basic Auth (`htpasswd`) has been retired. The operator-injected gateway proxy implements token-based authentication.
|
|
|
|
To access the Control UI in your browser, append your gateway token as a URL fragment:
|
|
|
|
```
|
|
https://openclaw.haumdaucher.de/#token=<your-gateway-token>
|
|
```
|
|
|
|
> The `<your-gateway-token>` corresponds to the `gateway-token` value configured inside the `openclaw-secrets` Secret.
|
|
|
|
---
|
|
|
|
## 💾 Backup & Disaster Recovery
|
|
|
|
Because your deployment relies on `openebs-hostpath` persistent storage, **all state resides on a single physical node disk**. Local pre-migration backups should be kept in case of host or cluster recreation.
|
|
|
|
### Perform a Local Backup
|
|
Run the following script to pull your memory files, SQLite databases, paired devices, and active configs locally:
|
|
|
|
```bash
|
|
# Define target backup dir
|
|
BACKUP_DIR="k8s/openclaw/backup"
|
|
mkdir -p "$BACKUP_DIR"
|
|
|
|
# Get active pod name
|
|
POD_NAME=$(kubectl get pods -n openclaw -l app.kubernetes.io/instance=openclaw -o jsonpath='{.items[0].metadata.name}')
|
|
|
|
# Copy critical runtime files (excluding 2.9GB model files)
|
|
for item in openclaw.json workspace memory credentials identity devices telegram settings scripts tasks subagents canvas; do
|
|
kubectl cp -n openclaw -c openclaw "$POD_NAME:/home/openclaw/.openclaw/$item" "$BACKUP_DIR/$item"
|
|
done
|
|
```
|
|
|
|
### Restore from a Local Backup
|
|
If your PVC is recreated or wiped, you can push the backup files back to the new pod:
|
|
|
|
```bash
|
|
# Push directories back to the running pod
|
|
kubectl cp "$BACKUP_DIR/workspace" openclaw-0:/home/openclaw/.openclaw/workspace -n openclaw -c openclaw
|
|
# Repeat for other folders as needed
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Operational Verification Commands
|
|
|
|
```bash
|
|
# Check the controller reconciliation phase (Expected: PHASE=Running)
|
|
kubectl get openclawinstances -n openclaw
|
|
|
|
# View the status of all 6 containers inside the StatefulSet pod
|
|
kubectl get pods -n openclaw -o wide
|
|
|
|
# Review live logs of the core OpenClaw engine
|
|
kubectl logs -n openclaw openclaw-0 -c openclaw --tail=100 -f
|
|
|
|
# Review live logs of the Chromium sidecar
|
|
kubectl logs -n openclaw openclaw-0 -c chromium --tail=100 -f
|
|
```
|