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]>
3.4 KiB
3.4 KiB
08 — TLS & Certificates
Serves: R-TLS-01/02/03, R-DNS-01. Related: ADR-0006 (cert-manager + Let's Encrypt).
Requirement recap
Every externally reachable service presents TLS from a credible, trusted, non-self-signed authority, with certificates auto issued, renewed, and revoked — including for internal-only services (R-TLS-01/02/03).
Solution: cert-manager + Let's Encrypt via DNS-01
- cert-manager runs in the cluster and manages the full certificate lifecycle.
- Let's Encrypt is the trusted, non-self-signed CA (publicly trusted; free; automatable) — satisfies R-TLS-01.
- ACME DNS-01 challenge against the
keithjackson.devDNS zone (Cloudflare or equivalent, per OQ-4). DNS-01 is the key choice because it validates domain control without exposing the service publicly — so internal-only services get real, trusted certs (R-TLS-03), and wildcard certificates (*.home.keithjackson.dev) are possible.
Issuance model
- A
ClusterIssuerfor Let's Encrypt production (and one for staging, used during bring-up to avoid rate limits). - Certificates are requested declaratively — either a wildcard
*.home.keithjackson.devcert shared by the Gateway, or per-service certs, decided per ADR-0006. Recommendation: a wildcard cert for*.home.keithjackson.devterminated at the Gateway simplifies onboarding (a new service needs no new cert), with per-service certs available where isolation warrants. - The DNS provider API token is a SOPS-encrypted secret (07).
Renewal & revocation (R-TLS-02)
- cert-manager renews well before expiry automatically; no human action.
- Revocation: removing/rotating a certificate is a declarative change; cert-manager handles issuance of replacements. Expiry monitoring is an alert condition (10, R-OBS-04).
Where TLS terminates
- North-south: at the Gateway API listener (implemented by Cilium, 09), using the cert-manager-issued cert. Public services are reached via the edge router forwarding to the Gateway; internal services resolve to the Gateway on the LAN.
- Internal service-to-service traffic relies primarily on network policy for security; mTLS between workloads is optional future hardening (could be added via Cilium/service mesh) and is not a launch requirement — record as a possible future ADR.
Trust chain for internal clients
Because certs come from Let's Encrypt (publicly trusted), internal clients trust them with no custom
CA distribution. Split-horizon DNS (09) resolves
<service>.home.keithjackson.dev to the internal Gateway while the same trusted cert is served.
Acceptance gates
https://<service>.home.keithjackson.devserves a valid, non-self-signed, unexpired certificate (verified by an external TLS checker), including for internal-only services.- Certificates renew automatically ahead of expiry with no manual step (observed across a renewal).
- Certificate expiry and issuance failures raise alerts.
- Onboarding a new service requires no manual certificate step.
Open questions
- OQ-4 — confirm DNS provider (Cloudflare assumed) and an API token scoped for DNS-01.
- Wildcard vs. per-service certs as the default (pinned in ADR-0006).