Workstation¶

Durable spec for any workstation used to work on this repo.

Site self-locate¶

Read your primary IPv4:

10.1.x.x or 192.168.1.x → home
10.2.x.x or 192.168.2.x → office
172.28.80.x → WSL2 internal (ignore)
anything else → ask

Commands:

# Linux / macOS
ip -4 addr show | grep -E 'inet ' | grep -vE '127\.0|172\.(2[8-9]|3[0-1])'
ipconfig getifaddr en0           # macOS specifically

# Windows (Git Bash)
ipconfig | grep "IPv4"

.claude/hooks/session-start.sh runs this automatically.

Site-local VIPs¶

Site	k8s API	gateway VIP	private API VIP	coredns-lan VIP	cloudflared VIP
home	`10.1.20.10:6443`	`10.1.30.10`	`10.1.30.13`	`10.1.30.11`	`10.1.30.12`
office	`10.2.20.10:6443`	`10.2.30.10`	`10.2.30.12`	`10.2.30.11`	(n/a yet)

kubectl access¶

Three supported paths:

Public API via cloudflared (recommended, works from anywhere). Server URL: https://k8s.infra.cauda.dev. OIDC auth via Authentik (planned per Phase 6; static-cert kubeconfig today).
Direct to the site-local API VIP. Only works from Mgmt/Infra/K8s VLANs. Server URL: https://10.{1,2}.20.10:6443.
SSH-jump via a Mgmt-VLAN host. Useful when debugging without rotating kubeconfigs.

VLANs are fully open at the gateway (all subnets route freely between sites except wlan-iot / wlan-guest). If a specific workstation can't reach the cluster, investigate the LOCAL host (ARP, route, Windows firewall, Hyper-V/WSL adapter metric). Do not conclude "cluster offline" from a single failed ping.

Setup scripts¶

OS	Script
Debian / Ubuntu	`scripts/setup/linux-apt-mise.sh`
Arch / CachyOS / Manjaro	`scripts/setup/linux-arch-pacman.sh`
macOS	`scripts/setup/macos-brew.sh`
Windows 11 (native)	`scripts/setup/windows-winget.ps1`
Windows + WSL2 Ubuntu	`scripts/setup/windows-wsl2.sh`

All scripts are idempotent; re-run safely.

Shell selection¶

Match the workstation's active shell. Don't mix (no powershell -Command '…' from bash; no bash heredocs from pwsh). Bash on Windows Git-Bash, zsh on macOS, fish/bash on Linux, pwsh on Windows-native — same rule codified in CLAUDE.md.

Environment variables¶

Var	Purpose
`KUBECONFIG`	k8s API auth. Point at the repo's `kubeconfig` or a site-specific one.
`CF_API_TOKEN`	Cloudflare (terraform + manual tools).
`ARGOCD_SERVER`	argocd CLI default.
`HARBOR_URL` / pull-secret	only when touching container images through Harbor proxy.

Secrets live in the OS keychain or ~/.config/<tool>/, never in shell rc files in plaintext.

Browser bookmarks¶

All under *.cauda.dev:

ArgoCD — https://argocd.infra.cauda.dev
Grafana — https://grafana.infra.cauda.dev
Prometheus / Alertmanager — https://prometheus.infra.cauda.dev, https://alerts.infra.cauda.dev
Hubble UI — https://hubble.infra.cauda.dev (verify exposed)
Harbor — https://harbor.infra.cauda.dev
Gitea — https://git.dev.cauda.dev
Authentik — https://auth.security.cauda.dev
Proxmox home/office — https://pve01.{home,office}.infra.cauda.dev

Troubleshooting — can't reach cluster from THIS workstation¶

Confirm you're not on wlan-iot / wlan-guest (the only isolated VLANs).
arp -a | grep 10.{1,2}.30 — stale? arp -d <ip> and retry.
route print -4 (Windows) or ip route — is there a route to 10.x? If not, add one or use the cloudflared path.
Windows firewall profile — private network OK, public usually blocks outbound.
Hyper-V / WSL adapter metric — low metric can hijack traffic. Get-NetIPInterface to inspect.
Ping the cloudflared API route: curl -I https://k8s.infra.cauda.dev (should return a TLS cert).

If still stuck, ask the user. Don't invent firewall ACLs — gateways are open.