tegwick
7711bf9c70
ACTIVITY-WP-0027: document durable ClusterIP host access for llm-connect; join activity_runs to ops_runs; surface Forgejo artefact links on /ops/ui automation detail and new run detail pages.
73 lines
2.6 KiB
Markdown
73 lines
2.6 KiB
Markdown
# llm-connect host access (ACTIVITY-WP-0027)
|
|
|
|
**Audience:** operators on railiance01
|
|
**Status:** decision locked 2026-08-05
|
|
|
|
## Problem
|
|
|
|
rein-aharness runs on the **host** (user systemd claim loop) and must call:
|
|
|
|
| Service | In-cluster DNS | Used for |
|
|
| ------- | -------------- | -------- |
|
|
| `llm-connect` | `llm-connect.activity-core.svc.cluster.local:8080` | FI / Binky LLM |
|
|
| `actcore-api` | `actcore-api.activity-core.svc.cluster.local:8010` | claim / complete |
|
|
| `actcore-statehub-edge-relay` | `…:8000` | progress / completion events |
|
|
|
|
Historically the claim-loop env pointed at `http://127.0.0.1:8080` and
|
|
`http://127.0.0.1:8010` via ad-hoc **`kubectl port-forward`**. That dies on
|
|
reboot or PF process exit while k3s and the claim loop keep running.
|
|
|
|
## Decision (H2 — ClusterIP via kube-proxy)
|
|
|
|
On single-node k3s (railiance01), the **host can reach Service ClusterIPs**
|
|
directly through kube-proxy. No port-forward required.
|
|
|
|
```text
|
|
rein-aharness@host
|
|
→ http://<clusterIP>:8080 llm-connect
|
|
→ http://<clusterIP>:8010 actcore-api
|
|
→ http://<clusterIP>:8000 statehub edge relay
|
|
```
|
|
|
|
**Not chosen**
|
|
|
|
| Option | Why not |
|
|
| ------ | ------- |
|
|
| Long-lived kubectl port-forward | Not production; fails silently |
|
|
| Public Ingress / NodePort for llm-connect | Exposes LLM proxy surface |
|
|
| Move claim loop fully in-cluster | Domain checkouts live on host disk today (repos under `$HOME`) |
|
|
|
|
## How URLs are set
|
|
|
|
1. **Preferred:** claim-loop env uses `k8s://activity-core/<svc>:<port>` pseudo-URLs.
|
|
The `rein-aharness-claim` wrapper resolves them at process start via
|
|
`kubectl get svc` (requires `KUBECONFIG` readable by the user).
|
|
2. **Fallback:** concrete `http://10.43.x.x:port` ClusterIPs (stable until the
|
|
Service object is recreated).
|
|
3. **Refresh:** `deploy/scripts/refresh-claim-loop-k8s-urls.sh` on rein-aharness
|
|
rewrites concrete IPs from live Services.
|
|
|
|
## Health checks (host)
|
|
|
|
```bash
|
|
# After claim wrapper resolves k8s:// URLs into the process env:
|
|
curl -sS "$LLM_CONNECT_URL/health"
|
|
curl -sS "$ACTIVITY_CORE_URL/health"
|
|
curl -sS "${STATE_HUB_URL%/}/edge/health" # if using edge relay
|
|
```
|
|
|
|
## Security
|
|
|
|
- ClusterIP ranges are not published on the Internet; they are cluster-local.
|
|
- Do not change `llm-connect` Service type to `LoadBalancer` / public NodePort
|
|
without a separate security review.
|
|
- Worker token for actcore-api stays in `~/.config/rein-aharness/claim-loop.env`
|
|
(mode 600), never git.
|
|
|
|
## Ownership
|
|
|
|
| Piece | Owner |
|
|
| ----- | ----- |
|
|
| In-cluster llm-connect Deployment | activity-core / railiance k8s |
|
|
| Host claim loop + URL resolution | rein-aharness |
|
|
| This decision doc | activity-core (ACTIVITY-WP-0027-T01) |
|