Skip to content

Commit 85bd068

Browse files
lllamnypclaude
andcommitted
docs(unified-tls-pki): anchor the engine table and fix three facts
The engine table described `main` in the present tense, so it goes stale every time the contract lands somewhere new. Anchor it to one dated moment and drop "today" from the two column headers and the takeaway; the table is a record of the gap this contract closes, not a tracker of `main`. Three claims were stale under that anchor. postgres, nats and qdrant all render a TenantProjection sentinel on `main` and deliver `<release>.tenant-ca`, so their "ca.crt to tenant?" cells and the takeaway now say so, and section 6 and the rollout list no longer carry nats and qdrant as convergence still to come. Two identifiers were wrong outright: redis's CA Secret is `<release>.ca-tls`, with a dot for the same collision-across-releases reason section 4 gives for the canonical name, and the carried operator patch is cut from freshworks-oss/redis-operator#85 commit 2ad2ed8d1. mariadb's `<release>-ca-tls` is hyphenated and is left alone. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01EoDWFXj3QE4Afg7Et9wFxy Signed-off-by: Timofei Larkin <[email protected]>
1 parent b76b162 commit 85bd068

1 file changed

Lines changed: 9 additions & 9 deletions

File tree

‎design-proposals/unified-tls-pki/README.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -113,23 +113,23 @@ The edge is largely done and is recorded here only to fix the framing. An operat
113113

114114
### 3. Interior PKI-ownership contract
115115

116-
The contract is a per-engine table. It is the artifact the per-app pull requests must conform to, and it makes the two-tier reality explicit: the operator owns the CA; the platform unifies only how `ca.crt` is consumed. The decisive column is **"self-publishes a key-free `ca.crt`?"** — that, not "mint vs consume", is what determines whether an engine needs a delivery mechanism.
116+
The contract is a per-engine table. It is the artifact the per-app pull requests must conform to, and it makes the two-tier reality explicit: the operator owns the CA; the platform unifies only how `ca.crt` is consumed. The decisive column is **"self-publishes a key-free `ca.crt`?"** — that, not "mint vs consume", is what determines whether an engine needs a delivery mechanism. The table describes `main` as of 2026-09-02.
117117

