From 428e9ecb1d4ac2b84adeb590af3026b6ccc20836 Mon Sep 17 00:00:00 2001 From: reachableceo Date: Wed, 29 Jul 2026 05:28:07 -0500 Subject: [PATCH] refactor(docs): co-locate k8s/proxmox docs with their code + fix broken perf paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docs moved from docs/k8s -> k8s/docs and docs/proxmox -> proxmox/docs to sit beside their code. Updated all cross-references (docmap, STATUS, README, AGENTS, k8s README). Fixed SCRIPT_DIR path resolution in 3 perf scripts broken by the reorg (deploy-check/and-fix/finish-host pointed at root/scripts instead of perf/scripts). Registered the new top-level proxmox/ dir in all listings. ๐Ÿ’˜ Generated with Crush Assisted-by: Crush:glm-5.2 --- AGENTS.md | 7 ++++--- README.md | 5 +++-- STATUS.md | 6 +++--- docs/docmap.md | 14 +++++++------- k8s/README.md | 2 +- {docs/k8s => k8s/docs}/ARCHITECTURE.md | 0 {docs/k8s => k8s/docs}/DISTRO-DECISION.md | 0 {docs/k8s => k8s/docs}/README.md | 0 perf/deploy-and-fix.sh | 2 +- perf/deploy-check.sh | 9 +++++---- perf/finish-host.sh | 2 +- {docs/proxmox => proxmox/docs}/AUDIT-2026-07-28.md | 0 {docs/proxmox => proxmox/docs}/K8S.md | 0 {docs/proxmox => proxmox/docs}/PROJECT.md | 0 {docs/proxmox => proxmox/docs}/TODO.md | 0 15 files changed, 25 insertions(+), 22 deletions(-) rename {docs/k8s => k8s/docs}/ARCHITECTURE.md (100%) rename {docs/k8s => k8s/docs}/DISTRO-DECISION.md (100%) rename {docs/k8s => k8s/docs}/README.md (100%) rename {docs/proxmox => proxmox/docs}/AUDIT-2026-07-28.md (100%) rename {docs/proxmox => proxmox/docs}/K8S.md (100%) rename {docs/proxmox => proxmox/docs}/PROJECT.md (100%) rename {docs/proxmox => proxmox/docs}/TODO.md (100%) diff --git a/AGENTS.md b/AGENTS.md index a9cd395..b8ab23f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,13 +11,14 @@ lives in subdirectories. provisioning/ Server provisioning (SetupNewSystem.sh, security, 2FA) tests/ Test suite + VM validation harness dns-cluster-setup/ Technitium DNS cluster replication -k8s/ k3s cluster setup scripts (3-node HA over Tailscale) +k8s/ k3s cluster setup scripts (3-node HA over Tailscale) + docs/ powerman/ Cyclades PM10i PDU management via powerman console/ Serial console management (ser2net + conman) for switches perf/ Proxmox perf tuning, fleet audit, iperf +proxmox/ Proxmox fleet docs (hardware audit, capacity, k8s host planning) netinfra/ pfv-netinfra-01/02 DNS/NTP setup switches/ Switch configuration captures -docs/ All documentation (see docs/docmap.md) +docs/ Server-build docs, docmap index, and archive vendor/ Vendored KNELShellFramework ``` @@ -94,4 +95,4 @@ vendor/ Vendored KNELShellFramework Solo-founder R&D Proxmox cluster in a private residence. Shoestring budget. Production lives on a Cloudron VPS in Reston VA. See [`STATUS.md`](STATUS.md) for current state and -[`docs/proxmox/PROJECT.md`](docs/proxmox/PROJECT.md) for the fleet report. +[`proxmox/docs/PROJECT.md`](proxmox/docs/PROJECT.md) for the fleet report. diff --git a/README.md b/README.md index 5e1d1ca..cfe22eb 100644 --- a/README.md +++ b/README.md @@ -11,13 +11,14 @@ Unified infrastructure repo for the Known Element Enterprises Proxmox R&D cluste | [`provisioning/`](provisioning/) | Server provisioning (SetupNewSystem.sh, security hardening, 2FA, NTP/DNS config, SNMP, Dell OMSA) | | [`tests/`](tests/) | Test suite + VM validation harness | | [`dns-cluster-setup/`](dns-cluster-setup/) | Technitium DNS cluster replication scripts | -| [`k8s/`](k8s/) | k3s cluster setup scripts (3-node HA control plane over Tailscale) | +| [`k8s/`](k8s/) | k3s cluster setup scripts (3-node HA control plane over Tailscale) + co-located docs | | [`powerman/`](powerman/) | Cyclades PM10i PDU management via powerman on pfv-tsys1 | | [`console/`](console/) | Serial console management (ser2net + conman) for network switches on pfv-tsys4 | | [`perf/`](perf/) | Proxmox performance tuning, fleet audit, iperf, switch diagnostics | +| [`proxmox/`](proxmox/) | Proxmox fleet docs: hardware audit, capacity analysis, k8s host planning | | [`netinfra/`](netinfra/) | pfv-netinfra-01/02 DNS/NTP setup + audit scripts | | [`switches/`](switches/) | Switch configuration captures | -| [`docs/`](docs/) | All documentation ([see docmap](docs/docmap.md)) | +| [`docs/`](docs/) | Server-build docs, documentation index ([docmap](docs/docmap.md)), and archive | | [`vendor/`](vendor/) | Vendored KNELShellFramework | ## Quick Start diff --git a/STATUS.md b/STATUS.md index 5f7f4a4..434c215 100644 --- a/STATUS.md +++ b/STATUS.md @@ -45,7 +45,7 @@ infrastructure, Proxmox cluster ops, and k8s control plane. - [x] Kubeconfig saved to `~/.kube/config.pfv-k8s` (gitignored, embedded certs) - [ ] Workers (wnodes) not yet joined to this cluster - [ ] Distro decision: **k3s chosen for regular R&D cluster**. Talos docs - preserved in `docs/k8s/` for future ITAR/classified cluster. + preserved in `k8s/docs/` for future ITAR/classified cluster. ### PDU Management (powerman on pfv-tsys1 โ€” LIVE) - [x] Cyclades AlterPath PM10i (10 outlets) managed via powerman over serial @@ -90,13 +90,13 @@ infrastructure, Proxmox cluster ops, and k8s control plane. - wnode-tsys7 (701): D5 โ†’ S1 (tsys4 โ†’ tsys5) - Gives every wnode its own physical disk, balances 3/3 across servers 2. **Friday maintenance:** physical hardware + VM migrations (see - [`docs/proxmox/AUDIT-2026-07-28.md`](docs/proxmox/AUDIT-2026-07-28.md) ยง5) + [`proxmox/docs/AUDIT-2026-07-28.md`](proxmox/docs/AUDIT-2026-07-28.md) ยง5) 3. **k8s workers:** Join wnodes to the k3s cluster (after rebalancing) 4. **PDU:** Rename outlets in powerman.conf to match physical devices (Friday) 5. **k8s deferred topics:** ETL tooling, HPC scheduler, vcluster policy, solar-aware scale-out -> **See [`docs/proxmox/AUDIT-2026-07-28.md`](docs/proxmox/AUDIT-2026-07-28.md) +> **See [`proxmox/docs/AUDIT-2026-07-28.md`](proxmox/docs/AUDIT-2026-07-28.md) > for the full fresh audit with VM inventory, capacity analysis, and > Friday migration plan.** diff --git a/docs/docmap.md b/docs/docmap.md index 60609f1..e88058c 100644 --- a/docs/docmap.md +++ b/docs/docmap.md @@ -12,9 +12,9 @@ procedures for the pfv-k8s cluster (Talos + vcluster + Keycloak OIDC). | Document | Description | Last Reviewed | |----------|-------------|---------------| -| [`k8s/README.md`](k8s/README.md) | Index + TL;DR of all k8s decisions | 2026-07-28 | -| [`k8s/DISTRO-DECISION.md`](k8s/DISTRO-DECISION.md) | Talos vs k3s analysis. Recommendation: Talos, driven by ITAR/classified requirement | 2026-07-28 | -| [`k8s/ARCHITECTURE.md`](k8s/ARCHITECTURE.md) | Target architecture: control plane, network, identity, storage, tenant isolation, bootstrap, DR. Mermaid diagrams | 2026-07-28 | +| [`k8s/docs/README.md`](k8s/docs/README.md) | Index + TL;DR of all k8s decisions | 2026-07-28 | +| [`k8s/docs/DISTRO-DECISION.md`](k8s/docs/DISTRO-DECISION.md) | Talos vs k3s analysis. Decision: k3s for regular R&D cluster; Talos preserved for future ITAR/classified | 2026-07-28 | +| [`k8s/docs/ARCHITECTURE.md`](k8s/docs/ARCHITECTURE.md) | Target architecture: control plane, network, identity, storage, tenant isolation, bootstrap, DR. Mermaid diagrams | 2026-07-28 | ## Proxmox Cluster ([`proxmox/`](proxmox/)) @@ -22,10 +22,10 @@ Fleet operations, hardware, performance tuning, storage architecture. | Document | Description | Last Reviewed | |----------|-------------|---------------| -| [`proxmox/PROJECT.md`](proxmox/PROJECT.md) | Comprehensive fleet report: 7 hosts, VM inventory, storage, recommendations | 2026-07-27 | -| [`proxmox/AUDIT-2026-07-28.md`](proxmox/AUDIT-2026-07-28.md) | Fresh fleet audit with current VM placements, storage redundancy analysis, pre-k8s action items | 2026-07-28 | -| [`proxmox/TODO.md`](proxmox/TODO.md) | Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 | -| [`proxmox/K8S.md`](proxmox/K8S.md) | Kubernetes storage/host analysis (predecessor to [`k8s/`](k8s/)) | 2026-07-27 | +| [`proxmox/docs/PROJECT.md`](proxmox/docs/PROJECT.md) | Comprehensive fleet report: 7 hosts, VM inventory, storage, recommendations | 2026-07-27 | +| [`proxmox/docs/AUDIT-2026-07-28.md`](proxmox/docs/AUDIT-2026-07-28.md) | Fresh fleet audit with current VM placements, storage redundancy analysis, pre-k8s action items | 2026-07-28 | +| [`proxmox/docs/TODO.md`](proxmox/docs/TODO.md) | Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 | +| [`proxmox/docs/K8S.md`](proxmox/docs/K8S.md) | Kubernetes storage/host analysis (predecessor to [`k8s/`](k8s/)) | 2026-07-27 | ## Server Build ([`server-build/`](server-build/)) diff --git a/k8s/README.md b/k8s/README.md index 96b55e9..dc092f5 100644 --- a/k8s/README.md +++ b/k8s/README.md @@ -42,7 +42,7 @@ kubectl get nodes ## Design Decisions - **k3s (not Talos):** This is a regular R&D cluster, not ITAR/classified. - Talos architecture is documented in [`docs/k8s/`](../docs/k8s/) for when + Talos architecture is documented in [`docs/`](docs/) for when that requirement comes online. k3s on stock Debian is simpler to operate. - **Tailscale-only transport:** `--node-ip`, `--advertise-address`, and `--tls-san` are all set to Tailscale IPs. No LAN IP appears in any node diff --git a/docs/k8s/ARCHITECTURE.md b/k8s/docs/ARCHITECTURE.md similarity index 100% rename from docs/k8s/ARCHITECTURE.md rename to k8s/docs/ARCHITECTURE.md diff --git a/docs/k8s/DISTRO-DECISION.md b/k8s/docs/DISTRO-DECISION.md similarity index 100% rename from docs/k8s/DISTRO-DECISION.md rename to k8s/docs/DISTRO-DECISION.md diff --git a/docs/k8s/README.md b/k8s/docs/README.md similarity index 100% rename from docs/k8s/README.md rename to k8s/docs/README.md diff --git a/perf/deploy-and-fix.sh b/perf/deploy-and-fix.sh index 11bcd03..087fab0 100755 --- a/perf/deploy-and-fix.sh +++ b/perf/deploy-and-fix.sh @@ -3,7 +3,7 @@ set -uo pipefail HOST="$1" SSH_OPTS=(-o BatchMode=yes -o ConnectTimeout=8 -o ServerAliveInterval=10 -o StrictHostKeyChecking=accept-new) -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scripts" echo "=== Uploading fix script to $HOST ===" scp "${SSH_OPTS[@]}" "$SCRIPT_DIR/fix-bond-nfs.sh" "root@$HOST:/root/fix-bond-nfs.sh" >/dev/null 2>&1 diff --git a/perf/deploy-check.sh b/perf/deploy-check.sh index 6d82096..b214dea 100755 --- a/perf/deploy-check.sh +++ b/perf/deploy-check.sh @@ -18,9 +18,10 @@ ############################################################################### set -uo pipefail -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -CHECK_SH="$SCRIPT_DIR/scripts/check.sh" -LOG_DIR="$SCRIPT_DIR/returned-logs" +SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT_DIR="$(cd "$SELF_DIR/.." && pwd)" +CHECK_SH="$SELF_DIR/scripts/check.sh" +LOG_DIR="$ROOT_DIR/returned-logs" mkdir -p "$LOG_DIR" # ONLY the hosts the user told us are alive. @@ -43,7 +44,7 @@ fi # Sanity-check shellcheck clean before shipping (best-effort, non-blocking) if command -v docker >/dev/null 2>&1; then log "pre-flight: shellcheck on check.sh" - if ! docker run --rm -v "$SCRIPT_DIR:/mnt" -w /mnt \ + if ! docker run --rm -v "$SELF_DIR:/mnt" -w /mnt \ koalaman/shellcheck:stable --severity=style --format=gcc scripts/check.sh \ >"$LOG_DIR/_shellcheck.preflight.txt" 2>&1; then log "WARNING: shellcheck reported issues โ€” see _shellcheck.preflight.txt" diff --git a/perf/finish-host.sh b/perf/finish-host.sh index 9577c1a..584d5e7 100755 --- a/perf/finish-host.sh +++ b/perf/finish-host.sh @@ -22,7 +22,7 @@ if [ -z "$HOST" ]; then fi SSH_OPTS=(-o BatchMode=yes -o ConnectTimeout=8 -o ServerAliveInterval=10 -o StrictHostKeyChecking=accept-new) -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scripts" echo "===================================================================" echo " finish-host.sh โ€” $HOST (mode: $MODE)" diff --git a/docs/proxmox/AUDIT-2026-07-28.md b/proxmox/docs/AUDIT-2026-07-28.md similarity index 100% rename from docs/proxmox/AUDIT-2026-07-28.md rename to proxmox/docs/AUDIT-2026-07-28.md diff --git a/docs/proxmox/K8S.md b/proxmox/docs/K8S.md similarity index 100% rename from docs/proxmox/K8S.md rename to proxmox/docs/K8S.md diff --git a/docs/proxmox/PROJECT.md b/proxmox/docs/PROJECT.md similarity index 100% rename from docs/proxmox/PROJECT.md rename to proxmox/docs/PROJECT.md diff --git a/docs/proxmox/TODO.md b/proxmox/docs/TODO.md similarity index 100% rename from docs/proxmox/TODO.md rename to proxmox/docs/TODO.md