78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# cert-manager Architecture
|
|
|
|
This document records the complete certificate control-plane contract for the `svc.plus` platform.
|
|
|
|
## Scope
|
|
|
|
The system is split into four distinct responsibilities:
|
|
|
|
- `cert-manager` owns certificate issuance, renewal, and the target `Secret` objects.
|
|
- `Caddy` remains the ingress surface and serves HTTP-01 challenge traffic.
|
|
- `external-dns` only manages DNS records for public hostnames.
|
|
- `external-secrets` continues to materialize Vault-sourced application secrets, AK/SK pairs, future provider credentials such as the Cloudflare API token, and image pull secrets.
|
|
|
|
## Default Contract
|
|
|
|
- `postgresql-prod.svc.plus` defaults to `cert-manager + ACME HTTP-01`.
|
|
- `DNS-01 + Cloudflare` is predeclared for wildcard certificates and future subdomains.
|
|
- `selfSigned` remains available as an internal temporary or recovery fallback.
|
|
- `cert-manager` owns `postgresql-tls` in every namespace that consumes it, so there is no cross-namespace Secret sync job.
|
|
|
|
## System Diagram
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Vault[(Vault)]
|
|
ESO[external-secrets]
|
|
CloudflareToken[(cloudflare-api-token Secret)]
|
|
ExternalDNS[external-dns]
|
|
DNSZone[(svc.plus DNS zone)]
|
|
Caddy[Caddy Ingress]
|
|
CertMgr[cert-manager]
|
|
Http01["ACME HTTP-01"]
|
|
Dns01["ACME DNS-01 + Cloudflare"]
|
|
SelfSigned["selfSigned fallback"]
|
|
PlatformCert["platform/postgresql-tls Certificate"]
|
|
PlatformSecret["platform/postgresql-tls Secret"]
|
|
DatabaseCert["database/postgresql-tls Certificate"]
|
|
DatabaseSecret["database/postgresql-tls Secret"]
|
|
PostgreSQL["postgresql-prod.svc.plus"]
|
|
Stunnel["database/stunnel-server"]
|
|
|
|
Vault --> ESO
|
|
ESO --> CloudflareToken
|
|
CloudflareToken --> Dns01
|
|
ExternalDNS --> DNSZone
|
|
DNSZone --> Caddy
|
|
Caddy --> Http01
|
|
Http01 --> CertMgr
|
|
Dns01 --> CertMgr
|
|
SelfSigned -. fallback .-> CertMgr
|
|
CertMgr --> PlatformCert
|
|
CertMgr --> DatabaseCert
|
|
PlatformCert --> PlatformSecret
|
|
DatabaseCert --> DatabaseSecret
|
|
PlatformSecret --> Caddy
|
|
DatabaseSecret --> Stunnel
|
|
Caddy --> PostgreSQL
|
|
```
|
|
|
|
## Operational Rules
|
|
|
|
- Keep `cert-manager` as the source of truth for TLS Secret ownership.
|
|
- Keep `Caddy` as the traffic and HTTP-01 routing layer only.
|
|
- Keep `external-dns` focused on DNS record reconciliation.
|
|
- Keep `external-secrets` focused on external secret materialization.
|
|
- Treat the Cloudflare API token as an external input secret; it can be bootstrapped manually or delivered by `external-secrets` when that path is wired in.
|
|
- Prefer namespace-local `Certificate` objects for each consumer namespace.
|
|
- Avoid cross-namespace certificate copying or Secret sync controllers.
|
|
|
|
## Related Playbook Roles
|
|
|
|
- `vhosts/k3s_platform_bootstrap`
|
|
- installs the platform node and prepares GitOps handoff
|
|
- `vhosts/k3s_platform_addon`
|
|
- installs shared platform services such as `cert-manager`, `external-secrets`, `caddy`, and `external-dns`
|
|
- `GitOps`
|
|
- owns the namespace-local `Certificate` manifests and workload wiring
|