Skip to content

Commit 13606b8

Browse files
committed
docs(unified-tls-pki): say application where the printed name uses one
The redis worked pair named its two colliding objects as releases while printing prefixed names, so the collision did not follow from its own inputs; the mariadb sentence inherits the pair and the same fix. Three neighbours go with it: the dot's leg count no longer adds up now that the residue is two assumptions rather than one, the table's exclusion list reads as a subject list before it resolves, and the two labels the guard paragraph warns about are alike in role rather than in spelling. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 9b3b124 commit 13606b8

1 file changed

Lines changed: 4 additions & 4 deletions

File tree

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ The edge is recorded here only to fix the framing. An operator selects the certi
119119

120120
### 3. Interior PKI-ownership contract
121121

122-
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 decides whether the controller's extraction is a straight copy or a strip. Every engine in the table but clickhouse, which serves no TLS, and Kamaji declares a sentinel either way. Filling in the last column takes one more question, the one §5 asks: whether the chart's sentinel names that key-free object, or the key-bearing one beside it. The table is deliberately free of convergence state: it records who owns each engine's CA, whether that object carries a key, and what the controller must therefore do, all of which outlive any particular branch. A series number in a cell is the provenance of a fact, not a status. Which engines have already converged is tracked in `cozystack/cozystack#2814`.
122+
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 decides whether the controller's extraction is a straight copy or a strip. Every engine in the table declares a sentinel either way, except clickhouse, which serves no TLS, and Kamaji. Filling in the last column takes one more question, the one §5 asks: whether the chart's sentinel names that key-free object, or the key-bearing one beside it. The table is deliberately free of convergence state: it records who owns each engine's CA, whether that object carries a key, and what the controller must therefore do, all of which outlive any particular branch. A series number in a cell is the provenance of a fact, not a status. Which engines have already converged is tracked in `cozystack/cozystack#2814`.
123123

124124
| Engine | PKI owner | CA-bearing Secret | Key in that Secret? | Self-publishes key-free `ca.crt`? | Delivery under this contract | Operator certificate capability |
125125
| --- | --- | --- | --- | --- | --- | --- |
@@ -143,15 +143,15 @@ Every engine, regardless of who owns its CA, exposes its trust anchor through on
143143

144144
The name took three revisions, and the reason is worth recording because it is the same mistake twice. `<release>-ca-cert` was rejected because Percona PSMDB already creates a Secret of that exact name and puts a private key in it — a collision across **engines**. Its replacement `<release>-tenant-ca` was justified as "claimed by no operator this platform ships", and that was false: it collides across **releases**. For an application `foo` the projection is `postgres-foo-tenant-ca`; for a sibling application `foo-tenant`, CloudNativePG's own CA is `postgres-foo-tenant` + `-ca` — the same string. Both names are legal and several Postgres instances in one namespace is the normal model. Nor is it merely a guard problem: if the projection lands first, CNPG rejects the key-free Secret (`missing ca.key secret data`) and the sibling's PKI never completes, so the sibling application never comes up — silently, blaming a Secret its owner never created. That would be a regression rather than a limitation: the name was unclaimed before this contract existed, so both applications worked, and no guard could refuse it, because the controller that wrote first was legitimate. Only the first of the three was ever published in a proposal; `<release>-tenant-ca` lived entirely inside this document's revision history. No release ever wrote either of them: the extraction controller carried the `.tenant-ca` suffix in the revision that merged.
145145

146-
The canonical name is therefore `<release>.tenant-ca`, and the dot is what does the work. Two of its three legs are machine-enforced, and both are worth naming because they are the reason the dot is available at all. Application names are validated as DNS-1035 labels (`k8svalidation.IsDNS1035Label`, `pkg/apis/apps/validation/validation.go`), so a dot is structurally impossible inside one. A release prefix is pinned to `^[a-z0-9-]*$` on `ApplicationDefinitionRelease` (`api/v1alpha1/applicationdefinitions_types.go`), which excludes the dot by construction. Secret names are DNS-1123 subdomains, where a dot is legal — so `<release>.tenant-ca` is a name the platform can write and no `<prefix><application>` the apps API admits can spell.
146+
The canonical name is therefore `<release>.tenant-ca`, and the dot is what does the work. Two of its legs are machine-enforced, and both are worth naming because they are the reason the dot is available at all. Application names are validated as DNS-1035 labels (`k8svalidation.IsDNS1035Label`, `pkg/apis/apps/validation/validation.go`), so a dot is structurally impossible inside one. A release prefix is pinned to `^[a-z0-9-]*$` on `ApplicationDefinitionRelease` (`api/v1alpha1/applicationdefinitions_types.go`), which excludes the dot by construction. Secret names are DNS-1123 subdomains, where a dot is legal — so `<release>.tenant-ca` is a name the platform can write and no `<prefix><application>` the apps API admits can spell.
147147

