diff --git a/content/docs/reference/api-docs.md b/content/docs/reference/api-docs.md
index 67da9cc630c..eb030dfcc2a 100644
--- a/content/docs/reference/api-docs.md
+++ b/content/docs/reference/api-docs.md
@@ -6787,5 +6787,5 @@ description: >-
- Generated with gen-crd-api-reference-docs on git commit 3403251.
+ Generated with gen-crd-api-reference-docs on git commit 35e27b7.
diff --git a/content/docs/trust/trust-manager/installation.md b/content/docs/trust/trust-manager/installation.md
index 156416e6af3..1657dd0bf5a 100644
--- a/content/docs/trust/trust-manager/installation.md
+++ b/content/docs/trust/trust-manager/installation.md
@@ -5,7 +5,7 @@ description: 'Installation guide for trust-manager'
## Installation Steps
-### 1. Install trust-manager
+### 1. Update Helm Repository
Helm is the easiest way to install trust-manager and comes with a publicly trusted certificate bundle package
(for the`useDefaultCAs` source) derived from Debian containers.
@@ -14,9 +14,14 @@ Helm is the easiest way to install trust-manager and comes with a publicly trust
helm repo add jetstack https://charts.jetstack.io --force-update
```
-When installed via Helm, trust-manager has a dependency on cert-manager for provisioning an application certificate,
-and as such cert-manager must also be installed into the cert-manager namespace.
-If you have not already installed cert-manager, you can install it using the following command:
+### 2. Install cert-manager (optional)
+
+When installed via Helm, trust-manager has a dependency on cert-manager for provisioning an application certificate
+unless you explicitly opt to use a Helm-generated certificate instead.
+
+In production, we recommend installing cert-manager first and having trust-manager depend on it.
+
+If you haven't already installed cert-manager, you can install it using the following command:
```bash
# Run this command only if you haven't installed cert-manager already
@@ -27,6 +32,15 @@ helm install cert-manager jetstack/cert-manager \
--set crds.enabled=true
```
+If you're running cert-manager without the default approver, see [approver-policy Integration](#approver-policy-integration)
+for details on how to avoid a stuck installation.
+
+If you don't want to rely on cert-manager, you can install using a Helm-generated cert; see [Installing trust-manager without cert-manager](./installation.md#install-without-cert-manager).
+
+### 3. Install trust-manager
+
+trust-manager is simple to install and is contained in a single Helm chart:
+
```bash
helm upgrade trust-manager jetstack/trust-manager \
--install \
@@ -34,6 +48,8 @@ helm upgrade trust-manager jetstack/trust-manager \
--wait
```
+Various options are available, and some are documented below.
+
## Installation Options
#### Enable Secret targets
@@ -47,6 +63,8 @@ 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.
@@ -79,6 +97,27 @@ namespace to whichever is most appropriate for your environment.
An ideal deployment would be a fresh namespace dedicated entirely to trust-manager, to minimize the number of actors in your
cluster that can modify your trust sources.
+#### Installing trust-manager without cert-manager
+
+
+
+As an alternative to generating a webhook certificate using cert-manager, it's possible to opt to use Helm to generate the webhook certificate instead.
+
+This isn't recommended for production, since Helm-generated certificates might be complicated to monitor or to reason about. The certificate is also rotated
+every time trust-manager is upgraded, which necessitates pod restarts and may complicate the upgrade process.
+
+Installing without cert-manager can be great for smaller, more resource-constrained deployments such as experiments, demos or home labs.
+
+Using a Helm-generated cert requires a single flag:
+
+```bash
+helm upgrade trust-manager jetstack/trust-manager \
+ --install \
+ --namespace cert-manager \
+ --wait \
+ --set app.webhook.tls.helmCert.enabled=true
+```
+
## Uninstalling
To uninstall trust-manager installed via Helm, run:
diff --git a/content/docs/usage/istio-csr/installation.md b/content/docs/usage/istio-csr/installation.md
index 8713770191b..42a2f733989 100644
--- a/content/docs/usage/istio-csr/installation.md
+++ b/content/docs/usage/istio-csr/installation.md
@@ -9,6 +9,18 @@ This guide will run through installing and using istio-csr from scratch. We'll u
Note that if you're following the Platform Setup guide for OpenShift, do not run the `istioctl install` command listed in that guide; we'll run our own command later.
+### 0. Background
+
+istio-csr uses cert-manager to issue Istio certificates, and needs to be able to reference an issuer resource to do this.
+
+You can choose to configure a an issuer when installing with the Helm chart, or to configure a ConfigMap to watch which can then be used to configure an issuer at runtime.
+
+If you configure an issuer in the chart, you'll be able to start issuing as soon as the istio-csr pods come online but you'll need to have already installed cert-manager and created the issuer.
+
+If you don't set an issuer in the chart, istio-csr will be unable to issue until an issuer is specified via runtime configuration, but you'll be able to install cert-manager and istio-csr concurrently.
+
+Note that the chart contains a default issuer name and so using runtime configuration requires an explicit opt-in. The guide below assumes you'll install istio-csr after an issuer is configured. A future release of istio-csr will improve runtime configuration support and a guide will be added for runtime-configured installation along with that release. Until then, there are some notes at the bottom of this page.
+
### 1. Initial Setup
You'll need the following tools installed on your machine:
@@ -278,6 +290,89 @@ Assuming your running inside kind, you can simply remove the cluster:
kind delete cluster
```
+## Installation with Runtime Configuration
+
+There are two options for installing with runtime configuration:
+
+1. Install after cert-manager and pass an explicit `issuerRef` in the Helm chart
+2. Blank out the `issuerRef` in the Helm chart and use pure runtime configuration
+
+Both options will require a ConfigMap to be created to point at an issuer. This ConfigMap can be created
+before or after installation, and must be created in the same namespace as the istio-csr pods.
+
+### Creating the ConfigMap
+
+Three keys are required, specifying the issuer name, kind and group. Any method of creating a ConfigMap will work. For example:
+
+```bash
+kubectl create configmap -n cert-manager istio-issuer \
+ --from-literal=issuer-name=my-issuer-name \
+ --from-literal=issuer-kind=ClusterIssuer \
+ --from-literal=issuer-group=cert-manager.io
+```
+
+### Option 1: Installation after cert-manager
+
+If cert-manager is already installed, you can use the same `helm upgrade` command as above but also specifying the name of the runtime configuration ConfigMap:
+
+```bash
+helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+ --install \
+ --namespace cert-manager \
+ --wait \
+ ...
+ --set "app.runtimeIssuanceConfigMap=istio-issuer"
+```
+
+In this scenario, the issuer defined in `app.certmanager.issuer` will be used at startup and to create the `istiod` certificate.
+
+When istio-csr detects the runtime ConfigMap, it'll use the issuer configured there. If the ConfigMap is updated, istio-csr will respect the update dynamically.
+
+If the runtime ConfigMap is deleted, istio-csr will revert to using the value from `app.certmanager.issuer`.
+
+### Option 2: Pure Runtime Configuration
+
+Pure runtime configuration requires more values to be set:
+
+1. The `app.certmanager.issuer` values must be blanked out (as they're set to a default value in the chart)
+2. `istiod` certificate generation must be disabled. A future update to istio-csr will remove this requirement.
+3. The `istiod` certificate must be manually created before installing Istio, with DNS names corresponding to the required services. [This cert-manager Certificate](https://github.com/cert-manager/istio-csr/blob/v0.10.0/deploy/charts/istio-csr/templates/certificate.yaml) may help. A future update to istio-csr will remove this requirement,.
+4. The `app.runtimeIssuanceConfigMap` must be set.
+
+An example `values.yaml` file for pure runtime configuration is as follows:
+
+```yaml
+app:
+ runtimeIssuanceConfigMap: istio-issuer
+ certmanager:
+ issuer:
+ name: "" # explicitly blanked out
+ kind: "" # explicitly blanked out
+ group: "" # explicitly blanked out
+ tls:
+ rootCAFile: "/var/run/secrets/istio-csr/ca.pem"
+ istiodCertificateEnable: false # will not be required in a future release
+volumeMounts:
+- name: root-ca
+ mountPath: /var/run/secrets/istio-csr
+volumes:
+- name: root-ca
+ secret:
+ secretName: istio-root-ca
+```
+
+This file could then be used with the following command:
+
+```bash
+helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+ --install \
+ --namespace cert-manager \
+ --wait \
+ --values values.yaml
+```
+
+We don't recommend using pure runtime configuration until a future release adds support for dynamic `istiod` certificate generation.
+
## Usage
> 📖 Read the [istio-csr docs](./README.md).
diff --git a/scripts/gendocs/generate-trust-manager b/scripts/gendocs/generate-trust-manager
index 4cbc11d9f6a..d4102a8d416 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.10.1"
+checkout "v0.12.0"
gendocs "$REPO_ROOT/content/docs/trust/trust-manager/api-reference.md"