From e564f8333fdc90418ae4704ef9337ca737205a75 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 Co-authored-by: Ashley Davis Signed-off-by: Erik Godding Boye --- .spelling | 4 + content/docs/trust/trust-manager/README.md | 39 ++++-- .../docs/trust/trust-manager/api-reference.md | 128 ++++++++++++++++++ scripts/gendocs/generate-trust-manager | 2 +- 4 files changed, 161 insertions(+), 12 deletions(-) diff --git a/.spelling b/.spelling index 15673739a42..320d2720756 100644 --- a/.spelling +++ b/.spelling @@ -214,6 +214,7 @@ OpenWRT OperatorHub OperatorHub.io PEM +PKCS12-formatted PKCS#12 PKCS#8 Pomerium @@ -402,6 +403,7 @@ ndegory oauth2 onwards openshift-supported-versions +plaintext powershell pre preemptible @@ -458,6 +460,8 @@ upstream userinfo vhosakot v0.5.0 +v0.7.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..3b88dd1957b 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,23 @@ 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`. +Applications consuming JKS and PKCS#12 trust stores often require a password to be set for legacy reasons. These passwords are often security theater - either they use very weak encryption or the passwords are provided in plaintext next to the files they encrypt which defeats the purpose of having them. + +Trust bundles do not contain private keys, and so for most use cases there wouldn't be any security benefit to encrypting them. As such, passwords for trust stores are hard-coded to `changeit` for JKS and `""` (the empty string or "password-less") for PKCS#12. Future releases of trust-manager may make these passwords configurable. #### Namespace Selector @@ -132,7 +140,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 need 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 read and update 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. diff --git a/content/docs/trust/trust-manager/api-reference.md b/content/docs/trust/trust-manager/api-reference.md index da09c7c0395..d0448f061fd 100644 --- a/content/docs/trust/trust-manager/api-reference.md +++ b/content/docs/trust/trust-manager/api-reference.md @@ -246,6 +246,13 @@ Target is the target location in all namespaces to sync source data to. NamespaceSelector will, if set, only sync the target resource in Namespaces which match the selector.
false + + secret + object + + Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace.
+ + false @@ -271,6 +278,13 @@ AdditionalFormats specifies any additional formats to write to the target JKS requests a JKS-formatted binary trust bundle to be written to the target. The bundle is created with the hardcoded password "changeit".
false + + pkcs12 + object + + PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password.
+ + false @@ -300,6 +314,31 @@ JKS requests a JKS-formatted binary trust bundle to be written to the target. Th +### `Bundle.spec.target.additionalFormats.pkcs12` + + +PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password. + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + Key is the key of the entry in the object's `data` field to be used.
+ 		true
+ + ### `Bundle.spec.target.configMap` @@ -350,6 +389,31 @@ NamespaceSelector will, if set, only sync the target resource in Namespaces whic +### `Bundle.spec.target.secret` + + +Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace. + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + Key is the key of the entry in the object's `data` field to be used.
+ 		true
+ + ### `Bundle.status` @@ -488,6 +552,13 @@ Target is the current Target that the Bundle is attempting or has completed sync NamespaceSelector will, if set, only sync the target resource in Namespaces which match the selector.
false + + secret + object + + Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace.
+ + false @@ -513,6 +584,13 @@ AdditionalFormats specifies any additional formats to write to the target JKS requests a JKS-formatted binary trust bundle to be written to the target. The bundle is created with the hardcoded password "changeit".
false + + pkcs12 + object + + PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password.
+ + false @@ -542,6 +620,31 @@ JKS requests a JKS-formatted binary trust bundle to be written to the target. Th +### `Bundle.status.target.additionalFormats.pkcs12` + + +PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password. + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + Key is the key of the entry in the object's `data` field to be used.
+ 		true
+ + ### `Bundle.status.target.configMap` @@ -590,3 +693,28 @@ NamespaceSelector will, if set, only sync the target resource in Namespaces whic false + + +### `Bundle.status.target.secret` + + +Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace. + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + Key is the key of the entry in the object's `data` field to be used.
+ 		true
diff --git a/scripts/gendocs/generate-trust-manager b/scripts/gendocs/generate-trust-manager index e4ee7cbb40b..3125d37aba0 100755 --- a/scripts/gendocs/generate-trust-manager +++ b/scripts/gendocs/generate-trust-manager @@ -59,6 +59,6 @@ gendocs() { echo "+++ Cloning trust-manager repository..." git clone "https://github.com/cert-manager/trust-manager.git" "$tmpdir" -checkout "v0.6.0" +checkout "v0.7.0" gendocs "$REPO_ROOT/content/docs/trust/trust-manager/api-reference.md"