118-
| Engine | PKI owner | CA-bearing Secret today | Key in that Secret? | Self-publishes key-free `ca.crt`? | `ca.crt` to tenant today? | Operator certificate capability |
118+
| Engine | PKI owner | CA-bearing Secret | Key in that Secret? | Self-publishes key-free `ca.crt`? | `ca.crt` to tenant? | Operator certificate capability |
119119
| --- | --- | --- | --- | --- | --- | --- |
120120
| kafka (Strimzi) | operator | `<release>-cluster-ca-cert`, `<release>-clients-ca-cert` | no | **yes** | yes — clean reference | `generateCertificateAuthority: false` BYO-CA + per-listener `brokerCertChainAndKey`; public cert on external listener, own-CA mTLS internally |
121-
| redis | none — no TLS on `main` | none — the chart renders no TLS objects on `main`; `cozystack/cozystack#2729` (open, in review) adds a chart cert-manager chain whose CA Secret `<release>-ca-tls` is key-bearing | n/a | **not yet** — under `cozystack/cozystack#2729` the patched operator does publish a key-free `<release>-ca-cert`, but nothing on the platform reads it: the chart's sentinel sources the cert-manager CA instead | no | stock freshworks-oss `redis-operator` v3.3.5 has no TLS support; `cozystack/cozystack#2729` carries it as a downstream patch over v3.3.5 (`packages/system/redis-operator/images/redis-operator/patches/tls.diff`, cut from freshworks-oss/redis-operator#85 commit 38b9e3732), which adds `spec.tls` including `caCertSecretName` |
122-
| postgres (CloudNativePG) | operator | `<release>-ca` (operator-created, async) | **yes — `ca.key`** | no | no — tenant gets passwords-only `<release>-credentials` (gap) | `serverCASecret` / `serverTLSSecret` BYO; single server cert, no edge/internal split |
121+
| redis | none — no TLS on `main` | none — the chart renders no TLS objects on `main`; `cozystack/cozystack#2729` (open, in review) adds a chart cert-manager chain whose CA Secret `<release>.ca-tls` is key-bearing | n/a | **not yet** — under `cozystack/cozystack#2729` the patched operator does publish a key-free `<release>-ca-cert`, but nothing on the platform reads it: the chart's sentinel sources the cert-manager CA instead | no | stock freshworks-oss `redis-operator` v3.3.5 has no TLS support; `cozystack/cozystack#2729` carries it as a downstream patch over v3.3.5 (`packages/system/redis-operator/images/redis-operator/patches/tls.diff`, cut from freshworks-oss/redis-operator#85 commit 2ad2ed8d1), which adds `spec.tls` including `caCertSecretName` |
122+
| postgres (CloudNativePG) | operator | `<release>-ca` (operator-created, async) | **yes — `ca.key`** | no | yes — `<release>.tenant-ca`, alongside the unchanged passwords-only `<release>-credentials` | `serverCASecret` / `serverTLSSecret` BYO; single server cert, no edge/internal split |
123123
| mongodb (Percona PSMDB) | operator | `<release>-ca-cert` (operator-created at runtime; the chart renders no TLS objects) | **yes — cert-manager `isCA`** | no | no (gap; name collides with redis, opposite shape) | `spec.tls.issuerConf` BYO issuer; auto-mints a cert-manager chain |
124-
| nats | chart + cert-manager | `<release>-ca` | yes | no | no | — |
125-
| qdrant | chart + cert-manager | `<release>-ca` | yes | no | no | — |
124+
| nats | chart + cert-manager | `<release>-ca` | yes | no | yes, when TLS is on | — |
125+
| qdrant | chart + cert-manager | `<release>-ca` | yes | no | yes, when TLS is on | — |
126126
| mariadb | none — no TLS on `main` | none — the chart renders no TLS objects on `main`; `cozystack/cozystack#2680` (open, in review) adds a chart cert-manager chain whose CA Secret `<release>-ca-tls` is key-bearing | n/a | no | no | mariadb-operator `serverCertSecretRef` / `serverCASecretRef` / `serverCertIssuerRef` |
127127
| opensearch | operator — opster generates its own TLS | none chart-rendered — on `main` the chart sets `security.tls.transport.generate` and `security.tls.http.generate`, so opster mints the material and the chart renders no cert-manager objects; `cozystack/cozystack#2682` (open, in review) adds a chart cert-manager chain whose CA Secret `<release>-http-ca` is key-bearing | n/a | no | no | opster `security.tls.http.secret.name`; transport operator-generated |
128128
| rabbitmq | none — no TLS on `main` | none — the chart renders no TLS objects on `main`; `cozystack/cozystack#2683` (open, in review) adds a chart cert-manager chain whose CA Secret `<release>-ca` is key-bearing | n/a | no | no | cluster-operator `spec.tls.secretName` / `caSecretName` |
129129
| clickhouse (Altinity) | — (BYO-cert) | supplied cert mount | n/a | no | no (not in TLS series yet) | mounts a supplied cert; no native issuance |
130130
| kubernetes (Kamaji) | Kamaji | Kamaji-owned, not swappable | n/a | n/a | no — out of model | control-plane CA, kubeconfig-pinned, non-swappable |
131131

132-
The takeaway: **kafka** (native) is the only engine that publishes a key-free `ca.crt` under its own name today, and it is still not at the canonical `<release>.tenant-ca` — it alone needs the controller to copy that output across under that name (§5). **Every other engine that ships TLS on `main` today — postgres, mongodb, nats, qdrant — has a key-bearing CA Secret and delivers no `ca.crt` to the tenant**, one uniform delivery gap, and the four whose TLS is still in review (redis, mariadb, rabbitmq, opensearch) all mint a key-bearing CA the same way. **redis** is the one that already closes the gap inside its own pull request: `cozystack/cozystack#2729` declares a `TenantProjection` sentinel naming that key-bearing chart CA, so the anchor lands directly at `<release>.tenant-ca` with the key stripped, and the key-free `<release>-ca-cert` its patched operator also publishes goes unread. The gap does **not** split along mint-versus-consume: postgres and mongodb are operator-owned, yet their CA Secret is key-bearing (and operator-created, hence asynchronous), so they need the same key-free projection as the cert-manager-minting engines. The cert-manager-minting engines additionally never reach the tenant at all. Kamaji anchors the other end of the table: a PKI owner so absolute that the only sane unification is the one this contract chooses — leave the CA alone, unify how trust reaches the client.
132+
The takeaway: **kafka** (native) is the only engine that publishes a key-free `ca.crt` under its own name, and it is still not at the canonical `<release>.tenant-ca` — it alone needs the controller to copy that output across under that name (§5). **Every other engine that ships TLS — postgres, mongodb, nats, qdrant — has a key-bearing CA Secret**, one uniform delivery gap; postgres, nats and qdrant have since closed it by declaring a sentinel, leaving mongodb, and the four whose TLS is still in review (redis, mariadb, rabbitmq, opensearch) all mint a key-bearing CA the same way. **redis** is the one that already closes the gap inside its own pull request: `cozystack/cozystack#2729` declares a `TenantProjection` sentinel naming that key-bearing chart CA, so the anchor lands directly at `<release>.tenant-ca` with the key stripped, and the key-free `<release>-ca-cert` its patched operator also publishes goes unread. The gap does **not** split along mint-versus-consume: postgres and mongodb are operator-owned, yet their CA Secret is key-bearing (and operator-created, hence asynchronous), so they need the same key-free projection as the cert-manager-minting engines. The cert-manager-minting engines additionally never reach the tenant at all. Kamaji anchors the other end of the table: a PKI owner so absolute that the only sane unification is the one this contract chooses — leave the CA alone, unify how trust reaches the client.
133133

134134
### 4. The uniform consume contract
135135

@@ -191,7 +191,7 @@ What this *reuses* rather than rebuilds: Flux's release-name label and its nativ
191191

192192
### 6. Per-engine application order
193193

194-
`postgres` goes first (under the tracking issue `cozystack/cozystack#2814`): it is the engine the epic most wants to see converged, and it exercises the controller against the hardest input — an **operator-created, asynchronous** CA Secret — so validating it there validates the mechanism everywhere. Convergence for postgres means publishing a key-free `<release>.tenant-ca` extracted from CNPG's key-bearing `<release>-ca`, while leaving the passwords-only `<release>-credentials` untouched. `kafka` already publishes a key-free `ca.crt` under its own name, so it converges by declaring a `TenantProjection` sentinel that names `<release>-clients-ca-cert` as the source — a straight copy with nothing to strip. `redis` (`cozystack/cozystack#2729`) is a stripping case rather than a straight copy: its chart mints a cert-manager chain and declares a sentinel naming the key-bearing `<release>-ca-tls` that chain produces, so the controller lifts `ca.crt` and drops the key, and the key-free `<release>-ca-cert` the patched operator also publishes goes unread. `mongodb`, then the cert-manager-minting engines (nats, qdrant, and then rabbitmq, mariadb, opensearch) converge by declaring a `TenantProjection` sentinel that names their CA Secret. `kubernetes` (Kamaji) is explicitly out.
194+
`postgres` goes first (under the tracking issue `cozystack/cozystack#2814`): it is the engine the epic most wants to see converged, and it exercises the controller against the hardest input — an **operator-created, asynchronous** CA Secret — so validating it there validates the mechanism everywhere. Convergence for postgres means publishing a key-free `<release>.tenant-ca` extracted from CNPG's key-bearing `<release>-ca`, while leaving the passwords-only `<release>-credentials` untouched. `kafka` already publishes a key-free `ca.crt` under its own name, so it converges by declaring a `TenantProjection` sentinel that names `<release>-clients-ca-cert` as the source — a straight copy with nothing to strip. `redis` (`cozystack/cozystack#2729`) is a stripping case rather than a straight copy: its chart mints a cert-manager chain and declares a sentinel naming the key-bearing `<release>.ca-tls` that chain produces, so the controller lifts `ca.crt` and drops the key, and the key-free `<release>-ca-cert` the patched operator also publishes goes unread. `nats` and `qdrant` have since converged the same way. `mongodb`, then rabbitmq, mariadb and opensearch, converge by declaring a `TenantProjection` sentinel that names their CA Secret. `kubernetes` (Kamaji) is explicitly out.
195195

196196
## User-facing changes
197197

@@ -232,7 +232,7 @@ Two consequences for the controller. First, it writes at runtime, after chart-re
232232
1. Edge — `cozystack/cozystack#2988`, `cozystack/cozystack#2989`, and the per-tenant propagation `cozystack/cozystack#2990` are all merged.
233233
2. This contract — accepted.
234234
3. Sentinel CRD and extraction controller — implemented and tested.
235-
4. Per-app convergence — postgres first (tracked by `cozystack/cozystack#2814`), then the remaining per-app TLS pull requests onto the contract.
235+
4. Per-app convergence — postgres (tracked by `cozystack/cozystack#2814`), nats and qdrant merged; the remaining per-app TLS pull requests onto the contract.
236236

237237
## Open questions
238238

0 commit comments

Comments
 (0)