KNEL/PFVCluster
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(docs): co-locate k8s/proxmox docs with their code + fix broken perf paths

Browse Source 
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
This commit is contained in:
mrcharles
2026-07-29 05:28:07 -05:00
parent b860cb116d
commit 428e9ecb1d
15 changed files with 25 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+4 -3
View File
@@ -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.
README.md
+3 -2
View File
@@ -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
STATUS.md
+3 -3
View File
@@ -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.**
docs/docmap.md
+7 -7
View File
@@ -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/))
k8s/README.md
+1 -1
View File
@@ -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
docs/k8s/ARCHITECTURE.md → k8s/docs/ARCHITECTURE.md
View File
docs/k8s/DISTRO-DECISION.md → k8s/docs/DISTRO-DECISION.md
View File
docs/k8s/README.md → k8s/docs/README.md
View File
perf/deploy-and-fix.sh
+1 -1
View File
@@ -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
perf/deploy-check.sh
+5 -4
View File
@@ -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"
perf/finish-host.sh
+1 -1
View File
@@ -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)"
docs/proxmox/AUDIT-2026-07-28.md → proxmox/docs/AUDIT-2026-07-28.md
View File
docs/proxmox/K8S.md → proxmox/docs/K8S.md
View File
docs/proxmox/PROJECT.md → proxmox/docs/PROJECT.md
View File
docs/proxmox/TODO.md → proxmox/docs/TODO.md
View File