Archived
beatzaplenty
ba73420350
pve-test was briefly clustered with pve1 then deliberately de-clustered so it could move to wifi-primary networking (4addr bridge mode, bonded with a wired LAN backup) - a change not achievable while clustered given corosync's latency requirements. Captures that as a reproducible script plus docs: cluster separation procedure, the wifi network design and the live-cutover pitfalls hit along the way, and node-role/history context. Also adds CLAUDE.md guardrails for pve1 (production) vs pve-test (sandbox) - this repo had none before, despite scripts here being able to make real changes to both. Separately: both nodes' mgmt firewalls were dropping ICMP by default (TCP 22/8006 only), which looked like an outage mid-troubleshooting even though SSH/web UI were fine. Added an explicit ping-allow rule to the firewall template, applied it live on both nodes, and added an audit.sh check so it stays enforced.
85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for Claude Code working in this repo. IMPORTANT: these
|
|
instructions OVERRIDE any default behavior and must be followed exactly
|
|
as written.
|
|
|
|
## Repo purpose
|
|
|
|
Base configuration/hardening toolset and planning docs for Proxmox VE
|
|
hosts (`scripts/`, `config/`, `docs/`) — see `README.md` and
|
|
`docs/00-overview.md`. Scripts in this repo are meant to be run **on**
|
|
the target Proxmox host itself (as root), not orchestrated remotely.
|
|
|
|
## Two Proxmox nodes: `pve1` (production) and `pve-test` (sandbox)
|
|
|
|
Two SSH-reachable Proxmox nodes exist on the LAN. They are **not
|
|
interchangeable** — see `docs/05-node-roles.md` for full background on
|
|
what each one is and why.
|
|
|
|
### `pve1` (production — off-limits to Claude by default)
|
|
|
|
A real, live Proxmox node hosting production VMs/containers (see
|
|
`docs/05-node-roles.md` for the current guest list) — not a sandbox, and
|
|
not Claude's to touch by default.
|
|
|
|
- **Off-limits at all times unless the operator has given explicit,
|
|
same-session instructions to act on this specific host.** That
|
|
authorization is scoped to the task it was given for — don't carry it
|
|
forward to unrelated later work in the same conversation, and never
|
|
assume it from a previous session.
|
|
- **Read-only for existing state is always fine, authorization or not.**
|
|
SSH in (or use `pvesm`, `qm list`, `pct list`, `qm config`, `pct
|
|
config`, the Proxmox API, etc.) to inspect config, storage, and any
|
|
existing VM/container freely.
|
|
- **Never** modify, stop, restart, delete, reconfigure, or create
|
|
anything on this node (`qm set`, `pct set`, `qm destroy`, `pct
|
|
destroy`, `qm stop`, `pct stop`, `qm create`, `pct create`, snapshot
|
|
operations, storage changes, running any script in this repo against
|
|
it, etc.) without that explicit go-ahead. Use `pve-test` for anything
|
|
exploratory instead.
|
|
- If a guest on `pve1` is HA-managed, be aware of the self-fence hazard
|
|
described in `docs/05-node-roles.md`'s cluster-teardown section before
|
|
doing anything that could cost the node quorum.
|
|
|
|
### `pve-test` (sandbox — Claude's default target)
|
|
|
|
A separate node set aside for testing — safe to create, interrogate, and
|
|
destroy scratch VMs/containers on without asking first.
|
|
|
|
- **Test VMs/containers are allowed, but must be torn down.** Anything
|
|
created this way must be destroyed again in the same session, before
|
|
ending the task. Use an obviously-scratch VMID/name.
|
|
- **Node-level config is still not yours to change by default.**
|
|
Creating/destroying your own scratch guests is fine; Proxmox host
|
|
config, storage pools, and networking on `pve-test` itself need the
|
|
operator's explicit go-ahead too, same as on `pve1` — the "sandbox"
|
|
status covers guest-level experimentation, not the host's own
|
|
identity. (`pve-test`'s current network config, `docs/06-pve-test-wifi-network.md`,
|
|
was applied under exactly that kind of explicit, same-session
|
|
authorization — it's not a standing invitation to keep changing it
|
|
further without asking again.)
|
|
- **Never re-cluster `pve-test` with `pve1`** without the operator
|
|
explicitly asking for it and being aware of the wifi/corosync
|
|
incompatibility in `docs/06-pve-test-wifi-network.md` — the two were
|
|
deliberately de-clustered for this reason once already.
|
|
|
|
## Safety rules
|
|
|
|
- Any script in `scripts/` that isn't `audit.sh` (read-only) makes real
|
|
changes when run for real. Don't run one against `pve1`, or against
|
|
`pve-test`'s node-level config, without the same-session go-ahead
|
|
described above. Running a script *against pve-test's own guests* — a
|
|
scratch VM/CT you created for this task — doesn't need separate
|
|
permission.
|
|
- Do not commit secrets: SSH private keys, wifi passphrases, sops/age
|
|
keys, or PVE credentials. `scripts/setup-wifi-bond-network.sh` takes
|
|
the SSID/passphrase via environment variables for exactly this reason
|
|
— never hardcode them into the script or a committed config file.
|
|
- Live changes to a node's own management network (the interface/bridge
|
|
carrying the SSH session you're using) can strand the box — see the
|
|
"what went wrong once" section in `docs/06-pve-test-wifi-network.md`
|
|
before touching `pve-test`'s networking again. Prefer applying via
|
|
`ifreload -a` over raw `ip link` surgery, and arm an auto-revert
|
|
watchdog first when acting without someone physically at the console.
|