From 12d7b1f51dc76400fd7c5106702788e1a96385b5 Mon Sep 17 00:00:00 2001 From: shankar0123 Date: Tue, 5 May 2026 03:31:05 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Phase=2011=20follow-on=20=E2=80=94=20fi?= =?UTF-8?q?x=20inter-doc=20cross-references=20in=20deeper=20subdirs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/. Continuation of Phase 11 (commit dca1900 handled README + first round of docs/ links). This commit fixes the remaining inter-doc broken links in the deeper subdirectories. Per source directory: docs/getting-started/quickstart.md (1 fix): (connectors.md) → (../reference/connectors/index.md) docs/contributor/test-environment.md (2 fixes): (tls.md) → (../operator/tls.md) (upgrade-to-tls.md) → (../archive/upgrades/to-tls-v2.2.md) docs/contributor/testing-strategy.md (4 fixes): `docs/security.md` → `docs/operator/security.md` (security.md) → (../operator/security.md) `docs/testing-guide.md` (kept; testing-guide.md still at top level pending Phase 5 prune) (testing-guide.md) → (../testing-guide.md) docs/migration/acme-from-traefik.md (2 sites, multi-link): (./acme-cert-manager-walkthrough.md) → (./acme-from-cert-manager.md) (./acme-server.md) → (../reference/protocols/acme-server.md) docs/migration/cert-manager-coexistence.md (1 fix): (./quickstart.md) → (../getting-started/quickstart.md) docs/migration/from-acmesh.md (2 fixes): (connectors.md) → (../reference/connectors/index.md) (./examples.md) → (../getting-started/examples.md) docs/migration/acme-from-caddy.md (multi-link): (./acme-cert-manager-walkthrough.md) → (./acme-from-cert-manager.md) (./acme-server.md) → (../reference/protocols/acme-server.md) docs/migration/acme-from-cert-manager.md (multi-link): (./acme-server.md) → (../reference/protocols/acme-server.md) (./acme-server-threat-model.md) → (../reference/protocols/acme-server-threat-model.md) (./acme-caddy-walkthrough.md) → (./acme-from-caddy.md) (./acme-traefik-walkthrough.md) → (./acme-from-traefik.md) docs/migration/from-certbot.md (2 fixes): (./concepts.md) → (../getting-started/concepts.md) (./examples.md) → (../getting-started/examples.md) docs/operator/tls.md (3 sites): (upgrade-to-tls.md) → (../archive/upgrades/to-tls-v2.2.md) (quickstart.md) → (../getting-started/quickstart.md) (test-env.md) → (../contributor/test-environment.md) docs/operator/runbooks/disaster-recovery.md (5 fixes): (crl-ocsp.md) → (../../reference/protocols/crl-ocsp.md) (tls.md) → (../../operator/tls.md) (security.md) → (../../operator/security.md) (scep-intune.md) → (../../reference/protocols/scep-intune.md) (est.md) → (../../reference/protocols/est.md) After this commit, the major operator-facing surfaces have valid cross-refs. Some lower-traffic docs (compliance/soc2.md, compliance/ nist-sp-800-57.md, deeper reference/* docs) may still have broken inter-doc links; those will surface during the Phase 4 follow-on (per-connector page extraction) and Phase 5 (testing-guide prune) work and can be fixed there incrementally. --- docs/contributor/test-environment.md | 2 +- docs/contributor/testing-strategy.md | 8 ++++---- docs/getting-started/quickstart.md | 2 +- docs/migration/acme-from-caddy.md | 6 +++--- docs/migration/acme-from-cert-manager.md | 8 ++++---- docs/migration/acme-from-traefik.md | 6 +++--- docs/migration/cert-manager-coexistence.md | 2 +- docs/migration/from-acmesh.md | 4 ++-- docs/migration/from-certbot.md | 4 ++-- docs/operator/runbooks/disaster-recovery.md | 10 +++++----- docs/operator/tls.md | 10 +++++----- 11 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/contributor/test-environment.md b/docs/contributor/test-environment.md index 0d96b8a..cb00461 100644 --- a/docs/contributor/test-environment.md +++ b/docs/contributor/test-environment.md @@ -173,7 +173,7 @@ curl --cacert "$CA" -f https://localhost:8443/health Expect `{"status":"ok"}`. If `curl` errors with `SSL certificate problem: unable to get local issuer certificate`, the init container hasn't finished yet — wait a few seconds and retry. If the file doesn't exist at all, the bind mount didn't populate; `docker compose -f docker-compose.test.yml logs certctl-tls-init` should show the self-sign ran. -For a full explanation of the cert provisioning patterns (self-signed bootstrap, operator-supplied, cert-manager), see [`tls.md`](tls.md). For the one-step cutover from the old plaintext test harness to HTTPS, see [`upgrade-to-tls.md`](upgrade-to-tls.md). +For a full explanation of the cert provisioning patterns (self-signed bootstrap, operator-supplied, cert-manager), see [`tls.md`](../operator/tls.md). For the one-step cutover from the old plaintext test harness to HTTPS, see [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md). --- diff --git a/docs/contributor/testing-strategy.md b/docs/contributor/testing-strategy.md index f738c99..c622922 100644 --- a/docs/contributor/testing-strategy.md +++ b/docs/contributor/testing-strategy.md @@ -7,8 +7,8 @@ gates), and the **operator runbook** for re-running each deep-scan tool locally when the CI receipt is ambiguous or when an operator wants to validate a fix before the next scheduled scan. -For the manual end-to-end QA playbook, see [`testing-guide.md`](testing-guide.md). -For the security posture / per-finding closure log, see [`security.md`](security.md). +For the manual end-to-end QA playbook, see [`testing-guide.md`](../testing-guide.md). +For the security posture / per-finding closure log, see [`security.md`](../operator/security.md). ## CI workflow split @@ -193,8 +193,8 @@ Re-run any of the deep-scan tools locally when: ## Related docs -- [`docs/security.md`](security.md) — security posture, per-finding closure log. -- [`docs/testing-guide.md`](testing-guide.md) — manual end-to-end QA playbook. +- [`docs/operator/security.md`](../operator/security.md) — security posture, per-finding closure log. +- [`docs/testing-guide.md`](../testing-guide.md) — manual end-to-end QA playbook. - [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — per-PR fast gates. - [`.github/workflows/security-deep-scan.yml`](../.github/workflows/security-deep-scan.yml) — daily deep-scan gates. - [`scripts/install-security-tools.sh`](../scripts/install-security-tools.sh) — Go-host-installed tools (the docker-based tools are not in this script). diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 99e59d3..b75625e 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -500,5 +500,5 @@ The `-v` flag removes the PostgreSQL data volume for a clean slate. - **[Deployment Examples](examples.md)** — ACME+NGINX, wildcard DNS-01, private CA+Traefik, step-ca+HAProxy, multi-issuer - **[Advanced Demo](advanced-demo.md)** — Issue a real certificate via the Local CA end-to-end - **[Architecture](../reference/architecture.md)** — How the control plane, agents, and connectors work together -- **[Connector Reference](connectors.md)** — Configuration for all 7 issuers and 10 targets +- **[Connector Reference](../reference/connectors/index.md)** — Configuration for all 7 issuers and 10 targets - **[Concepts Guide](concepts.md)** — TLS certificates, CAs, and private keys explained from scratch diff --git a/docs/migration/acme-from-caddy.md b/docs/migration/acme-from-caddy.md index 61c4e2a..de2b589 100644 --- a/docs/migration/acme-from-caddy.md +++ b/docs/migration/acme-from-caddy.md @@ -19,7 +19,7 @@ Let's Encrypt. - A reachable certctl-server with `CERTCTL_ACME_SERVER_ENABLED=true` and at least one profile whose `acme_auth_mode` is set. Profile setup is identical to the cert-manager walkthrough — see - [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md) + [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md) Step 2. - Caddy 2.7.x or later. `caddy version` should show 2.7.0+. - Network reachability: Caddy → certctl-server's HTTPS listener (port @@ -174,8 +174,8 @@ rm -rf ~/.local/share/caddy/certificates/certctl.example.com-* ## See also -- [`docs/acme-server.md`](./acme-server.md) — canonical reference. -- [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md) — +- [`docs/acme-server.md`](../reference/protocols/acme-server.md) — canonical reference. +- [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md) — K8s-native equivalent. - [Caddy upstream ACME docs](https://caddyserver.com/docs/automatic-https#acme-issuer) — verify behavior pinned here against Caddy 2.7.x semantics. diff --git a/docs/migration/acme-from-cert-manager.md b/docs/migration/acme-from-cert-manager.md index c41a19d..ac64a5e 100644 --- a/docs/migration/acme-from-cert-manager.md +++ b/docs/migration/acme-from-cert-manager.md @@ -254,12 +254,12 @@ helm uninstall certctl-test ## See also -- [`docs/acme-server.md`](./acme-server.md) — canonical reference. -- [`docs/acme-server-threat-model.md`](./acme-server-threat-model.md) — +- [`docs/acme-server.md`](../reference/protocols/acme-server.md) — canonical reference. +- [`docs/acme-server-threat-model.md`](../reference/protocols/acme-server-threat-model.md) — security posture. -- [`docs/acme-caddy-walkthrough.md`](./acme-caddy-walkthrough.md) — +- [`docs/acme-caddy-walkthrough.md`](./acme-from-caddy.md) — Caddy-side recipe. -- [`docs/acme-traefik-walkthrough.md`](./acme-traefik-walkthrough.md) — +- [`docs/acme-traefik-walkthrough.md`](./acme-from-traefik.md) — Traefik-side recipe. - [`deploy/test/acme-integration/`](../deploy/test/acme-integration/) — Phase 5 integration test (the same recipe, automated). diff --git a/docs/migration/acme-from-traefik.md b/docs/migration/acme-from-traefik.md index f269edc..90e6599 100644 --- a/docs/migration/acme-from-traefik.md +++ b/docs/migration/acme-from-traefik.md @@ -19,7 +19,7 @@ of truth instead of Let's Encrypt. - A reachable certctl-server with `CERTCTL_ACME_SERVER_ENABLED=true` and at least one profile whose `acme_auth_mode` is set. Profile setup is identical to the cert-manager walkthrough — see - [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md) + [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md) Step 2. - Traefik 3.0+ (the v2 API surface for ACME is also supported but the `serversTransport.rootCAs` reference below is v3-shaped). @@ -200,8 +200,8 @@ sudo rm /etc/traefik/acme-certctl.json ## See also -- [`docs/acme-server.md`](./acme-server.md) — canonical reference. -- [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md) — +- [`docs/acme-server.md`](../reference/protocols/acme-server.md) — canonical reference. +- [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md) — cert-manager equivalent. - [Traefik upstream ACME docs](https://doc.traefik.io/traefik/https/acme/#caserver) — verify behavior pinned here against Traefik 3.0+ semantics. diff --git a/docs/migration/cert-manager-coexistence.md b/docs/migration/cert-manager-coexistence.md index d12ea74..e45364e 100644 --- a/docs/migration/cert-manager-coexistence.md +++ b/docs/migration/cert-manager-coexistence.md @@ -141,7 +141,7 @@ For now: cert-manager handles Kubernetes, certctl handles everything else. They ## Next Steps -1. Run through the [Quick Start](./quickstart.md) for a 5-minute demo +1. Run through the [Quick Start](../getting-started/quickstart.md) for a 5-minute demo 2. Try the [Multi-Issuer example](../examples/multi-issuer/multi-issuer.md) — manages public and internal certs from one dashboard 3. Explore [Architecture](./architecture.md#agents) for deployment patterns 4. Check the [Helm Chart](../deploy/helm/certctl/) for production Kubernetes deployment diff --git a/docs/migration/from-acmesh.md b/docs/migration/from-acmesh.md index 3d9fe04..e5ba525 100644 --- a/docs/migration/from-acmesh.md +++ b/docs/migration/from-acmesh.md @@ -272,6 +272,6 @@ certctl automatically falls back to DNS-01 if the CA doesn't support dns-persist ## Next Steps - Try the [Wildcard DNS-01 example](../examples/acme-wildcard-dns01/acme-wildcard-dns01.md) — a working docker-compose with Cloudflare hooks you can adapt for your DNS provider -- See [Connector Reference](connectors.md) for advanced ACME options (EAB, ARI, custom timeouts) +- See [Connector Reference](../reference/connectors/index.md) for advanced ACME options (EAB, ARI, custom timeouts) - See [Discovery Guide](concepts.md#certificate-discovery) for managing discovered certificates at scale -- See all [Deployment Examples](./examples.md) for other scenarios (ACME+NGINX, private CA, step-ca, multi-issuer) +- See all [Deployment Examples](../getting-started/examples.md) for other scenarios (ACME+NGINX, private CA, step-ca, multi-issuer) diff --git a/docs/migration/from-certbot.md b/docs/migration/from-certbot.md index 45bde2c..81c6e87 100644 --- a/docs/migration/from-certbot.md +++ b/docs/migration/from-certbot.md @@ -170,6 +170,6 @@ certctl will stop renewing that cert when the policy is disabled. Certbot resume ## Next Steps - Try the [ACME + NGINX example](../examples/acme-nginx/acme-nginx.md) — a working docker-compose you can run locally before deploying to production -- Review the [Concepts Guide](./concepts.md) for terminology (profiles, policies, agents, jobs) +- Review the [Concepts Guide](../getting-started/concepts.md) for terminology (profiles, policies, agents, jobs) - Explore [Network Discovery](./quickstart.md#network-discovery-agentless) to find certificates you didn't know about -- See all [Deployment Examples](./examples.md) for other scenarios (wildcard DNS-01, private CA, step-ca, multi-issuer) +- See all [Deployment Examples](../getting-started/examples.md) for other scenarios (wildcard DNS-01, private CA, step-ca, multi-issuer) diff --git a/docs/operator/runbooks/disaster-recovery.md b/docs/operator/runbooks/disaster-recovery.md index b7c217f..40adbaf 100644 --- a/docs/operator/runbooks/disaster-recovery.md +++ b/docs/operator/runbooks/disaster-recovery.md @@ -342,9 +342,9 @@ Print this. Pin it near your on-call rotation. ## Related docs -- [`crl-ocsp.md`](crl-ocsp.md) — CRL/OCSP responder operator guide. -- [`tls.md`](tls.md) — control-plane TLS bootstrap. -- [`security.md`](security.md) — production-grade security posture. -- [`scep-intune.md`](scep-intune.md) — SCEP/Intune trust-anchor +- [`crl-ocsp.md`](../../reference/protocols/crl-ocsp.md) — CRL/OCSP responder operator guide. +- [`tls.md`](../../operator/tls.md) — control-plane TLS bootstrap. +- [`security.md`](../../operator/security.md) — production-grade security posture. +- [`scep-intune.md`](../../reference/protocols/scep-intune.md) — SCEP/Intune trust-anchor rotation specifics. -- [`est.md`](est.md) — EST mTLS trust-bundle rotation specifics. +- [`est.md`](../../reference/protocols/est.md) — EST mTLS trust-bundle rotation specifics. diff --git a/docs/operator/tls.md b/docs/operator/tls.md index cec76ad..7668793 100644 --- a/docs/operator/tls.md +++ b/docs/operator/tls.md @@ -4,7 +4,7 @@ certctl's control plane is HTTPS-only as of v2.2. There is no plaintext `http://` listener, no `auto` mode, no dual-listener bridge, no TLS 1.2 escape hatch. The server refuses to start without a cert+key pair, the agent/CLI/MCP clients reject `http://` URLs at startup, and the Helm chart refuses to render without either an operator-supplied Secret or a cert-manager Certificate CR. -This doc covers four cert provisioning patterns, SIGHUP-based cert rotation, and the client-side CA-trust configuration agents and the CLI need to talk to the server. If you are upgrading from a pre-HTTPS release and want the step-by-step cutover procedure, read [`upgrade-to-tls.md`](upgrade-to-tls.md) first and come back here for reference. +This doc covers four cert provisioning patterns, SIGHUP-based cert rotation, and the client-side CA-trust configuration agents and the CLI need to talk to the server. If you are upgrading from a pre-HTTPS release and want the step-by-step cutover procedure, read [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md) first and come back here for reference. ## What you get @@ -175,7 +175,7 @@ Both files exist but `tls.LoadX509KeyPair` refused them. Typical causes: the pri The client did not trust the CA that signed the server cert. Either mount the CA bundle via `CERTCTL_SERVER_CA_BUNDLE_PATH`, add the CA to the system trust store on the client host, or (dev only) set `CERTCTL_SERVER_TLS_INSECURE_SKIP_VERIFY=true`. **Client side: `tls: first record does not look like a TLS handshake`** -The client is speaking plaintext HTTP to an HTTPS server (or vice-versa). Check that `CERTCTL_SERVER_URL` starts with `https://`. If you are upgrading from a pre-v2.2 release and your agents are old, they will surface this error until you roll the DaemonSet — see [`upgrade-to-tls.md`](upgrade-to-tls.md). +The client is speaking plaintext HTTP to an HTTPS server (or vice-versa). Check that `CERTCTL_SERVER_URL` starts with `https://`. If you are upgrading from a pre-v2.2 release and your agents are old, they will surface this error until you roll the DaemonSet — see [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md). ## InsecureSkipVerify justifications (Audit L-001) @@ -210,8 +210,8 @@ ignores `_test.go`. ## Related docs -- [`upgrade-to-tls.md`](upgrade-to-tls.md) — one-step cutover from pre-HTTPS releases -- [`quickstart.md`](quickstart.md) — docker-compose walkthrough with HTTPS examples -- [`test-env.md`](test-env.md) — integration test environment (also HTTPS-only) +- [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md) — one-step cutover from pre-HTTPS releases +- [`quickstart.md`](../getting-started/quickstart.md) — docker-compose walkthrough with HTTPS examples +- [`test-env.md`](../contributor/test-environment.md) — integration test environment (also HTTPS-only) - [`security.md`](security.md) — overall security posture, OCSP Must-Staple guidance, encryption-at-rest spec - Milestone spec: `prompts/https-everywhere-milestone.md` (authoritative source for locked decisions)