coulomb/the-custodian
4
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

Orientation §1: explain and fix the workstation kube context trap.
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 3s
Details

Browse source 
Non-interactive shells skipped the .bashrc KUBECONFIG export and fell back
to ~/.kube/config (retired coulombcore tunnel :16443). ~/.kube/config now
links to config-railiance01; the old default is config-coulombcore-legacy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
codex 2026-09-22 16:19:28 +02:00
parent 66be5cb72f
commit 13f75e75d8
1 changed files with 7 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/agent-environment-orientation.md
View file

@ -1,7 +1,7 @@
# Agent environment orientation
**Audience:** every coding agent working in this estate (Claude Code, Codex, Grok, custodian workers). It is tool-neutral.
**Owner:** the-custodian. **Last verified:** 2026-09-21.
**Owner:** the-custodian. **Last verified:** 2026-09-22.
These are facts about the *environment*: where things run, how to reach them, and the traps that cost real time. Each section names its owner. When a fact changes, fix it here and in the owner's record.
@ -13,9 +13,11 @@ Read this before touching railiance01, OpenBao, ArgoCD or credentials.
- **The workstation is WSL2** (Ubuntu on Windows). It is dev-only; production runs on railiance01. There is no `xdg-open` by default: see §5.
- **railiance01** (`92.205.62.239`) is production. It is a **single-node k3s cluster**, the only control-plane node. `ssh railiance01` reaches it as user `tegwick`.
- **The workstation's kube context is NOT railiance01.** A `kubectl` run on the workstation talks to another cluster. On 2026-09-21 that sent an agent to the wrong conclusion about ArgoCD.
- To read or change railiance01, run commands on the node: `ssh railiance01 'kubectl …'`.
- Before trusting any result, confirm the node IP is `92.205.62.239` (`kubectl get nodes -o wide`).
- **Workstation `kubectl` reaches railiance01 through the `k3s-api-railiance01` tunnel (`https://127.0.0.1:16444`), but only if that kubeconfig is the one in use.**
- Until 2026-09-22 only interactive shells got it. `~/.bashrc` exports `KUBECONFIG=~/.kube/config-railiance01`, but it returns early in non-interactive shells. Agents, scripts and cron therefore fell back to `~/.kube/config`, which pointed at the retired coulombcore tunnel (`:16443`). On 2026-09-21 that sent an agent to the wrong conclusion about ArgoCD.
- Fixed 2026-09-22: `~/.kube/config` is now a symlink to `config-railiance01`. The old default is kept as `config-coulombcore-legacy`, and `config-hosteurope` is also coulombcore. Do not point a default at either of them again.
- Always confirm the node IP is `92.205.62.239` (`kubectl get nodes -o wide`) before trusting a result. A down tunnel shows as "connection refused".
- Change railiance01 by running on the node: `ssh railiance01 'kubectl …'` (see §3 for the permission rule). Workstation `kubectl` is fine for reads once the node IP checks out.
- On railiance01, `kubectl` works directly. **`helm` needs `export KUBECONFIG=/etc/rancher/k3s/k3s.yaml`**, or it tries `localhost:8080`.
- **"railiance01" in older records sometimes means coulombcore.** That usage predates the 2026-07-02 correction. coulombcore is the frozen old cluster; it still runs a stale ArgoCD.
@ -27,7 +29,7 @@ Services are private by default (railiance-master ADR-0008) and are reached thro
|---|---|---|
| State Hub API | `http://127.0.0.1:8000` (health: `/state/health`) | `state-hub-primary` |
| OpenBao | `http://127.0.0.1:18200` | `openbao-ui-railiance01` |
| k3s API | via `k3s-api-railiance01` | `k3s-api-railiance01` |
| k3s API | `https://127.0.0.1:16444` (`~/.kube/config` → `config-railiance01`) | `k3s-api-railiance01` |
**Trap:** the shell default `BAO_ADDR=https://bao.coulomb.social` is **unreachable** from the workstation. Use `BAO_ADDR=http://127.0.0.1:18200` (and `VAULT_ADDR` the same) for any `bao` command.