Merge pull request #1523 from SgtCoDFish/doc-new-releases

Document new releases of istio-csr and trust-manager

content/docs/reference/api-docs.md

@@ -6787,5 +6787,5 @@ description: >-
 </table>
 <hr />
 <p>
-  <em> Generated with <code>gen-crd-api-reference-docs</code> on git commit <code>3403251</code>. </em>
+  <em> Generated with <code>gen-crd-api-reference-docs</code> on git commit <code>35e27b7</code>. </em>
 </p>

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,13 +32,24 @@ 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 \
   --namespace cert-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
 
+<a name="approver-policy-integration"></a>
+
 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
+
+<a name="install-without-cert-manager"></a>
+
+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:

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).

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"