Skip to content

Commit

Permalink
Add/update docs for new trust-manager features
Browse files Browse the repository at this point in the history 
Co-authored-by: Ashley Davis <SgtCoDFish@users.noreply.github.com>
Signed-off-by: Erik Godding Boye <egboye@gmail.com>
  • Loading branch information
@erikgb @SgtCoDFish
erikgb and SgtCoDFish committed Nov 30, 2023
1 parent 2c72ba0 commit a3dac03
Show file tree
Hide file tree
Showing 4 changed files with 159 additions and 12 deletions.
2 changes: 2 additions & 0 deletions .spelling
View file
Original file line number Diff line number Diff line change
Expand Up @@ -458,6 +458,8 @@ upstream
userinfo
vhosakot
v0.5.0
v0.7.0
v0.7.0.
v0.16
v0.23.1
v1
Expand Down
39 changes: 28 additions & 11 deletions content/docs/trust/trust-manager/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"
Expand All @@ -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

Expand Down Expand Up @@ -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.
Expand Down
128 changes: 128 additions & 0 deletions content/docs/trust/trust-manager/api-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.<br/>
</td>
<td>false</td>
</tr><tr>
<td><b><a href="#bundlespectargetsecret">secret</a></b></td>
<td>object</td>
<td>
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.<br/>
</td>
<td>false</td>
</tr></tbody>
</table>

Expand All @@ -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".<br/>
</td>
<td>false</td>
</tr><tr>
<td><b><a href="#bundlespectargetadditionalformatspkcs12">pkcs12</a></b></td>
<td>object</td>
<td>
PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password.<br/>
</td>
<td>false</td>
</tr></tbody>
</table>

Expand Down Expand Up @@ -300,6 +314,31 @@ JKS requests a JKS-formatted binary trust bundle to be written to the target. Th
</table>


### `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.

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody><tr>
<td><b>key</b></td>
<td>string</td>
<td>
Key is the key of the entry in the object's `data` field to be used.<br/>
</td>
<td>true</td>
</tr></tbody>
</table>


### `Bundle.spec.target.configMap`


Expand Down Expand Up @@ -350,6 +389,31 @@ NamespaceSelector will, if set, only sync the target resource in Namespaces whic
</table>


### `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.

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody><tr>
<td><b>key</b></td>
<td>string</td>
<td>
Key is the key of the entry in the object's `data` field to be used.<br/>
</td>
<td>true</td>
</tr></tbody>
</table>


### `Bundle.status`


Expand Down Expand Up @@ -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.<br/>
</td>
<td>false</td>
</tr><tr>
<td><b><a href="#bundlestatustargetsecret">secret</a></b></td>
<td>object</td>
<td>
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.<br/>
</td>
<td>false</td>
</tr></tbody>
</table>

Expand All @@ -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".<br/>
</td>
<td>false</td>
</tr><tr>
<td><b><a href="#bundlestatustargetadditionalformatspkcs12">pkcs12</a></b></td>
<td>object</td>
<td>
PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password.<br/>
</td>
<td>false</td>
</tr></tbody>
</table>

Expand Down Expand Up @@ -542,6 +620,31 @@ JKS requests a JKS-formatted binary trust bundle to be written to the target. Th
</table>


### `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.

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody><tr>
<td><b>key</b></td>
<td>string</td>
<td>
Key is the key of the entry in the object's `data` field to be used.<br/>
</td>
<td>true</td>
</tr></tbody>
</table>


### `Bundle.status.target.configMap`


Expand Down Expand Up @@ -590,3 +693,28 @@ NamespaceSelector will, if set, only sync the target resource in Namespaces whic
<td>false</td>
</tr></tbody>
</table>


### `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.

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody><tr>
<td><b>key</b></td>
<td>string</td>
<td>
Key is the key of the entry in the object's `data` field to be used.<br/>
</td>
<td>true</td>
</tr></tbody>
</table>
2 changes: 1 addition & 1 deletion scripts/gendocs/generate-trust-manager
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"

0 comments on commit a3dac03

Please sign in to comment.