From 2e8c5a8d227e1eb87f33d3bcbe7d89e8fa434a78 Mon Sep 17 00:00:00 2001 From: shankar0123 Date: Tue, 5 May 2026 02:51:10 +0000 Subject: [PATCH] docs: re-home ACME client walkthroughs under docs/migration/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The three ACME client walkthroughs (Caddy, cert-manager, Traefik) are conceptually "I have an existing X, here's how to point its ACME client at certctl." They belong with the migration docs, not with the acme-server protocol reference. Renames: docs/acme-caddy-walkthrough.md → docs/migration/acme-from-caddy.md docs/acme-cert-manager-walkthrough.md → docs/migration/acme-from-cert-manager.md docs/acme-traefik-walkthrough.md → docs/migration/acme-from-traefik.md Each walkthrough's lede gets a "Use this walkthrough when..." paragraph that closes the WHY-weak gap flagged in the Phase 1 audit. The new framing tells the reader when to pick this walkthrough versus the alternatives: - Caddy: "you're running Caddy 2.7+ and want it to ACME-issue from certctl instead of Let's Encrypt" - cert-manager: explicit pointer to cert-manager-coexistence.md for the keep-cert-manager-running case (vs replacement) - Traefik: "you're running Traefik 3.0+ and want certctl as your ACME source of truth" Cross-reference updates from other docs and README still pending in Phase 11. --- .../acme-from-caddy.md} | 7 +++++++ .../acme-from-cert-manager.md} | 9 +++++++++ .../acme-from-traefik.md} | 7 +++++++ 3 files changed, 23 insertions(+) rename docs/{acme-caddy-walkthrough.md => migration/acme-from-caddy.md} (93%) rename docs/{acme-cert-manager-walkthrough.md => migration/acme-from-cert-manager.md} (95%) rename docs/{acme-traefik-walkthrough.md => migration/acme-from-traefik.md} (93%) diff --git a/docs/acme-caddy-walkthrough.md b/docs/migration/acme-from-caddy.md similarity index 93% rename from docs/acme-caddy-walkthrough.md rename to docs/migration/acme-from-caddy.md index 5af0fc1..98a8b68 100644 --- a/docs/acme-caddy-walkthrough.md +++ b/docs/migration/acme-from-caddy.md @@ -1,5 +1,12 @@ # Caddy Integration Walkthrough +> **Use this walkthrough when** you're already running Caddy 2.7+ and +> want it to ACME-issue from certctl (your internal CA, your private +> PKI, or a local sub-CA chained under an enterprise root) instead of +> Let's Encrypt. The Caddyfile changes are minimal; the load-bearing +> piece is trusting certctl's bootstrap CA so Caddy's ACME client can +> talk to certctl over HTTPS. + End-to-end recipe for issuing certs from a certctl-server deployment through Caddy 2.7+. Target audience: operator running Caddy on a VM or container who wants Caddy to ACME-issue from certctl instead of diff --git a/docs/acme-cert-manager-walkthrough.md b/docs/migration/acme-from-cert-manager.md similarity index 95% rename from docs/acme-cert-manager-walkthrough.md rename to docs/migration/acme-from-cert-manager.md index d41ee0c..d9a63c1 100644 --- a/docs/acme-cert-manager-walkthrough.md +++ b/docs/migration/acme-from-cert-manager.md @@ -1,5 +1,14 @@ # cert-manager Integration Walkthrough +> **Use this walkthrough when** you're already running cert-manager +> 1.15+ in Kubernetes and want it to issue certs from certctl (your +> internal CA, your private PKI, or a local sub-CA chained under an +> enterprise root) via the standard ACME `ClusterIssuer` model. If +> you want certctl to coexist with cert-manager rather than replace +> its issuer backend, see +> [`docs/migration/cert-manager-coexistence.md`](cert-manager-coexistence.md) +> instead. + End-to-end recipe for issuing certs from a certctl-server deployment through cert-manager 1.15+. Target audience: Kubernetes operator who has never deployed certctl before and wants a working diff --git a/docs/acme-traefik-walkthrough.md b/docs/migration/acme-from-traefik.md similarity index 93% rename from docs/acme-traefik-walkthrough.md rename to docs/migration/acme-from-traefik.md index 7543f58..e703eec 100644 --- a/docs/acme-traefik-walkthrough.md +++ b/docs/migration/acme-from-traefik.md @@ -1,5 +1,12 @@ # Traefik Integration Walkthrough +> **Use this walkthrough when** you're already running Traefik 3.0+ +> (Kubernetes or VM) and want it to ACME-issue from certctl (your +> internal CA, your private PKI, or a local sub-CA chained under an +> enterprise root) instead of Let's Encrypt. The Traefik static config +> changes are minimal; the load-bearing piece is `serversTransport.rootCAs` +> so Traefik trusts certctl's bootstrap CA on every outbound ACME call. + End-to-end recipe for issuing certs from a certctl-server deployment through Traefik 3.0+. Target audience: operator running Traefik (in Kubernetes or on a VM) who wants to use certctl as their ACME source