Skip to content

docs(self-hosting): explain verified Kubernetes upgrades and recovery - #1111

Merged
nik13 merged 3 commits into
mainfrom
docs/kubernetes-verified-upgrades
Nov 10, 2026
Merged

nik13 merged 3 commits into
mainfrom
docs/kubernetes-verified-upgrades

Conversation

@nik13

@nik13 nik13 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Update the public Helm operator guide for verified Kubernetes/Helm/GitOps upgrades. Resolve and authenticate one chart digest, deploy that same digest, distinguish Argo's external-verification boundary from Flux's native verifier, and document scoped reconciliation, existing-release ownership, failure handling and coordinated datastore recovery.

Remove the blanket patch/minor compatibility claim and the default --rollback-on-failure / --atomic upgrade recommendation. Chart/image rollback does not undo database migrations, and signature verification is not migration qualification.

Dependency and base

  • Companion implementation: feat(helm): add verified operator-controlled GitOps upgrades future-agi#3761
  • Ready for review; merge only after the companion is merged into dev and its runbook/examples links are available. Required merge order: product repair #3771 → implementation #3761 → this documentation PR. The source helper is used from a reviewed checkout, not claimed to exist in every older release package.
  • This docs repository has only main, no dev branch (checked with git ls-remote --heads origin dev main); this PR targets main. The product implementation PR targets dev.
  • No deployment, signing, merge or release action is requested by this PR.

What changed

Only src/pages/docs/self-hosting/helm.mdx:

  • Resolve exact version → immutable OCI digest → exact release-tag cosign identity before deployment.
  • Explain the optional preparation helper and its explicit non-qualification boundary.
  • Require migration/backup review and account for old pods still writing during bootstrap.
  • Pin controller sources and distinguish exact Flux OIDC trust from Argo's protected Git promotion boundary.
  • Preserve existing Flux HelmRelease/release/target/storage identities unless a separate migration plan is reviewed; do not create a second owner or uninstall by deleting the old resource.
  • Pause reconciliation in its source of truth and wait for active operations/Jobs before recovery.
  • Replace the universal restore sequence with deployment-specific, coordinated PG/CH/S3/Temporal/key recovery.
  • State the bounded same-source, synthetic-data controller acceptance scope.

Validation

GitHub CI passed on current head 789ffe75ff21adf64c921b051ced3933cac4a422: run 42589239321. All four jobs passed: Docs build/Pagefind, link audit/redirect enforcement and both Helicone offline conformance matrices. This head normally merges main 5e54cbc. The Helm page is byte-identical to previously tested 1f0b274289cf37689b8fe81b5c109999ea9554b8, and the PR diff against main remains only that page. At final check, main was one commit ahead with an unrelated RAGFlow integration page (#1024) that does not touch the Helm guide. Docs main does not require branches to be up to date; it requires one approving review. Earlier head 07efcf45 also passed all four checks in run 42564416876. The private browser/build proof below belongs to the earlier frozen source snapshot; no new private browser run on the refreshed integration head is claimed. Current-head CI verifies the merged documentation infrastructure. The PR remains ready for human review, with merge held until the implementation and its source links land in dev.

Private E2B sandbox, baseline a0f14ce1f4f0c7d8fad412824b4689c9b0a6bca7 versus final candidate source snapshot e75a6cc8b12ce551bc6abf0f827002c2a9b249cd4a7f0e85431f24f6ecbd3781. Node 20.19.5, npm 10.8.2 and repository Playwright 1.56.1; cloud-only 6 GiB V8 heap for the full docs build. No local build or test suite was run.

Both baseline and candidate:

npm run test:integrations
# tests 206
# pass 206
# fail 0
# skipped 0

npm run audit-links
Broken nav links: 0
Broken content links: 0
Orphan pages: 28 (same pre-existing warning)

npm run build
exit 0; 848 pages indexed

Real Chromium at 1440px and 390px loaded the built Helm page, checked page/runtime and same-origin resource errors, same-page anchors, required safety guidance, and the immutable-digest upgrade command without automatic rollback flags. No new browser errors, failed same-origin resources or broken anchors were observed. Screenshots were inspected.

Pre-existing limitation: mobile document width is 673px at a 390px viewport on both baseline and candidate (283px overflow). This is a no-regression result, not a claim that the existing page is fully responsive. The build's existing missing-HTML cookbook warning also remains. No site-wide layout or menu change is bundled here.

All 3,059 source file hashes were checked before and after cloud execution; local source was unchanged during the final run. The owned sandbox and template were deleted and absence was verified. Evidence retained by the author at fagi-phase3-review/docs-f80601d1.

AI use

Claude Code authored the documentation and performed source comparison, isolated build/link/unit/browser validation and screenshot inspection under the maintainer's end-to-end Phase 3 request. Human review remains required.

🤖 Generated with Claude Code

Authenticate immutable chart digests, separate Argo and Flux trust boundaries, remove blanket migration compatibility and automatic rollback advice, and document existing Flux release ownership and coordinated datastore recovery.

Co-Authored-By: Claude Code <noreply@anthropic.com>
nik13 and others added 2 commits November 8, 2026 20:55
Refresh the reviewed Helm guide against current documentation infrastructure without changing its content.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Validate the unchanged Helm guide against the current docs site and integration tests.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit 182fbc0 into main Nov 10, 2026
4 checks passed
@nik13
nik13 deleted the docs/kubernetes-verified-upgrades branch November 10, 2026 00:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant