cert-manager · jetstack-bot · Oct 19, 2021 · Jul 20, 2021 · Aug 4, 2021 · Aug 9, 2021
diff --git a/README.md b/README.md
@@ -106,3 +106,11 @@ This will automatically run a number of checks against your changes.
 If `./scripts/verify` fails with a number of `..target not found..` errors, you
 can run  `./scripts/verify-release` instead, which will fetch all versions of the
 documentation content before running the regular `verify` script.
+
+### Signing Keys
+
+Public keys used for verifying signatures are served on the website statically, and
+are located in `static/public-keys`.
+
+See the [docs on signing keys](./content/en/docs/contributing/signing-keys.md) for
+more information about how and why these keys are generated and provided here.
diff --git a/content/en/docs/concepts/certificate.md b/content/en/docs/concepts/certificate.md
@@ -25,8 +25,8 @@ metadata:
 spec:
   secretName: acme-crt-secret
   dnsNames:
+  - example.com
   - foo.example.com
-  - bar.example.com
   issuerRef:
     name: letsencrypt-prod
     # We can reference ClusterIssuers by changing the kind here.
@@ -36,8 +36,8 @@ spec:
 ```
 
 This `Certificate` will tell cert-manager to attempt to use the `Issuer` named
-`letsencrypt-prod` to obtain a certificate key pair for the `foo.example.com`
-and `bar.example.com` domains. If successful, the resulting TLS key and certificate
+`letsencrypt-prod` to obtain a certificate key pair for the `example.com` and
+`foo.example.com` domains. If successful, the resulting TLS key and certificate
 will be stored in a secret named `acme-crt-secret`, with keys of `tls.key`, and
 `tls.crt` respectively. This secret will live in the same namespace as the
 `Certificate` resource.

diff --git a/content/en/docs/concepts/certificaterequest.md b/content/en/docs/concepts/certificaterequest.md
@@ -27,7 +27,8 @@ spec:
   - signing
   - digital signature
   - server auth
-  duration: 90d
+  # 90 days
+  duration: 2160h
   issuerRef:
     name: ca-issuer
     # We can reference ClusterIssuers by changing the kind here.

diff --git a/content/en/docs/configuration/acme/dns01/acme-dns.md b/content/en/docs/configuration/acme/dns01/acme-dns.md
@@ -150,7 +150,6 @@ stringData:
       },
     }
 ---
-kind: Issuer
 apiVersion: cert-manager.io/v1
 kind: Issuer
 metadata:

diff --git a/content/en/docs/configuration/external.md b/content/en/docs/configuration/external.md
@@ -28,7 +28,7 @@ These external issuers are known to support and honor [approval](https://cert-ma
 - [kms-issuer](https://github.com/Skyscanner/kms-issuer): Requests
   certificates signed using an [AWS KMS](https://aws.amazon.com/kms/) asymmetric key.
 - [aws-privateca-issuer](https://github.com/cert-manager/aws-privateca-issuer): Requests
-  certificates from [AWS Private Certificate Authority] (https://aws.amazon.com/certificate-manager/private-certificate-authority/)
+  certificates from [AWS Private Certificate Authority](https://aws.amazon.com/certificate-manager/private-certificate-authority/)
   for cloud native/hybrid environments.
 - [google-cas-issuer](https://github.com/jetstack/google-cas-issuer): Used
   to request certificates signed by private CAs managed by the

diff --git a/content/en/docs/contributing/building.md b/content/en/docs/contributing/building.md
@@ -8,7 +8,7 @@ type: "docs"
 cert-manager makes use of [Bazel](https://bazel.build/) to build the project. 
 Bazel manages all developer dependencies, Helm chart building, Docker images and the code itself. 
 We try to use it as much as possible.
-We currently use Bazel `v3.7.2`. The minimum supported version is `v3.5.0`.
+We currently use Bazel `v4.2.1`. The minimum supported version is `v4.0.0`.
 
 > **TIP**: are you using GoLand? Make sure to exclude the `bazel-` folders! You can do this by right clicking on the folder -> Mark Directory As -> Excluded
 > This will save you a ton of CPU time!
@@ -101,7 +101,7 @@ $ bazel build //cmd/ctl
 If you need the Docker images you can generate these using:
 ```bash
 $ export APP_VERSION="dev"
