From 13f75e75d8217e2ab1150be335fc00433a1495c4 Mon Sep 17 00:00:00 2001 From: codex Date: Tue, 22 Sep 2026 16:19:28 +0200 Subject: [PATCH] =?UTF-8?q?Orientation=20=C2=A71:=20explain=20and=20fix=20?= =?UTF-8?q?the=20workstation=20kube=20context=20trap.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/agent-environment-orientation.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/agent-environment-orientation.md b/docs/agent-environment-orientation.md index 28c907d..6a04eea 100644 --- a/docs/agent-environment-orientation.md +++ b/docs/agent-environment-orientation.md @@ -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.