docs(nats): document the tenant-facing CA trust anchor

Enabling TLS gave a tenant no documented way to obtain the CA certificate,
so the server could not actually be verified — which is the point of turning
TLS on in the first place.

Records where the trust anchor lives (<release>.tenant-ca, reached through
tenantsecrets), and why the chart's nats-<name>-ca and nats-<name>-tls
Secrets are not that path: both carry private keys, so read access to either
would convey the ability to issue certificates rather than verify them.

Signed-off-by: Aleksei Sviridkin <f@lex.la>
Assisted-By: Claude <noreply@anthropic.com>
This commit is contained in:
Aleksei Sviridkin authored and Aleksei Sviridkin committed 2026-08-12 18:42:13 +03:00
1 parent 7e26358817
commit 936bdf0c47
1 file changed
+19
+19
View File
@@ -56,3 +56,22 @@ Presets follow a cloud-style `<series>.<size>` naming convention. Five series co
See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping.
### tls
`tls.enabled` is tri-state. Left unset it follows `external`, so TLS is enabled automatically for a NATS instance exposed outside the cluster and disabled for one that is not. Setting it explicitly overrides that in either direction.
When TLS is on, the chart issues a self-signed CA and a server certificate from it, and NATS serves the client port on `:4222` with the server certificate.
**Retrieving the CA certificate** for client verification:
The trust anchor is published as `nats-<name>.tenant-ca`: an object holding `ca.crt` and nothing else, delivered to tenants through the `core.cozystack.io/tenantsecrets` API that the base tenant roles already grant.
```bash
kubectl --context <ctx> --namespace <tenant> \
get tenantsecret nats-<name>.tenant-ca \
--output jsonpath='{.data.ca\.crt}' | base64 --decode
```
`nats-<name>.tenant-ca` is the only object that hands over the CA certificate without also handing over a private key, which is why it exists. The chart's own `nats-<name>-ca` Secret stores the CA **private key** under `tls.key` alongside the certificate — read access to it would let the holder issue certificates for anything, so it is never granted to a tenant. The same applies to `nats-<name>-tls`, which holds the server's private key.
It is reached through `tenantsecrets` rather than by reading the Secret directly, and that is deliberate: `tenantsecrets` surfaces only objects the platform has vouched for, whereas a direct grant on the name would convey whatever happens to occupy that name.