-$ export DOCKER_REGISTRY="quay.io/jetstack/"
+$ export DOCKER_REGISTRY="quay.io/jetstack"
 $ bazel run \
 		--stamp \
 		--platforms=@io_bazel_rules_go//go/toolchain:linux_amd64 \

diff --git a/content/en/docs/contributing/e2e.md b/content/en/docs/contributing/e2e.md
@@ -104,3 +104,21 @@ to the X.509 SAN extension.
 
 Each test specifies a used feature using `s.checkFeatures(feature)`, which is then checked against the issuer's
 `UnsupportedFeatures` list. Tests which use a feature unsupported by an issuer are skipped for that issuer.
+
+### Cloud Provider Tests
+
+The master branch of cert-manager can also be tested against different cloud providers. Currently, tests for [EKS](https://aws.amazon.com/eks/) are present which run as a periodic job once every two days.
+
+#### Extending The Cloud Provider Tests
+
+The infrastructure used to run the e2e tests on cloud providers is present in the [cert-manager/test-infra](https://github.com/cert-manager/test-infra) repository. More cloud providers can be added by creating infrastructure for them using [Terraform](https://www.terraform.io/).
+
+Apart from that, tests for the existing infrastructure can be customized by editing their respective prow jobs present in the [Jetstack testing repository](https://github.com/jetstack/testing/tree/master/config/jobs/cert-manager) repository. Values like the cert-manager version or the cloud provider version are present as variables in Terraform so their values can be changed when using `terraform apply` in the prow jobs, for example, for the [EKS prow job](https://github.com/jetstack/testing/blob/master/config/jobs/cert-manager/cert-manager-periodics.yaml#L524) the cert-manager version being tested can be changed using
+
+```
+terraform apply -var="cert_manager_version=v1.3.3" -auto-approve
+```
+
+To see a list of all configurable variables present for a particular infrastructure you can see the `variables.tf` file for that cloud provider's [infrastructure](https://github.com/cert-manager/test-infra).
+
+> Please note that the cloud provider tests run the e2e tests present in the **master** branch of cert-manager on a predefined version of cert-manager (can be changed in the prow job). Currently, they do **not** test code in a PR, but we have an [issue](https://github.com/jetstack/cert-manager/issues/4349) tracking that request.
diff --git a/content/en/docs/contributing/release-process.md b/content/en/docs/contributing/release-process.md
@@ -460,3 +460,9 @@ page if a step is missing or if it is outdated.
        updates to the website configuration. To do this, take inspiration from
        [Maartje's PR
        example](https://github.com/cert-manager/website/pull/309/files).
+
+    5. Ensure that any installation commands in
+       [`cert-manager/website`](https://github.com/cert-manager/website) install
+       the latest version. This should be done after every release, including
+       patch releases as we want to encourage users to always install the latest
+       patch.
diff --git a/content/en/docs/contributing/signing-keys.md b/content/en/docs/contributing/signing-keys.md
@@ -0,0 +1,74 @@
+---
+title: "Signing Keys"
+linkTitle: "Signing Keys"
+weight: 250
+type: "docs"
+---
+
+This page describes the bootstrapping process for a key, including how to do it and why a bootstrapping
+process is required.
+
+## What do we Serve?
+
+To facilitate verification of signatures, we serve public key information from the cert-manager website
+directly. It's important to serve the keys from a different location to where the artifacts are hosted; if the
+keys were hosted at the same location as the artifacts, an attacker able to change the artifacts would be able
+to also change the keys!
+
+We serve several key types under `static/public-keys`:
+
+- `cert-manager-pgp-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.asc`: ASCII-armored PGP public key, used for verifying signatures on helm charts via `helm verify` (after being converted to a keyring)
+- `cert-manager-keyring-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.gpg`: Old style GPG keyring, needed by the `--keyring` parameter to `helm verify`. See Keyring below.
+- `cert-manager-pubkey-2021-09-20.pem`: The raw, PEM-encoded public key used for signing. Cannot be used with GPG (and therefore helm), but should be used for other verification types.
+
+## Background / Architecture
+
+Code signing for cert-manager artifacts is done entirely using cloud KMS keys, to ensure that nobody
+can get access to the private keys in plain-text; all signing operations using the key are therefore
+done through cloud APIs and are logged.
+
+Currently, all keys are on Google KMS, since the rest of cert-manager's release infrastructure is also
+in GCP. The key - and the role bindings which allow access to it - are specified in terraform in a closed
+source Jetstack repo.
+
+## Why Bootstrap?
+
+While the private key is not retrievable for a KMS key, the public key is and _must_ be retrieved so that
+end-users can verify signatures made by the key. In GCP, retrieving the public key is itself an
+[API call](https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.cryptoKeyVersions/getPublicKey)
+which returns the raw key in a PEM encoded format.
+
+That PEM-encoded public key works for some cases (e.g. verifying container signature made using `cosign`) but
+it's not sufficient for Helm chart verification, since Helm chart signing (sadly) requires the use of PGP.
+
+## Bootstrapping a PGP Identity
+
+It's possible to use a shim to use GCP KMS as a PGP key which enables us to avoid having two separate signing keys,
+but PGP public identities are slightly more complicated than plain public keys; they also contain a name,
+creation time, comment and email address to identify the signer. This public "identity" must itself be signed by the
+private key (to prove that the information in the identity is legitimate).
+
+This bootstrapping can be done using the cert-manager release tool, `cmrel`:
+
+```console
+# note that the key name might not exactly match this in the future
+$ cmrel bootstrap-pgp --key "projects/cert-manager-release/locations/europe-west1/keyRings/cert-manager-release/cryptoKeys/cert-manager-release-signing-key/cryptoKeyVersions/1"
+```
+
+This will trigger a cloud build job which will output both the armored PGP identity and the raw PEM public key; the values
+can be copied from the job output.
+
+### GPG Keyring
+
+As an additional UX feature, we can also generate a GPG keyring from the PGP identity, since the keyring is what's required
+by the Helm CLI to actually validate a chart:
+
+```console
+# Example of verifying a chart.
+$ helm verify --keyring cert_manager_keyring_1020CF3C033D4F35BAE1C19E1226061C665DF13E.gpg /path/to/chart.tgz
+Signed by: cert-manager Maintainers <cert-manager-maintainers@googlegroups.com>
+Using Key With Fingerprint: 1020....
+Chart Hash Verified: sha256:bb86...
+```
+
+The keyring can be generated using [this script](https://github.com/cert-manager/release/blob/a219e18b2e64ef078bf73b3641d589b43d1fccb8/hack/helm_keyring.sh).
diff --git a/content/en/docs/faq/kubed.md b/content/en/docs/faq/kubed.md
@@ -18,7 +18,7 @@ Most ingress controllers, including [ingress-nginx](https://kubernetes.github.io
 Sample ingress snippet:
 
 ```
-apiVersion: networking.k8s.io/v1beta1
+apiVersion: networking.k8s.io/v1
 kind: Ingress
 #[...]
 spec:

diff --git a/content/en/docs/installation/_index.md b/content/en/docs/installation/_index.md
@@ -15,15 +15,15 @@ install methods are listed below for each of the situations.
 
 The default static configuration can be installed as follows:
 ```bash
-$ kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml
+$ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.4/cert-manager.yaml
 ```
 More information on this install method [can be found here](./kubectl/).
 
 ## Getting started
 
 > You quickly want to learn how to use cert-manager and what it can be used for.
 
-We recommend [kubectl cert-manager x install](./kubectl-plugin/) to quickly install cert-manager and [interact with cert-manager resources](../usage/kubectl-plugin/) from the command line. 
+We recommend [kubectl cert-manager x install](./kubectl-plugin/) to quickly install cert-manager and [interact with cert-manager resources](../usage/kubectl-plugin/) from the command line.
 
 Or if you prefer Helm or if you don't want to install the `kubectl cert-manager` plugin, you can [use helm to install cert-manager](./helm/).
 

diff --git a/content/en/docs/installation/code-signing.md b/content/en/docs/installation/code-signing.md
@@ -0,0 +1,53 @@
+---
+title: "cert-manager Signature Verification"
+linkTitle: "Signature Verification"
+weight: 5000
+type: "docs"
+---
+
+To help prevent [supply chain attacks](https://en.wikipedia.org/wiki/Supply_chain_attack), some cert-manager release
+artifacts are cryptographically signed so you can be sure that the version of cert-manager you're about to install
+is actually built by and provided by the cert-manager maintainers.
+
+This signing is vitally important if for any reason you need to use a mirrored version of cert-manager; it allows you
+to confirm that the mirror hasn't tampered with the code you're about to install.
+
+Signing keys required for verification are all available on this website, but the actual key that you need might depend
+on the artifact you're trying to validate in the future. At the time of writing, all signing is done using the same underlying
+key.
+
+## Container Images / Cosign
+
+For all cert-manager versions from `v1.6.0` and later, container images are verifiable using [`cosign`](https://docs.sigstore.dev/cosign/overview).
+
+The simplest way to verify signatures is to download the public key and then pass it to the cosign CLI:
+
+```console
+curl -sSL https://cert-manager.io/public-keys/cert-manager-pubkey-2021-09-20.pem > cert-manager-pubkey-2021-09-20.pem
+cosign verify -key cert-manager-pubkey-2021-09-20.pem quay.io/jetstack/cert-manager-controller
+# repeat for other images as desired
+```
+
+For a more fully-featured signature verification process in Kubernetes, check out [`connaisseur`](https://sse-secure-systems.github.io/connaisseur/).
+
+- PEM-encoded public key: [`cert-manager-pubkey-2021-09-20.pem`](/public-keys/cert-manager-pubkey-2021-09-20.pem)
+
+## Helm Charts
+
+{{% alert title="Warning" color="warning" %}}
+Helm requires the use of PGP for verification; the key format is different.
+
+Trying to use the PEM encoded public keys above will fail.
+{{% /alert %}}
+
+For all cert-manager versions from `v1.6.0` and later, helm charts are signed and verifiable through the helm CLI.
+
+The easiest way to verify is to grab the GPG keyring directly, which can then be passed into `helm verify` like so:
+
+```console
+curl -sSL https://cert-manager.io/public-keys/cert-manager-keyring-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.gpg > cert-manager-keyring-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.gpg
+helm verify --keyring cert-manager-keyring-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.gpg /path/to/cert-manager-vx.y.z.tgz
+```
+
+- ASCII-armored signing key: [`cert-manager-pgp-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.asc`](/public-keys/cert-manager-pgp-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.asc)
+- GPG keyring: [`cert-manager-keyring-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.gpg`](/public-keys/cert-manager-keyring-2021-09-20-1020CF3C033D4F35BAE1C19E1226061C665DF13E.gpg)
diff --git a/content/en/docs/installation/compatibility.md b/content/en/docs/installation/compatibility.md
@@ -46,17 +46,16 @@ You can read more information on how to add firewall rules for the GKE control
 plane nodes in the [GKE
 docs](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules).
 
-## GKE Autopilot
 
-As of May 2021, GKE Autopilot has no support for 3rd party webhooks.
-Without webhooks, many Kubernetes plugins such as cert-manager cannot
-operate correctly.
+### GKE Autopilot
 
-As per [this
-tweet](https://twitter.com/BagadeVivek/status/1365701217469534220), GKE
-Autopilot is meant to support webhooks in a coming release. We will keep
-you updated on the progress on [this
-issue](https://github.com/jetstack/cert-manager/issues/3717).
+GKE Autopilot mode with Kubernetes < 1.21 does not support cert-manager,
+due to a [restriction on mutating admission webhooks](https://github.com/jetstack/cert-manager/issues/3717).
+
+As of October 2021, only the "rapid" Autopilot release channel has rolled
+out version 1.21 for Kubernetes masters. Installation via the helm chart
+may end in an error message but cert-manager is reported to be working by
+some users. Feedback and PRs are welcome.
 
 ## AWS EKS
 
@@ -74,9 +73,13 @@ port; see the warning at the top of the page for details.
 
 ### AWS Fargate
 
-It's worth noting that using AWS Fargate to run cert-manager will force you to
-run using the host's network, and will force a port clash with the kubelet
-running on port 10250, as seen in [#3237](https://github.com/jetstack/cert-manager/issues/3237).
+It's worth noting that using AWS Fargate doesn't allow much network configuration and
+will cause the webhook's port to clash with the kubelet running on port 10250, as seen
+in [#3237](https://github.com/jetstack/cert-manager/issues/3237).
 
 When deploying cert-manager on Fargate, you _must_ change the port on which
 the webhook listens. See the warning at the top of this page for more details.
+
+Because Fargate forces you to use its networking, you cannot manually set the networking
+type and options such as `webhook.hostNetwork` on the helm chart will cause your
+cert-manager deployment to fail in surprising ways.
diff --git a/content/en/docs/installation/helm.md b/content/en/docs/installation/helm.md
@@ -46,7 +46,7 @@ or using the `installCRDs` option when installing the Helm chart.
 
 
 ```bash
-$ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.0/cert-manager.crds.yaml
+$ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.4/cert-manager.crds.yaml
 ```
 
 ##### Option 2: install CRDs as part of the Helm release
@@ -67,7 +67,7 @@ $ helm install \
   cert-manager jetstack/cert-manager \
   --namespace cert-manager \
   --create-namespace \
-  --version v1.5.0 \
+  --version v1.5.4 \
   # --set installCRDs=true
 ```
 
@@ -80,7 +80,7 @@ $ helm install \
   cert-manager jetstack/cert-manager \
   --namespace cert-manager \
   --create-namespace \
-  --version v1.5.0 \
+  --version v1.5.4 \
   --set prometheus.enabled=false \  # Example: disabling prometheus using a Helm parameter
   --set webhook.timeoutSeconds=4s   # Example: changing the wehbook timeout using a Helm parameter
 ```
@@ -97,7 +97,7 @@ $ helm template \
   cert-manager jetstack/cert-manager \
   --namespace cert-manager \
   --create-namespace \
-  --version v1.5.0 \
+  --version v1.5.4 \
   # --set prometheus.enabled=false \   # Example: disabling prometheus using a Helm parameter
   # --set installCRDs=true \           # Uncomment to also template CRDs
   > cert-manager.custom.yaml

diff --git a/content/en/docs/installation/kubectl.md b/content/en/docs/installation/kubectl.md
@@ -21,7 +21,7 @@ are included in a single YAML manifest file:
 Install all cert-manager components:
 
 ```bash
-$ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.0/cert-manager.yaml
+$ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.4/cert-manager.yaml
 ```
 
 By default, cert-manager will be installed into the `cert-manager`

diff --git a/content/en/docs/installation/operator-lifecycle-manager.md b/content/en/docs/installation/operator-lifecycle-manager.md
@@ -69,7 +69,7 @@ spec:
   name: cert-manager
 ...
 status:
-  currentCSV: cert-manager.v1.5.0
+  currentCSV: cert-manager.v1.5.4
   state: AtLatestKnown
 ...
 ```

diff --git a/content/en/docs/installation/supported-releases.md b/content/en/docs/installation/supported-releases.md
@@ -93,7 +93,7 @@ branch is actually supported.
        \                                                           v
         \
          \       v1.1.0
-          \    Nov 24, 2021                                        ^
+          \    Nov 24, 2020                                        ^
            ---------+-------------------------------> release-1.1  |
                      \                                             | SUPPORTED
                       \                                            | RELEASES
@@ -185,7 +185,7 @@ Our testing coverage is:
 
 | Release branch | Prow configuration            | Dashboard                 | Kubernetes versions tested  |  Periodicity  |
 | :------------: | :---------------------------- | :------------------------ | :-------------------------: | :-----------: |
-|      PRs       | [`presubmits.yaml`][]         | [`presubmits-blocking`][] |         1.21, 1.22          |  On each PR   |
+|      PRs       | [`presubmits.yaml`][]         | [`presubmits-blocking`][] |            1.22             |  On each PR   |
 |     master     | [`periodics.yaml`][]          | [`master`][]              |         1.16 → 1.22         | Every 2 hours |
 |  release-1.6   | [`next-periodics.yaml`][]     | [`next`][]                |         1.16 → 1.22         | Every 2 hours |
 |  release-1.5   | [`previous-periodics.yaml`][] | [`previous`][]            |         1.16 → 1.22         | Every 2 hours |