jakman85andClaude Opus 4.8
e8c555cfeb
Greenfield spec set for a GitOps-driven PaaS+IaaS home platform: vision & requirements (R-* IDs), architecture, 14 domain specs, 11 ADRs, roadmap (phases + workstreams), and AI-agent coordination (roles, protocol, definition-of-done, task board). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
# ADR-0006 — TLS: cert-manager + Let's Encrypt (DNS-01)
|
|
- Status: Accepted
|
|
- Date: 2026-08-15
|
|
- Serves: R-TLS-01, R-TLS-02, R-TLS-03, R-DNS-01
|
|
- Supersedes: —
|
|
|
|
## Context
|
|
Every service needs a **trusted, non-self-signed** certificate, auto issued/renewed/revoked,
|
|
including **internal-only** services (which must not be forced public just to validate a cert).
|
|
Wildcard coverage of `*.home.keithjackson.dev` would make onboarding certificate-free.
|
|
|
|
## Decision
|
|
Use **cert-manager** with **Let's Encrypt** (a publicly trusted, free, automatable CA) via the
|
|
**ACME DNS-01** challenge against the `keithjackson.dev` DNS zone (Cloudflare or equivalent, OQ-4).
|
|
DNS-01 validates domain control without exposing the service and enables **wildcard** certs.
|
|
Default: a **wildcard `*.home.keithjackson.dev`** certificate terminated at the Gateway ([09](../docs/09-dns-and-ingress.md)),
|
|
with per-service certificates available where isolation warrants. Provide both `letsencrypt-staging`
|
|
(bring-up) and `letsencrypt-prod` ClusterIssuers.
|
|
|
|
## Alternatives considered
|
|
- **HTTP-01 challenge** — rejected: requires public exposure of each service; fails R-TLS-03 for
|
|
internal-only services and can't do wildcards.
|
|
- **Self-signed / private CA** — rejected: explicitly disallowed (R-TLS-01, "not self-signed").
|
|
- **Paid CA** — unnecessary; Let's Encrypt is trusted and free.
|
|
- **ZeroSSL/other ACME CA** — viable fallback; Let's Encrypt chosen as default.
|
|
|
|
## Consequences
|
|
- Internal services get real, trusted certs; wildcard makes onboarding certificate-free (default).
|
|
- Requires a DNS-provider API token scoped for DNS-01, stored SOPS-encrypted (OQ-4, ADR-0007).
|
|
- Certificate expiry/issuance failures are alert conditions (R-OBS-04).
|
|
- Internal clients trust the certs with no custom-CA distribution; split-horizon DNS serves the same
|
|
cert internally and externally.
|
|
- Optional future mTLS between workloads is a separate concern (Cilium/mesh), not covered here.
|