From b21c02a3d5b73cf0f5d8c474cd21721ab17659cf Mon Sep 17 00:00:00 2001 From: shankar0123 Date: Tue, 5 May 2026 02:50:14 +0000 Subject: [PATCH] docs: archive version-specific upgrade guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit upgrade-to-tls.md and upgrade-to-v2-jwt-removal.md are version-specific runbooks for past releases. Late upgraders still need them; current operators don't. Move both to docs/archive/upgrades/ with one-line archive headers pointing readers at the current canonical docs. Renames: docs/upgrade-to-tls.md → docs/archive/upgrades/to-tls-v2.2.md docs/upgrade-to-v2-jwt-removal.md → docs/archive/upgrades/to-v2-jwt-removal.md Each gets a top-of-doc archive notice with the date and a forward pointer to the relevant steady-state doc: to-tls-v2.2.md → docs/operator/tls.md to-v2-jwt-removal.md → docs/operator/security.md The relative link inside to-v2-jwt-removal.md (was "upgrade-to-tls.md", now "to-tls-v2.2.md") updated to point at its archived sibling. Cross-reference updates from other docs and README still pending in Phase 11. --- .../upgrades/to-tls-v2.2.md} | 8 +++++++- .../upgrades/to-v2-jwt-removal.md} | 9 ++++++++- 2 files changed, 15 insertions(+), 2 deletions(-) rename docs/{upgrade-to-tls.md => archive/upgrades/to-tls-v2.2.md} (96%) rename docs/{upgrade-to-v2-jwt-removal.md => archive/upgrades/to-v2-jwt-removal.md} (94%) diff --git a/docs/upgrade-to-tls.md b/docs/archive/upgrades/to-tls-v2.2.md similarity index 96% rename from docs/upgrade-to-tls.md rename to docs/archive/upgrades/to-tls-v2.2.md index dc41e94..a1df67e 100644 --- a/docs/upgrade-to-tls.md +++ b/docs/archive/upgrades/to-tls-v2.2.md @@ -1,10 +1,16 @@ # Upgrading to HTTPS-Everywhere (v2.2) +> **Archived 2026-05-05.** This upgrade guide applies to certctl < v2.2. +> Current operators on v2.2+ already have HTTPS-only control planes and +> don't need this procedure. For the steady-state TLS reference, see +> [`docs/operator/tls.md`](../../operator/tls.md). Preserved here for +> late upgraders coming off pre-v2.2 releases. + certctl's control plane is HTTPS-only as of v2.2. There is no `http` mode, no `auto` mode, no dual-listener bind, no N-release migration window. The cutover is a single step. Out-of-date agents that still point at `http://…` fail at the TCP/TLS handshake layer on first connect after the upgrade and stay `Offline` in the dashboard until their env block is updated and the fleet is rolled. This doc walks operators through the cutover for the two shipped deployment topologies — docker-compose and Helm — and documents the failure modes and rollback posture explicitly. -For the deep-dive on cert provisioning patterns, SIGHUP cert reload, and client-side CA-trust configuration, read [`tls.md`](tls.md). This doc is the narrow "how do I upgrade" procedure. +For the deep-dive on cert provisioning patterns, SIGHUP cert reload, and client-side CA-trust configuration, read [`tls.md`](../../operator/tls.md). This doc is the narrow "how do I upgrade" procedure. ## Preconditions diff --git a/docs/upgrade-to-v2-jwt-removal.md b/docs/archive/upgrades/to-v2-jwt-removal.md similarity index 94% rename from docs/upgrade-to-v2-jwt-removal.md rename to docs/archive/upgrades/to-v2-jwt-removal.md index e5308bf..c26085c 100644 --- a/docs/upgrade-to-v2-jwt-removal.md +++ b/docs/archive/upgrades/to-v2-jwt-removal.md @@ -1,8 +1,15 @@ # Upgrading past G-1 — `CERTCTL_AUTH_TYPE=jwt` removal +> **Archived 2026-05-05.** This upgrade guide applies to operators +> upgrading past the G-1 milestone (the `CERTCTL_AUTH_TYPE=jwt` removal). +> Current operators on post-G-1 releases don't need this. For the +> steady-state security posture reference, see +> [`docs/operator/security.md`](../../operator/security.md). Preserved +> here for late upgraders. + If your certctl deployment currently sets `CERTCTL_AUTH_TYPE=jwt` (or `server.auth.type=jwt` in Helm), the next certctl upgrade will fail-fast at startup with a dedicated diagnostic. This guide explains why, what to switch to, and how to keep JWT/OIDC at your edge. -For everyone else — operators running `api-key` or `none` — this upgrade is a no-op. Skip to [`upgrade-to-tls.md`](upgrade-to-tls.md) for the v2.2 HTTPS-everywhere migration if you haven't done that one yet. +For everyone else — operators running `api-key` or `none` — this upgrade is a no-op. Skip to [`to-tls-v2.2.md`](to-tls-v2.2.md) for the v2.2 HTTPS-everywhere migration if you haven't done that one yet. ## Why we removed it