feat(kb): SPLIT vps-control-plane -> subsystem (deprecated) + runbook
kb/subsystems/control-plane.md — status: deprecated, superseded_by: "przepisany tor redeploy, commity da151fc/79bfe8c 2026-08-03" kb/runbooks/control-plane-deploy-recovery.md — Deployment + Recovery Rozstrzygniecie 3: dokument NIE jest odswiezany, tylko oznaczony jako nieaktualny. Ostatnia zmiana tresci 2026-05-27, czyli przed przepisaniem toru redeployu. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
oskar
parent
9756338133
commit
aa1e7fce1b
60
kb/runbooks/control-plane-deploy-recovery.md
Normal file
60
kb/runbooks/control-plane-deploy-recovery.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
okf: "0.1"
|
||||
type: runbook
|
||||
visibility: private
|
||||
status: active
|
||||
updated: 2026-05-27
|
||||
links:
|
||||
- ../subsystems/control-plane.md
|
||||
---
|
||||
|
||||
# Control-plane — deployment i recovery
|
||||
|
||||
## Deployment
|
||||
|
||||
### From SATURN (primary control node)
|
||||
```bash
|
||||
# Full deploy via SSH
|
||||
./scripts/deploy/deploy-control-plane.sh --ssh
|
||||
|
||||
# Or manually:
|
||||
ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws && git pull origin master && cd services/control-plane && docker compose up -d --build --force-recreate"
|
||||
```
|
||||
|
||||
### Direct on VPS
|
||||
```bash
|
||||
cd ~/homelab-codex-ws/services/control-plane
|
||||
docker compose up -d --build --force-recreate
|
||||
```
|
||||
|
||||
`deploy-local.sh` also creates the required `/opt/homelab/` directory structure and sets ownership to UID 1000 (requires `sudo`). If directories already exist, skip to the `docker compose` step directly.
|
||||
|
||||
### Verification
|
||||
```bash
|
||||
# On VPS
|
||||
docker ps --filter "name=control-plane"
|
||||
curl -s http://localhost:18180/summary | python3 -m json.tool
|
||||
```
|
||||
|
||||
## Recovery
|
||||
|
||||
### World state is stale or corrupt
|
||||
```bash
|
||||
# On VPS — delete checkpoint to force full replay
|
||||
rm /opt/homelab/state/observer_checkpoint.json
|
||||
docker restart control-plane-observer
|
||||
```
|
||||
|
||||
### Flood of pending actions after bootstrap
|
||||
Check if node-agent is running and emitting `service_healthy` events on each node. Without `service_healthy`, the supervisor sees all services as missing and queues redeployments every cycle.
|
||||
|
||||
```bash
|
||||
# Check node-agent on each node
|
||||
ssh oskar@<node> "docker ps --filter name=node-agent && docker logs node-agent --tail 20"
|
||||
```
|
||||
|
||||
### Rebuild from scratch
|
||||
```bash
|
||||
ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws/services/control-plane && docker compose up -d --build --force-recreate"
|
||||
```
|
||||
|
||||
|
|
@ -1,3 +1,14 @@
|
|||
---
|
||||
okf: "0.1"
|
||||
type: subsystem
|
||||
visibility: private
|
||||
status: deprecated
|
||||
updated: 2026-05-27
|
||||
links:
|
||||
- ../runbooks/control-plane-deploy-recovery.md
|
||||
superseded_by: "przepisany tor redeploy, commity da151fc/79bfe8c 2026-08-03"
|
||||
---
|
||||
|
||||
# VPS Control Plane
|
||||
|
||||
The VPS Control Plane is the orchestration brain of the homelab platform. It runs on the Hetzner VPS (Tailscale IP: `100.95.58.48`) and provides observability, automated reconciliation, and a web-based operator interface.
|
||||
|
|
@ -48,32 +59,6 @@ The supervisor supports a `NODE_ALIAS_MAP` environment variable (JSON string) to
|
|||
NODE_ALIAS_MAP='{"node-2": "chelsty-infra", "node-1": "piha"}'
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### From SATURN (primary control node)
|
||||
```bash
|
||||
# Full deploy via SSH
|
||||
./scripts/deploy/deploy-control-plane.sh --ssh
|
||||
|
||||
# Or manually:
|
||||
ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws && git pull origin master && cd services/control-plane && docker compose up -d --build --force-recreate"
|
||||
```
|
||||
|
||||
### Direct on VPS
|
||||
```bash
|
||||
cd ~/homelab-codex-ws/services/control-plane
|
||||
docker compose up -d --build --force-recreate
|
||||
```
|
||||
|
||||
`deploy-local.sh` also creates the required `/opt/homelab/` directory structure and sets ownership to UID 1000 (requires `sudo`). If directories already exist, skip to the `docker compose` step directly.
|
||||
|
||||
### Verification
|
||||
```bash
|
||||
# On VPS
|
||||
docker ps --filter "name=control-plane"
|
||||
curl -s http://localhost:18180/summary | python3 -m json.tool
|
||||
```
|
||||
|
||||
## Action Approval Workflow
|
||||
|
||||
```
|
||||
|
|
@ -87,28 +72,6 @@ Supervisor writes → /opt/homelab/actions/pending/<id>.json
|
|||
Possible action states: `pending → approved → running → completed / failed / rejected`
|
||||
Auto-cancel path: `pending → cancelled/`
|
||||
|
||||
## Recovery
|
||||
|
||||
### World state is stale or corrupt
|
||||
```bash
|
||||
# On VPS — delete checkpoint to force full replay
|
||||
rm /opt/homelab/state/observer_checkpoint.json
|
||||
docker restart control-plane-observer
|
||||
```
|
||||
|
||||
### Flood of pending actions after bootstrap
|
||||
Check if node-agent is running and emitting `service_healthy` events on each node. Without `service_healthy`, the supervisor sees all services as missing and queues redeployments every cycle.
|
||||
|
||||
```bash
|
||||
# Check node-agent on each node
|
||||
ssh oskar@<node> "docker ps --filter name=node-agent && docker logs node-agent --tail 20"
|
||||
```
|
||||
|
||||
### Rebuild from scratch
|
||||
```bash
|
||||
ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws/services/control-plane && docker compose up -d --build --force-recreate"
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
### piha agent-system webui (port 18180 on piha)
|
||||
Loading…
Reference in a new issue