From 936bdf0c4711e42440dfc4c1bdee23f01c7072f6 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Sun, 19 Jul 2026 23:11:27 +0300 Subject: [PATCH] docs(nats): document the tenant-facing CA trust anchor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 (.tenant-ca, reached through tenantsecrets), and why the chart's nats--ca and nats--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 Assisted-By: Claude --- packages/apps/nats/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/apps/nats/README.md b/packages/apps/nats/README.md index 213ff2554..011b9337f 100644 --- a/packages/apps/nats/README.md +++ b/packages/apps/nats/README.md @@ -56,3 +56,22 @@ Presets follow a cloud-style `.` 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-.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 --namespace \ + get tenantsecret nats-.tenant-ca \ + --output jsonpath='{.data.ca\.crt}' | base64 --decode +``` + +`nats-.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--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--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.