From 6d4d6d383f388ad681427214d1e67d318ea9b85d Mon Sep 17 00:00:00 2001 From: Erik Godding Boye Date: Sun, 26 Nov 2023 16:02:49 +0100 Subject: [PATCH] Add/update docs for new trust-manager features Signed-off-by: Erik Godding Boye --- .spelling | 1 + content/docs/trust/trust-manager/README.md | 41 ++++++++++++++++------ 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/.spelling b/.spelling index 15673739a42..72710219b5d 100644 --- a/.spelling +++ b/.spelling @@ -458,6 +458,7 @@ upstream userinfo vhosakot v0.5.0 +v0.7.0 v0.16 v0.23.1 v1 diff --git a/content/docs/trust/trust-manager/README.md b/content/docs/trust/trust-manager/README.md index 94a94a416d2..ad75a372f50 100644 --- a/content/docs/trust/trust-manager/README.md +++ b/content/docs/trust/trust-manager/README.md @@ -21,7 +21,7 @@ and enables cluster administrators to easily automate providing a secure bundle to worry about rebuilding containers to update trust stores. It's designed to complement cert-manager and works well when consuming CA certificates from a -cert-manager `Issuer` or `ClusterIssuer` but can be used entirely independently from cert-manager +cert-manager `Issuer` or `ClusterIssuer` but can be used entirely independently of cert-manager if needed. ## Usage @@ -70,12 +70,15 @@ spec: # Sync the bundle to a ConfigMap called `my-org.com` in every namespace which # has the label "linkerd.io/inject=enabled" # All ConfigMaps will include a PEM-formatted bundle, here named "root-certs.pem" - # and in this case we also request a binary JKS formatted bundle, here named "bundle.jks" + # and in this case we also request binary formatted bundles in JKS and PKCS#12 formats, + # here named "bundle.jks" and "bundle.p12". configMap: key: "root-certs.pem" additionalFormats: jks: key: "bundle.jks" + pkcs12: + key: "bundle.p12" namespaceSelector: matchLabels: linkerd.io/inject: "enabled" @@ -88,18 +91,25 @@ spec: - `inLine` - a manually specified string containing at least one certificate - `useDefaultCAs` - usually, a bundle of publicly trusted certificates -These sources, along with the single currently supported target type (`configMap`) -are documented in the trust-manager [API reference documentation](./api-reference.md). +`ConfigMap` is the default target type, but as of v0.7.0 trust-manager also supports `Secret` resources as targets. + +Support for `Secret` targets must be explicitly enabled in the trust-manager controller; see details below under "Enable Secret targets". + +All sources and target options are documented in the trust-manager [API reference documentation](./api-reference.md). #### Targets -All `Bundle` targets are written to `ConfigMap`s whose name matches that of the `Bundle`, and every -target has a PEM-formatted bundle included. +All `Bundle` targets are written to `ConfigMap`s (and/or `Secret`s) whose name matches that of the +`Bundle`, and every target has a PEM-formatted bundle included. + +Users can also optionally choose to write JKS/PKCS#12 formatted binary trust store(s) to targets. +JKS has been supported since v0.5.0, and PKCS#12 since v0.7.0. -Users can also optionally - as of trust-manager v0.5.0 - choose to write a JKS formatted binary -bundle to the target. We understand that most Java applications tend to require a password on JKS -files (even though trust bundles don't contain secrets), so all trust-manager JKS bundles use the -default password `changeit`. +We understand that any binary trust store require a password, even though trust bundles don't contain +secrets. Both JKS and PKCS#12 uses weak encryption primitives, so a trust store (or keystore) will NOT +be protected by a password alone, and needs to be protected by additional measures. +At present, passwords for trust stores are hard-coded to `changeit` for JKS and `""` (the empty string +or "passwordless") for PKCS#12. Future releases of trust-manager may make this configurable. #### Namespace Selector @@ -132,7 +142,16 @@ helm upgrade -i -n cert-manager cert-manager jetstack/cert-manager --set install helm upgrade -i -n cert-manager trust-manager jetstack/trust-manager --wait ``` -### approver-policy Integration +#### Enable Secret targets + +`Secret` targets are supported as of trust-manager v0.7.0, but needs to be explicitly enabled on the controller. +The feature can be enabled with a Helm value `--set secretTargets.enabled=true`, but since the controller needs +RBAC to secrets, you also need to set `secretTargets.authorizedSecretsAll` or `secretTargets.authorizedSecrets`. +Please consult the +[trust-manager Helm chart docs](https://github.com/cert-manager/trust-manager/blob/main/deploy/charts/trust-manager/README.md#values) +for details and trade-offs. + +#### approver-policy Integration If you're running [approver-policy](../../policy/approval/approver-policy/README.md) then cert-manager's default approver will be disabled which will mean that trust-manager's webhook certificate will - by default - block when you install the Helm chart until it's manually approved.