docs: re-home ACME client walkthroughs under docs/migration/

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.
This commit is contained in:
shankar0123
2026-05-05 02:51:10 +00:00
parent b21c02a3d5
commit f157c18368
3 changed files with 23 additions and 0 deletions
@@ -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
@@ -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
@@ -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