mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-11 19:59:01 +00:00
docs: Phase 11 follow-on — fix anchor-bearing + remaining inter-doc links
Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/.
Sweeps the anchor-bearing inter-doc links that the previous Phase 11
sed pass missed (anchors after .md# weren't matched), plus a few
remaining cross-refs in docs/reference/.
Per source file:
docs/migration/acme-from-caddy.md (1 anchor link):
(./acme-server.md#certificate-readyfalse-with-rejectedidentifier)
→ (../reference/protocols/acme-server.md#certificate-readyfalse-...)
docs/migration/acme-from-cert-manager.md (3 anchor links):
Same shape; all (./acme-server.md#...) → (../reference/protocols/acme-server.md#...)
docs/reference/connectors/index.md (5 walkthrough + reference links):
(./acme-server.md) → (../protocols/acme-server.md)
(./acme-server-threat-model.md) → (../protocols/acme-server-threat-model.md)
(./acme-cert-manager-walkthrough.md) → (../../migration/acme-from-cert-manager.md)
(./acme-caddy-walkthrough.md) → (../../migration/acme-from-caddy.md)
(./acme-traefik-walkthrough.md) → (../../migration/acme-from-traefik.md)
docs/reference/protocols/acme-server.md (3 walkthrough links):
(./acme-cert-manager-walkthrough.md) → (../../migration/acme-from-cert-manager.md)
(./acme-caddy-walkthrough.md) → (../../migration/acme-from-caddy.md)
(./acme-traefik-walkthrough.md) → (../../migration/acme-from-traefik.md)
docs/reference/protocols/acme-server-threat-model.md (1 cross-dir):
(./tls.md) → (../../operator/tls.md)
After this commit, every grep for old-style `./<old-doc-name>.md` links
returns clean across docs/migration/, docs/reference/, and
docs/operator/.
This commit is contained in:
@@ -158,7 +158,7 @@ psql -c "SELECT actor, action, resource_id FROM audit_events
|
|||||||
legitimately high throughput.
|
legitimately high throughput.
|
||||||
- **Caddy logs `urn:ietf:params:acme:error:rejectedIdentifier`** →
|
- **Caddy logs `urn:ietf:params:acme:error:rejectedIdentifier`** →
|
||||||
the SAN list includes an identifier the certctl profile policy
|
the SAN list includes an identifier the certctl profile policy
|
||||||
rejects. Cross-reference [`docs/acme-server.md` § Troubleshooting](./acme-server.md#certificate-readyfalse-with-rejectedidentifier).
|
rejects. Cross-reference [`docs/acme-server.md` § Troubleshooting](../reference/protocols/acme-server.md#certificate-readyfalse-with-rejectedidentifier).
|
||||||
- **`badNonce` in Caddy logs** → clock skew or multi-replica certctl
|
- **`badNonce` in Caddy logs** → clock skew or multi-replica certctl
|
||||||
without sticky sessions; same fix as the cert-manager walkthrough.
|
without sticky sessions; same fix as the cert-manager walkthrough.
|
||||||
|
|
||||||
|
|||||||
@@ -75,7 +75,7 @@ curl -X POST https://certctl-test.default.svc.cluster.local:8443/api/profiles \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Auth-mode tradeoffs are covered in
|
Auth-mode tradeoffs are covered in
|
||||||
[`docs/acme-server.md` § Auth-mode decision tree](./acme-server.md#auth-mode-decision-tree).
|
[`docs/acme-server.md` § Auth-mode decision tree](../reference/protocols/acme-server.md#auth-mode-decision-tree).
|
||||||
For first-time deployments, `trust_authenticated` is the right default.
|
For first-time deployments, `trust_authenticated` is the right default.
|
||||||
|
|
||||||
## Step 3 — Capture the certctl bootstrap CA
|
## Step 3 — Capture the certctl bootstrap CA
|
||||||
@@ -94,7 +94,7 @@ cat deploy/test/certs/ca.crt | base64 -w0
|
|||||||
Capture the output for Step 4. This is **the** single biggest first-
|
Capture the output for Step 4. This is **the** single biggest first-
|
||||||
time-deploy footgun on the cert-manager integration path. The reference
|
time-deploy footgun on the cert-manager integration path. The reference
|
||||||
recipe lives in
|
recipe lives in
|
||||||
[`docs/acme-server.md` § TLS trust bootstrap](./acme-server.md#tls-trust-bootstrap-read-this-before-configuring-cert-manager).
|
[`docs/acme-server.md` § TLS trust bootstrap](../reference/protocols/acme-server.md#tls-trust-bootstrap-read-this-before-configuring-cert-manager).
|
||||||
|
|
||||||
## Step 4 — Apply the ClusterIssuer
|
## Step 4 — Apply the ClusterIssuer
|
||||||
|
|
||||||
@@ -229,7 +229,7 @@ psql -c "SELECT created_at, action, resource_type, resource_id
|
|||||||
## Common failure modes
|
## Common failure modes
|
||||||
|
|
||||||
These are operator-side; full troubleshooting reference is in
|
These are operator-side; full troubleshooting reference is in
|
||||||
[`docs/acme-server.md` § Troubleshooting](./acme-server.md#troubleshooting).
|
[`docs/acme-server.md` § Troubleshooting](../reference/protocols/acme-server.md#troubleshooting).
|
||||||
|
|
||||||
- `400 Bad Request: badNonce` → clock skew between certctl-server and
|
- `400 Bad Request: badNonce` → clock skew between certctl-server and
|
||||||
cert-manager, or a multi-replica certctl fleet without sticky
|
cert-manager, or a multi-replica certctl fleet without sticky
|
||||||
|
|||||||
@@ -813,16 +813,16 @@ issued, SCEP-issued certs).
|
|||||||
|
|
||||||
See:
|
See:
|
||||||
|
|
||||||
- [ACME Server Reference](./acme-server.md) — env-var reference,
|
- [ACME Server Reference](../protocols/acme-server.md) — env-var reference,
|
||||||
endpoints, auth-mode decision tree, RFC 8555 conformance statement,
|
endpoints, auth-mode decision tree, RFC 8555 conformance statement,
|
||||||
troubleshooting, FAQ.
|
troubleshooting, FAQ.
|
||||||
- [cert-manager Walkthrough](./acme-cert-manager-walkthrough.md) — kind
|
- [cert-manager Walkthrough](../../migration/acme-from-cert-manager.md) — kind
|
||||||
→ cert-manager → certctl-server → Certificate flow.
|
→ cert-manager → certctl-server → Certificate flow.
|
||||||
- [Caddy Walkthrough](./acme-caddy-walkthrough.md) — Caddyfile `acme_ca`
|
- [Caddy Walkthrough](../../migration/acme-from-caddy.md) — Caddyfile `acme_ca`
|
||||||
+ trust configuration.
|
+ trust configuration.
|
||||||
- [Traefik Walkthrough](./acme-traefik-walkthrough.md) — `certificatesResolvers`
|
- [Traefik Walkthrough](../../migration/acme-from-traefik.md) — `certificatesResolvers`
|
||||||
+ `serversTransport.rootCAs`.
|
+ `serversTransport.rootCAs`.
|
||||||
- [Threat Model](./acme-server-threat-model.md) — JWS forgery
|
- [Threat Model](../protocols/acme-server-threat-model.md) — JWS forgery
|
||||||
resistance, nonce store integrity, HTTP-01 SSRF, DNS-01 cache
|
resistance, nonce store integrity, HTTP-01 SSRF, DNS-01 cache
|
||||||
posture, TLS-ALPN-01 chain-not-validated rationale, rate-limit
|
posture, TLS-ALPN-01 chain-not-validated rationale, rate-limit
|
||||||
tuning, audit trail.
|
tuning, audit trail.
|
||||||
|
|||||||
@@ -270,7 +270,7 @@ Documented to set scope expectations for security reviewers:
|
|||||||
## See also
|
## See also
|
||||||
|
|
||||||
- [`docs/acme-server.md`](./acme-server.md) — operator-facing reference.
|
- [`docs/acme-server.md`](./acme-server.md) — operator-facing reference.
|
||||||
- [`docs/tls.md`](./tls.md) — TLS posture, including the L-001
|
- [`docs/tls.md`](../../operator/tls.md) — TLS posture, including the L-001
|
||||||
table of `InsecureSkipVerify` justifications (TLS-ALPN-01 row).
|
table of `InsecureSkipVerify` justifications (TLS-ALPN-01 row).
|
||||||
- [`internal/api/acme/jws.go`](../internal/api/acme/jws.go) — verifier
|
- [`internal/api/acme/jws.go`](../internal/api/acme/jws.go) — verifier
|
||||||
source.
|
source.
|
||||||
|
|||||||
@@ -12,9 +12,9 @@ external PKI vendors today.
|
|||||||
> **Phase status (2026-05-03):** Phase 6 — full operator-facing
|
> **Phase status (2026-05-03):** Phase 6 — full operator-facing
|
||||||
> reference. The functional surface is complete (Phases 1a-5); this
|
> reference. The functional surface is complete (Phases 1a-5); this
|
||||||
> doc is the canonical procurement-readability reference. New: client-
|
> doc is the canonical procurement-readability reference. New: client-
|
||||||
> walkthrough docs for [cert-manager](./acme-cert-manager-walkthrough.md),
|
> walkthrough docs for [cert-manager](../../migration/acme-from-cert-manager.md),
|
||||||
> [Caddy](./acme-caddy-walkthrough.md), and
|
> [Caddy](../../migration/acme-from-caddy.md), and
|
||||||
> [Traefik](./acme-traefik-walkthrough.md); a dedicated
|
> [Traefik](../../migration/acme-from-traefik.md); a dedicated
|
||||||
> [threat model](./acme-server-threat-model.md); a section-by-section
|
> [threat model](./acme-server-threat-model.md); a section-by-section
|
||||||
> RFC 8555 + RFC 9773 conformance statement; a 5-failure-mode
|
> RFC 8555 + RFC 9773 conformance statement; a 5-failure-mode
|
||||||
> troubleshooting playbook; a tested-clients version pinning table.
|
> troubleshooting playbook; a tested-clients version pinning table.
|
||||||
@@ -600,7 +600,7 @@ Yes. The endpoints are HTTPS over the certctl-server's listener (port
|
|||||||
Posh-ACME on a Mac all integrate against
|
Posh-ACME on a Mac all integrate against
|
||||||
`https://<certctl-server>:8443/acme/profile/<profile-id>/directory`.
|
`https://<certctl-server>:8443/acme/profile/<profile-id>/directory`.
|
||||||
The TLS-trust-bootstrap requirement applies the same way — see the
|
The TLS-trust-bootstrap requirement applies the same way — see the
|
||||||
[Caddy walkthrough](./acme-caddy-walkthrough.md) for the OS-trust-store
|
[Caddy walkthrough](../../migration/acme-from-caddy.md) for the OS-trust-store
|
||||||
recipe.
|
recipe.
|
||||||
|
|
||||||
### How do I migrate manually-issued certs to ACME-issued ones?
|
### How do I migrate manually-issued certs to ACME-issued ones?
|
||||||
@@ -640,9 +640,9 @@ Read before writing a security review.
|
|||||||
|
|
||||||
## See also
|
## See also
|
||||||
|
|
||||||
- [cert-manager integration walkthrough](./acme-cert-manager-walkthrough.md)
|
- [cert-manager integration walkthrough](../../migration/acme-from-cert-manager.md)
|
||||||
- [Caddy integration walkthrough](./acme-caddy-walkthrough.md)
|
- [Caddy integration walkthrough](../../migration/acme-from-caddy.md)
|
||||||
- [Traefik integration walkthrough](./acme-traefik-walkthrough.md)
|
- [Traefik integration walkthrough](../../migration/acme-from-traefik.md)
|
||||||
- [Threat model](./acme-server-threat-model.md)
|
- [Threat model](./acme-server-threat-model.md)
|
||||||
- [TLS trust bootstrap reference](./tls.md)
|
- [TLS trust bootstrap reference](./tls.md)
|
||||||
- [Architecture (control-plane)](./architecture.md)
|
- [Architecture (control-plane)](./architecture.md)
|
||||||
|
|||||||
Reference in New Issue
Block a user