docs: match platform instructions to the current repository layout and install path by devantler · Pull Request #4987 · devantler-tech/platform

devantler · 2026-10-17T06:01:13Z

Why

Readers and agents copy commands, names and setup steps straight from the platform's instructions and guides. A freshness audit found more than twenty statements that no longer match the repository, including commands that would fail, unlisted deploy secrets, and storage and security descriptions of a design the platform no longer runs.

What

Corrects those statements to describe the platform as it is today: the install, publish and recovery commands, the deploy secrets, DNS, autoscaling and rebalancing, storage on the workers' own disks, the highly available secrets store and its database password rotation, signed and verified releases, local certificate trust, network settings, chaos-test examples, and several resource and file names. Documentation only; nothing that runs changes. A configuration mismatch found along the way is tracked in #4988.

🤖 Generated with Claude Code

Fixes #4986

… to the repository Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…deploy Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…pository Show the staging reference the production workload push requires, publish recovery manifests through CD, list every deploy secret by name, point the SOPS example and the new-environment steps at the real bootstrap files, pin the naming gate to the version CI runs, and describe external-dns and the autoscaler buffer as they are deployed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… autoscaler pools Longhorn keeps replicas under /var/lib/longhorn on each storage worker's root filesystem and longhorn-wffc is the default class. The autoscaler guide now shows the runner pool, capacity buffers and the two-replica descheduler. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Name the crossplane-sync-alerter CronJob and the github-config role.yaml, allow the single external-secret.yaml form for a tenant pull secret, and list all eight files the KSail pin check reads. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The deploy action signs the published artifact with cosign keyless signing and Flux verifies it against the three publishing workflows. The template guide now describes OpenBao in HA mode with integrated Raft storage. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…yed platform Local TLS comes from the cert-manager platform-ca published by trust-manager, Cilium 1.20.2 uses the en+ eth+ device set with BPF masquerading, and the chaos examples target the multi-replica homepage instead of single-replica whoami. SPIRE is not deployed, so it leaves the chaos and descheduler notes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

OpenBao runs the Database secrets engine with umami and fleetdm static roles, umami rotates weekly through its CronJob, and the fleetdm role uses a 168h period. The autoscaler guide also states the runner pool cap. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

devantler · 2026-10-17T06:23:14Z

@coderabbitai review

coderabbitai · 2026-10-17T06:23:22Z

⚠️ Action not completed

Review rate limited.

coderabbitai · 2026-10-17T06:23:29Z

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 45 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Advanced
Run ID: 6375faff-dd85-4e21-b7f9-30979640f007

📥 Commits

Reviewing files that changed from the base of the PR and between c13df1b and f89d9fe.

📒 Files selected for processing: 12

AGENTS.md
SECURITY.md
docs/TEMPLATING.md
docs/TENANTS.md
docs/architecture.md
docs/chaos-engineering.md
docs/github-management.md
docs/node-autoscaling.md
docs/oidc-kubectl.md
docs/rwx-storage.md
docs/secret-rotation.md
scripts/reconcile-talos-kernel-args/README.md

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

devantler

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 913c308550727e8d528fc102a670f61a4f922b8a

No review service could review this head when the round started. I read each one's own messages on 2026-10-17:

CodeRabbit: on this PR at 06:23:22Z it replied Review rate limited. This repository gets one included review per hour, and the next one went to platform#4971.
Codex: on platform#4971 at 06:30:06Z it replied that the account has reached its usage limits for code reviews. The message gives no reset time.
Cursor Bugbot: usage limit reached (monorepo#4272, 05:36:50Z). The message gives no reset time.

I checked every changed statement against the repository at this head. Most are right, including:

The install command matches the tap's cask, the wrapper accepts only a staging-<sha>-<run>-<attempt> reference, and cd.yaml is dispatch-only.
The deploy secrets and the DR_GH_ADMIN_TOKEN use in dr-rebuild.yaml are accurate, and the signing identity matches flux-instance.yaml and ksail.prod.yaml.
The bootstrap file layout, the capacity-buffer location and the removed Flux layer, the autoscaler pools in ksail.prod.yaml, and the descheduler settings all match.
The storage classes, the OpenBao replica counts, the Cilium settings and the kernel-argument pin files match.

Three statements the PR adds are still not true, and two need a small wording fix. Each is inline. The PR adds no secret value, credential or private address.

Verdict: 5 findings (P0: 0, P1: 3)

The manifest publication composite has two callers, deploy and disaster recovery. Workflows need the organization's GitHub App client ID and key. The fleet database role exists only once fleetdm's MySQL is reachable. HTTPRoutes are accepted by the Gateway rather than becoming Ready. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

devantler

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 2c08d4213f0b5b47fe9ec5e1054a88067d2d20b9

This is an incremental round. It covers commit 2c08d421, which answers the five findings of the round at 913c3085. The rest of the PR is unchanged since that round.

No review service can review this head now. I read each one's own messages on 2026-10-17:

CodeRabbit: this repository gets one included review per hour. On this PR at 06:23:22Z it replied Review rate limited, and the next included review was taken by platform#4971 at 07:11Z.
Codex: on platform#4971 at 06:30:06Z it replied that the account has reached its usage limits for code reviews. The message gives no reset time.
Cursor Bugbot: usage limit reached (monorepo#4272, 05:36:50Z). The message gives no reset time.

What I checked at this head:

AGENTS.md publication caller. The wrapper's only caller is now named as the publish-platform-manifests composite action, which .github/actions/deploy-prod/action.yml and .github/workflows/dr-rebuild.yaml both use. That matches both call sites.
TEMPLATING.md credentials. APP_PRIVATE_KEY (read by release.yaml, update-skills.yaml, todos.yaml and two more workflows) and APP_CLIENT_ID (read through vars. by two workflows) are now listed, with the note that they come from the organization.
secret-rotation.md fleet role. Both sentences now say the vault-config Job creates the fleetdm-mysql connection and fleet role only once fleetdm's MySQL is reachable, which is what the Job does. The umami roles are unchanged.
SECURITY.md signer and AGENTS.md DNS wording. Both now name the composite action and the Gateway's acceptance of the HTTPRoutes.
Security. Documentation only. No secret value, credential or private address is added.

All five earlier threads are resolved.

Verdict: no P0/P1 findings

devantler

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 2c08d4213f0b5b47fe9ec5e1054a88067d2d20b9

The maintainer said at 10:40Z on 2026-10-17 that the review services are quota-limited. Each one's own most recent message:

CodeRabbit: on this PR at 06:23:22Z it replied Review rate limited. It allows one included review per hour for this repository.
Codex: on platform#4971 at 06:30:06Z it replied that the account has reached its usage limits for code reviews. The message gives no reset time.
Cursor Bugbot: usage limit reached (monorepo#4272, 05:36:50Z). The message gives no reset time.

I checked each changed statement against the files at this head. These match:

Install path: the KSail cask command in the toolchain and reinstall steps.
Publishing: the staging-<sha>-<run>-<attempt> reference and the promotion to latest in publish-platform-manifests/action.yml. The signer subjects in ksail.prod.yaml's matchOIDCIdentity are ci.yaml on the merge-queue ref and cd.yaml or dr-rebuild.yaml on main.
Secrets: the names the CD, CI and DR workflows read, and the admin@prod context.
Repository layout: k8s/clusters/local/bootstrap/secret.enc.yaml, config-map.yaml, github-config/role.yaml, the crossplane-sync-alerter CronJob, deleting-policies/, limit-ranges/ and priority-classes/ under k8s/bases/bootstrap/, and the Hetzner vertical-pod-autoscalers/.
Layers: overprovisioning/ is listed in the Hetzner infrastructure kustomization. No Testkube file remains.
Naming gate pin: validate-naming@e1681322… at v7.12.0, the same pin ci.yaml uses.
DNS: external-dns uses policy: sync with the gateway-httproute source.
Autoscaling: the autoscale-arc-runners pool (CX53, 0 to 1, the label and taint) and capacityBuffers: true in ksail.prod.yaml. The descheduler runs 2 replicas with required anti-affinity and leader election.
Storage: Longhorn uses a root-filesystem bind mount in talos/workers/mount-longhorn-data.yaml, and longhorn-wffc is the default StorageClass.
OpenBao: prod sets openbao_replicas: "3". The vault-config Job sets the fleet static role's rotation period to ${fleetdm_mysql_rotation_period:=168h}, and it holds the umami, umami-blue and umami-green roles.
Chaos example: homepage's PDB selects app.kubernetes.io/instance: homepage and its ScaledObject keeps a minimum of 2 replicas. Prod sets whoami_replicas: "1".
Cilium: version 1.20.2. homogeneous-devices/ is referenced after private-nic-devices/, so en+ eth+ wins. BPF masquerade comes from ebpf-host-routing/.
KSail pins: the eight pinned files in reconcile-talos-kernel-args.

No changed line adds an internal address, an internal hostname or a secret value. The new lines name secrets and a kubeconfig context only, and the only registry they name is the public GHCR path.

Two nits are inline. Neither blocks the PR.

Verdict: no P0/P1 findings

…homepage up The platform-ca ConfigMap bundle also carries the public default CAs, so the OIDC guide now says so and points the system-trust-store step at the platform CA on its own rather than the whole bundle. A pod-kill deletes the pod directly instead of evicting it, so its PDB does not limit it. The chaos guide's homepage hypothesis now credits the second replica, and the pod-kill example no longer claims to validate the PDB. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…-4986 # Conflicts: # docs/wireguard-vpn-access.md

devantler · 2026-10-17T14:14:16Z

Merged main into this branch at f89d9fe9 to clear the conflict in docs/wireguard-vpn-access.md. main (#5002) rewrote that page as the description of the VPN bridge into the home network and removed the sections this pull request corrected: the Cilium version, devices value and live-state table no longer appear there. The resolution therefore takes main's version of that file unchanged. The other twelve files merged cleanly and keep this pull request's changes.

devantler · 2026-10-17T14:15:37Z

@coderabbitai full review

coderabbitai · 2026-10-17T14:15:46Z

⚠️ Action not completed

Review rate limited.

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 45 minutes.

devantler · 2026-10-17T14:17:59Z

CodeRabbit declined the full review at f89d9fe9 (hourly review limit for this repository). Codex and Cursor Bugbot are at their usage limits, so this head gets a local review round next.

…tions

devantler

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 16f69e2169f8b842fb89cb1e16a6787cb2a21417

CodeRabbit: rate limited at f89d9fe9 (hourly review limit for this repository, comment 6234958333; recorded as no-gate in 6234982591).
Codex: usage limit reached since 2026-10-17T09:53Z.
Cursor Bugbot: usage limit reached since 2026-10-17T09:55Z.

Scope: the whole pull request against main (12 documentation files), every added or changed factual statement checked against the files in this repository: the publish path and its signing identity, the secrets and variables named, the cd.yaml dispatch input and pins, external-dns policy, the infrastructure and bootstrap layout (overprovisioning, deleting policies, limit ranges, priority classes, VPAs), autoscaler pools and buffers against ksail.prod.yaml, the storage classes, OpenBao replicas and rotation roles, the trust-manager bundle, the chaos example and the --check-pins file count. All relative links and anchors resolve, and no old names remain in other docs.

One finding at f89d9fe9, fixed at this head: docs/TENANTS.md said every registration directory ships a ghcr-auth ExternalSecret, but only the registrations with private artifacts do (wedding-app, data-product-controller, ascoachingogvaner). The sentence is now scoped to those. Re-reviewed the one-line change at this head; nothing else changed.

Verdict: 0 findings (P0: 0, P1: 0)

devantler · 2026-10-17T16:09:40Z

Readiness at `16f69e2169f8b842fb89cb1e16a6787cb2a21417`

Tested: all required checks pass at this head (25 success, 8 skipped by path filter). Unresolved review threads: 0. No conflict with main.
Reviewed: a local review round at this head found 0 issues. All three review services were unavailable when it was posted: CodeRabbit was rate limited, and Codex and Cursor Bugbot had hit their usage limits.
Tried as a reader: this PR changes only documentation, so there is nothing to run. Instead, I checked that every repository path the changed docs now name exists at this head: ksail.prod.yaml, docs/dr/runbook.md, docs/dr/crypto-custody.md, docs/github-management.md, k8s/bases/apps/github-config/role.yaml, talos/control-planes/wireguard.yaml, talos/workers/mount-longhorn-data.yaml, and the cd.yaml, ci.yaml and dr-rebuild.yaml workflows. All 10 exist.

Promoting and queueing at this head.

devantler and others added 2 commits October 17, 2026 07:58

docs(agents): match the KSail install command and CR folder locations…

b1550c3

… to the repository Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(architecture): drop the testing component the platform does not …

19b52aa

…deploy Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-project-automation Bot added this to 🌊 Project Board Oct 17, 2026

github-project-automation Bot moved this to 🫴 Ready in 🌊 Project Board Oct 17, 2026

devantler and others added 6 commits October 17, 2026 08:09

devantler commented Oct 17, 2026

View reviewed changes

Comment thread AGENTS.md Resolved

Comment thread docs/TEMPLATING.md Resolved

Comment thread docs/secret-rotation.md Resolved

Comment thread SECURITY.md Resolved

Comment thread AGENTS.md Resolved

devantler commented Oct 17, 2026

View reviewed changes

Comment thread docs/oidc-kubectl.md Resolved

Comment thread docs/chaos-engineering.md Resolved

devantler and others added 2 commits October 17, 2026 13:10

Merge remote-tracking branch 'origin/main' into claude/docs-freshness…

f89d9fe

…-4986 # Conflicts: # docs/wireguard-vpn-access.md

docs(tenants): scope the ghcr-auth ExternalSecret to private registra…

16f69e2

…tions

devantler commented Oct 17, 2026

View reviewed changes

devantler marked this pull request as ready for review October 17, 2026 16:09

devantler added this pull request to the merge queue Oct 17, 2026

Merged via the queue into main with commit ba08530 Oct 17, 2026
33 checks passed

devantler deleted the claude/docs-freshness-4986 branch October 17, 2026 17:35

github-project-automation Bot moved this from 🫴 Ready to ✅ Done in 🌊 Project Board Oct 17, 2026

devantler mentioned this pull request Oct 17, 2026

docs(agents): place the capacity buffer inside the infrastructure layer #5022

Closed

Conversation

devantler commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

Uh oh!

devantler commented Oct 17, 2026

Uh oh!

coderabbitai Bot commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

devantler left a comment

Choose a reason for hiding this comment

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devantler left a comment

Choose a reason for hiding this comment

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Uh oh!

devantler left a comment

Choose a reason for hiding this comment

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Uh oh!

Uh oh!

Uh oh!

devantler commented Oct 17, 2026

Uh oh!

devantler commented Oct 17, 2026

Uh oh!

coderabbitai Bot commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devantler commented Oct 17, 2026

Uh oh!

devantler left a comment

Choose a reason for hiding this comment

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Uh oh!

devantler commented Oct 17, 2026

Readiness at 16f69e2169f8b842fb89cb1e16a6787cb2a21417

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

devantler commented Oct 17, 2026 •

edited

Loading

coderabbitai Bot commented Oct 17, 2026 •

edited

Loading

coderabbitai Bot commented Oct 17, 2026 •

edited

Loading

coderabbitai Bot commented Oct 17, 2026 •

edited

Loading

Readiness at `16f69e2169f8b842fb89cb1e16a6787cb2a21417`