148148
Two things are assumed rather than enforced, and both are worth stating. The first is that the release name is dot-free. The apps API makes it so, through the two legs above — but the controller derives the release from a `helm.toolkit.fluxcd.io/name` label value, where a dot is legal, so a hand-written HelmRelease carrying one is outside the guarantee. Under a dot-free release name the arithmetic is narrow: **`<prefix><application><suffix>` can spell `<release>.tenant-ca` only by supplying that dot itself — that is, only when the suffix ends with `.tenant-ca`**. The second assumption is that no suffix in use does. Nothing validates a suffix; chart authors and upstream operators pick them, and dotted ones are already in use here — under `cozystack/cozystack#2729` the redis chart names its CA Secret `<release>.ca-tls` and its leaf `<release>.tls`, the operator that series patches writes `<release>.ca-cert`, `cozystack/cozystack#2680` gives mariadb the same pair, and `cozystack/cozystack#2682` names the opensearch CA Secret `<release>.http-ca`. None of those ends with `.tenant-ca`, so none reaches the canonical name; but that is a claim about a set this platform keeps growing.
149149

150150
What makes the name safe is that the residue is guarded rather than argued away. A Secret already occupying `<release>.tenant-ca` that this controller did not create is never overwritten and never adopted — §5(f) — so a future suffix that did collide surfaces as a refusal, with a Warning Event on the colliding Secret and a `Ready=False` condition on the sentinel naming it. That is the difference from the two names before it, and it is a difference in failure direction rather than in confidence. `<release>-tenant-ca` had no refusal available at all: a sibling application whose own CA the projection pre-empted would have stopped coming up, silently, and no guard could have refused the write, because the writer that got there first was legitimate. This one fails *closed* in the direction the controller controls: a stranger already at the canonical name is refused, loudly. The other direction is not symmetric and should not be claimed as such — if the projection is written first and some future operator suffix then wants that same name, what happens is that operator's behaviour, not this controller's, and CNPG's rejection of a key-free Secret is what that looks like. What has changed is the probability, not the shape: `<release>-tenant-ca` collided with an operator the platform already ships, and `.tenant-ca` collides only with a suffix ending in `.tenant-ca`, which nobody has written.
151151

152152
The same reasoning applies one level down, to the source Secrets a chart renders, and the contract should say so rather than leave the next per-engine author to rediscover it. Two per-release Secrets collide across releases exactly when one of their suffixes is a tail of the other: if the suffix set holds both `-x` and `-y-x`, then release `foo`'s `-y-x` object and release `foo-y`'s `-x` object are the same string, and both release names are legal. The set to check is every per-release Secret suffix that lands in the namespace, the ones an operator writes included, not only the ones the chart renders.
153153

154-
**A chart separates a per-release Secret suffix with a dot when, and only when, that pair exists in its set.** The check belongs to the chart author, over the whole set, and this document deliberately does not publish a verdict per engine: an enumeration that misses one operator-written name produces exactly the false clearance this section is warning about. Three worked pairs, because they are documented in the charts themselves. Under `cozystack/cozystack#2729` the redis set holds `-ca-tls` and `-tls`, so hyphenated, release `foo`'s CA Secret and release `foo-ca`'s leaf Secret would both be `redis-foo-ca-tls`; it uses `<release>.ca-tls` and `<release>.tls` for that reason and records it in a comment on the Certificate. Under `cozystack/cozystack#2680` the mariadb chart's cert-manager path renders that same pair and separates it the same way, restating the rule in a comment on its own Certificate. And opensearch is the case that shows why the operator's names count: opster writes its own transport CA at `<clusterName>-ca` unconditionally, and keeping the chart's CA apart within one release is not enough, because across releases the two meet anyway — with a hyphenated `-http-ca`, application `foo`'s chart CA and application `foo-http`'s operator CA would both be `opensearch-foo-http-ca`, which is why `cozystack/cozystack#2682` separates it with a dot. So the dot is neither a platform-wide convention nor a redis-local taste: it is what this contract asks of new work wherever the mechanism above finds the pair, and applying it anywhere else buys nothing.
154+
**A chart separates a per-release Secret suffix with a dot when, and only when, that pair exists in its set.** The check belongs to the chart author, over the whole set, and this document deliberately does not publish a verdict per engine: an enumeration that misses one operator-written name produces exactly the false clearance this section is warning about. Three worked pairs, because they are documented in the charts themselves. Under `cozystack/cozystack#2729` the redis set holds `-ca-tls` and `-tls`, so hyphenated, application `foo`'s CA Secret and application `foo-ca`'s leaf Secret would both be `redis-foo-ca-tls`; it uses `<release>.ca-tls` and `<release>.tls` for that reason and records it in a comment on the Certificate. Under `cozystack/cozystack#2680` the mariadb chart's cert-manager path renders that same pair and separates it the same way, restating the rule in a comment on its own Certificate. And opensearch is the case that shows why the operator's names count: opster writes its own transport CA at `<clusterName>-ca` unconditionally, and keeping the chart's CA apart within one release is not enough, because across releases the two meet anyway — with a hyphenated `-http-ca`, application `foo`'s chart CA and application `foo-http`'s operator CA would both be `opensearch-foo-http-ca`, which is why `cozystack/cozystack#2682` separates it with a dot. So the dot is neither a platform-wide convention nor a redis-local taste: it is what this contract asks of new work wherever the mechanism above finds the pair, and applying it anywhere else buys nothing.
155155

156156
This is where the label-filtered projection matters. Because `tenantsecrets` delivers the whole Secret `Data`, the helper's fail-closed guard is not a nicety — it is the boundary that keeps a server or CA private key out of a tenant's hands. Kafka's `<release>-cluster-ca-cert` is the shape to match: a CA certificate, no key, readable by the tenant.
157157

@@ -201,7 +201,7 @@ The sentinel is a **declaration**, not a copy of the data: the chart renders it
201201

202202
**(f) Revocation is part of the mechanism, and the canonical name is guarded.** The `tenantresource` verdict in (c) has to be able to go back to `false`, and that does not happen for free. Each projection records a digest of the owning `ApplicationDefinition`'s `spec.secrets` in `internal.cozystack.io/ca-cert-selectors`, and the digest is part of the drift check, so a change to those selectors forces exactly one write; that write also drops the `internal.cozystack.io/managed-by-cozystack` marker, which is what hands the projection back to the lineage webhook — the webhook's `objectSelector` skips any object already carrying the marker, so forcing a write without dropping it would leave the verdict frozen at whatever the selectors said on create. Both halves together are what lets a definition that stops selecting the anchor actually take the tenant's read access away, instead of leaving it reading a trust anchor the platform withdrew. The canonical name carries its own guards, and they are two distinct refusals. A Secret at `<release>.tenant-ca` that this controller did not create is never overwritten and never adopted: adoption keys on the projection's **owner reference** back to a `TenantProjection` of the sentinel's name, not on any label — a label is something any writer in the namespace can forge or strip, and keying adoption on one would let an actor who strips it make the controller disown its own object and keep serving whatever bytes that actor wrote. A stranger at the name is refused as `Ready=False, Reason=ProjectionCollision`, with a Warning Event on the colliding Secret. Separately, when the sentinel's own declared source *is* the canonical name and carries private key material, the answer is `Ready=False, Reason=CanonicalNameOccupied` and a Warning Event on that Secret. There is a third outcome that is neither refusal: when the declared source sits at the canonical name and is key-free, it already *is* the trust anchor, so the controller writes nothing and reports `Ready=True, Reason=Projected` — and if that Secret departs from the shape the name promises, it emits a `CACertCanonicalNameContract` Warning Event rather than silently implying it checked out. It is the only path on which the object a tenant reads at that name is not one the controller wrote. A release whose anchor is declared more than once publishes no new anchor, and one an earlier uncontested reconcile already published is left in place rather than withdrawn, because taking a trust anchor away is worse than leaving a stale one visible beside the condition that explains it — `MultipleCACertProjections` when a single sentinel declares two `CACert` entries, `ReleaseContested` when two sentinels in one namespace claim the same release. All of these live in `internal/controller/cacert/reconciler.go`.
203203

204-
**(g) Which label is written by whom, on the projection.** Five labels appear below; four are stamped on the projection and the last is Flux's, on the sentinel. An anchor a chart renders through `cozy-lib.tls.caCertSecret` instead of through this controller carries its two selector labels from the helper — the table is about the projected object, not about every route to a trust anchor. Two of the five have names close enough to be used interchangeably by mistake: `internal.cozystack.io/ca-cert-copy`, the controller's own marker, and `internal.cozystack.io/managed-by-cozystack`, the webhook's. Making that mistake would be a real bug in one specific direction, though the shipped controller does not: the lineage webhook is registered with `objectSelector` `managed-by-cozystack` `DoesNotExist`, so a projection created already carrying that marker never reaches the webhook — it is admitted, the webhook simply skips it — and therefore never receives a `tenantresource` verdict, and no tenant ever reads the trust anchor. Neither name is what adoption keys on — see (f).
204+
**(g) Which label is written by whom, on the projection.** Five labels appear below; four are stamped on the projection and the last is Flux's, on the sentinel. An anchor a chart renders through `cozy-lib.tls.caCertSecret` instead of through this controller carries its two selector labels from the helper — the table is about the projected object, not about every route to a trust anchor. Two of the five both read as ownership markers and are easy to reach for interchangeably: `internal.cozystack.io/ca-cert-copy`, the controller's own marker, and `internal.cozystack.io/managed-by-cozystack`, the webhook's. Making that mistake would be a real bug in one specific direction, though the shipped controller does not: the lineage webhook is registered with `objectSelector` `managed-by-cozystack` `DoesNotExist`, so a projection created already carrying that marker never reaches the webhook — it is admitted, the webhook simply skips it — and therefore never receives a `tenantresource` verdict, and no tenant ever reads the trust anchor. Neither name is what adoption keys on — see (f).
205205

206206
| Label | Written by | What it means |
207207
| --- | --- | --- |

0 commit comments

Comments
 (0)