[Post-Release] Merge release-next into master

.spelling

@@ -475,13 +475,15 @@ v1.8.2
 v1.9.0
 v1.9.1
 v1.10
+v1.11.0
+v1.12.0
 v1alpha1
 v1alpha2
 v1alpha3
 v1beta1
 v2
 v3
-vCert
+VCert
 vendoring
 vendored
 versioning
@@ -553,6 +555,38 @@ NetworkPolicy
 mjudeikis
 rgl
 1password
+secretless
+TokenRequest
+v1.12.0
+v1.12.0.
+PodDisruptionBudgets
+andrewsomething
+avi-08
+e96wic
+ExNG
+g-gaston
+jkroepke
+malovme
+maumontesilva
+tobotg
+TrilokGeer
+waterfoul
+yulng
+vidarno
+vinzent
+dsonck92
+go.work
+go.mod
+validatingwebhookconfigurations
+mutatingwebhookconfigurations
+customresourcedefinitions
+unlabelled
+v1.27.1
+v0.6.0.
+v4.4.1
+liveness
+apiservices
+arm64
 
 # TEMPORARY
 # these are temporarily ignored because the spellchecker

content/docs/configuration/acme/README.md

@@ -65,7 +65,7 @@ spec:
     solvers:
     - http01:
         ingress:
-          class: nginx
+          ingressClassName: nginx
 ```
 
 Solvers come in the form of [`dns01`](./dns01/README.md) and
@@ -123,8 +123,9 @@ spec:
     solvers:
     - http01:
         ingress:
-          class: nginx
+          ingressClassName: nginx
 ```
+
 > Note: cert-manager versions pre-`v1.3.0` also required users to specify the
 > MAC algorithm for EAB by setting
 > `Issuer.spec.acme.externalAccountBinding.keyAlgorithm` field. This field is
@@ -296,7 +297,7 @@ spec:
     solvers:
     - http01:
         ingress:
-          class: nginx
+          ingressClassName: nginx
       selector:
         matchLabels:
           "use-http01-solver": "true"

content/docs/configuration/acme/http01/README.md

@@ -43,7 +43,7 @@ spec:
     solvers:
     - http01:
         ingress:
-          class: nginx
+          ingressClassName: nginx
 ```
 
 ## Options
@@ -52,18 +52,32 @@ The HTTP01 Issuer supports a number of additional options.  For full details on
 the range of options available, read the [reference
 documentation](../../../reference/api-docs.md#acme.cert-manager.io/v1.ACMEChallengeSolverHTTP01).
 
-### `class`
+### `ingressClassName`
+
+<div className="info">
 
-If the `class` field is specified, cert-manager will create new `Ingress`
-resources in order to route traffic to the `acmesolver` pods, which are
-responsible for responding to ACME challenge validation requests.
+📌 The field `ingressClassName` was added in cert-manager 1.12.
 
-If this field is not specified, and `name` is also not specified,
-cert-manager will default to create *new* `Ingress` resources but will **not**
-set the ingress class on these resources, meaning *all* ingress controllers
-installed in your cluster will serve traffic for the challenge solver,
-potentially incurring additional cost.
+</div>
 
+If the `ingressClassName` field is specified, cert-manager will create new
+`Ingress` resources in order to route traffic to the `acmesolver` pods, which
+are responsible for responding to ACME challenge validation requests.
+
+This is the recommended way of configuring the Ingress controller. Most Ingress
+controllers support `ingressClassName`, with the notable exception of
+ingress-gce (as per the page [Configure Ingress for external load
+balancing](https://cloud.google.com/kubernetes-engine/docs/how-to/load-balance-ingress)).
+
+### `class`
+
+If the `class` field is specified, a new Ingress resource with a randomly
+generated name will be created in order to solve the challenge. This new
+resource will have an annotation with key `kubernetes.io/ingress.class` and
+value set to the value of the `class` field.
+
+This field is only recommended with ingress-gce. ingress-gce [doesn't support the
+`ingressClassName` field](https://cloud.google.com/kubernetes-engine/docs/how-to/load-balance-ingress).
 
 ### `name`
 
@@ -77,6 +91,16 @@ This mode should be avoided when using ingress controllers that expose a single
 IP for all ingress resources, as it can create compatibility problems with
 certain ingress-controller specific annotations.
 
+<div className="warning">
+
+If `class` and `ingressClassName` are not specified, and `name` is also not
+specified, cert-manager will default to create *new* `Ingress` resources but
+will **not** set the ingress class on these resources, meaning *all* ingress
+controllers installed in your cluster will serve traffic for the challenge
+solver, potentially incurring additional cost.
+
+</div>
+
 <h3 id="ingress-service-type">`serviceType`</h3>
 
 In rare cases it might be not possible/desired to use `NodePort` as type for the

content/docs/configuration/vault.md

@@ -144,13 +144,125 @@ spec:
           key: token
 ```
 
+<a id="authenticating-with-kubernetes-service-accounts"></a>
+
 ### Authenticating with Kubernetes Service Accounts
 
-Vault can be configured so that applications can authenticate using Kubernetes
-[`Service Account
-Tokens`](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin).
-You find documentation on how to configure Vault to authenticate using Service
-Account Tokens [here](https://www.vaultproject.io/docs/auth/kubernetes.html).
+The [Vault Kubernetes
+Auth](https://developer.hashicorp.com/vault/docs/auth/kubernetes) allows
+cert-manager to authenticate to Vault using a Kubernetes Service Account Token
+in order to issue certificates using Vault as a certification authority. The
+Kubernetes service account token can be provided in two ways:
+
+- [Secretless Authentication with a Service Account](#secretless-authentication-with-a-service-account) (recommended),
+- [Authentication with a Static Service Account Token](#static-service-account-token).
+
+#### Secretless Authentication with a Service Account
+
+ℹ️ This feature is available in cert-manager >= v1.12.0.
+
+With the secretless authentication with a service account, cert-manager creates
+an ephemeral service account token using the TokenRequest API and uses it to
+authenticate with Vault. These tokens are short-lived (10 minutes) and are
+never stored to disk.
+
+This is the recommended authentication method because it does not rely on the
+deprecated static service account tokens. The static service account tokens pose
+a threat due to their infinite lifetime. Static service account tokens have been
+disabled by default on Kubernetes 1.24.
+
+The first step is to create a `ServiceAccount` resource:
+
+```sh
+kubectl create serviceaccount -n sandbox vault-issuer
+```
+
+Then add an RBAC Role so that cert-manager can get tokens for the
+ServiceAccount:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: vault-issuer
+  namespace: sandbox
+rules:
+  - apiGroups: ['']
+    resources: ['serviceaccounts/token']
+    resourceNames: ['vault-issuer']
+    verbs: ['create']
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: vault-issuer
+  namespace: sandbox
+subjects:
+  - kind: ServiceAccount
+    name: cert-manager
+    namespace: cert-manager
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: vault-issuer
+```
+
+Finally, create the Issuer resource:
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: vault-issuer
+  namespace: sandbox
+spec:
+  vault:
+    path: pki_int/sign/example-dot-com
+    server: https://vault.local
+    auth:
+      kubernetes:
+        role: my-app-1
+        mountPath: /v1/auth/kubernetes
+        serviceAccountRef:
+          name: vault-issuer
+```
+
+> **Issuer vs. ClusterIssuer:** With an Issuer resource, you can only refer to a
+> service account located in the same namespace as the Issuer. With a
+> ClusterIssuer, the service account must be located in the namespace that is
+> configured by the flag `--cluster-resource-namespace`.
+
+To create the role in Vault, you can use the following command:
+
+```bash
+vault write auth/kubernetes/role/vault-issuer \
+    bound_service_account_names=vault-issuer \
+    bound_service_account_namespaces=sandbox \
+    audience="vault://sandbox/vault-issuer" \
+    policies=vault-issuer \
+    ttl=1m
+```
+
+It is recommended to use a different Vault role each per Issuer or
+ClusterIssuer. The `audience` allows you to restrict the Vault role to a single
+Issuer or ClusterIssuer. The syntax is the following:
+
+```yaml
+"vault://<namespace>/<issuer-name>"   # For an Issuer.
+"vault://<cluster-issuer-name>"       # For a ClusterIssuer.
+```
+
+The expiration duration for the Kubernetes tokens that are requested is
+hard-coded to 10 minutes (that's the minimum accepted). The `ttl` field can be
+as short as possible, since cert-manager requests a new token every time it
+needs to talks to Vault.
+
+Although it is not recommended, you can also use the same Vault role for all of
+your Issuers and ClusterIssuers by omitting the `audience` field and re-using
+the same service account.
+<a name="static-service-account-token"></a>
+
+#### Authentication with a Static Service Account Token
 
 For the Vault issuer to use this authentication, cert-manager must get access to
 the token that is stored in a Kubernetes `Secret`. Kubernetes Service Account

content/docs/installation/upgrading/ingress-class-compatibility.md

@@ -1,12 +1,21 @@
 ---
-title: Notes on Ingress Class Compatibility
+title: Notes on the breaking change with the `class` field that happened in cert-manager v1.5.4
 description: 'cert-manager installation: Notes on ingress classes and safe upgrades'
 ---
 
-In cert-manager v1.5.4 we made a change to the HTTP-01 code which was not backwards compatible.
-See [Regression: HTTP-01 challenges fail with Istio, Traefik, ingress-gce and Azure AGIC].
 
-[Regression: HTTP-01 challenges fail with Istio, Traefik, ingress-gce and Azure AGIC]: https://github.com/cert-manager/cert-manager/issues/4537
+> ⚠️ This document focuses on the `class` field of the Issuer and ClusterIssuer
+> resources and the annotation `kubernetes.io/ingress.class`. If you are
+> interested in using `ingressClassName` on your Ingress resources when using
+> cert-manager's HTTP-01 solver, see the page [Securing Ingress
+> Resources](../../configuration/acme/http01#ingressclassname).
+
+In cert-manager v1.5.4 we made a change to the HTTP-01 code which was not
+backwards compatible. Before v1.5.4, cert-manager was using the `class` field on
+the Issuer and ClusterIssuer to add the annotation
+`kubernetes.io/ingress.class`. In cert-manager v1.5.4, cert-manager stopped
+setting the annotation. See [Regression: HTTP-01 challenges fail with Istio,
+Traefik, ingress-gce and Azure AGIC].
 
 In v1.5.5, v1.6.2 and 1.7.1 we fixed this problem.
 
@@ -18,6 +27,8 @@ If you have cert-manager v1.5.3 (or below) you should skip v1.5.4 and instead:
 
 and you can ignore the rest of this document.
 
+[Regression: HTTP-01 challenges fail with Istio, Traefik, ingress-gce and Azure AGIC]: https://github.com/cert-manager/cert-manager/issues/4537
+
 The following notes apply to anyone upgrading from cert-manager v1.5.4, v1.6.0, v1.6.1 on Kubernetes v1.19 or later.
 
 # Background
@@ -49,9 +60,9 @@ compatibility is to only use the annotation, even when creating `v1` Ingresses.
 
 ## ingress-nginx
 
-If you chose not to use the IngressClass `nginx` that is created by default by the Helm chart
-(e.g., you named the IngressClass `nginx-outside`), you will need to add the flags
-`--ingress-class` and `--ingress-class-by-name` to your ingress-nginx deployment:
+If you chose not to use the IngressClass `nginx` that is created by default by
+the Helm chart (e.g., you named the IngressClass `nginx-outside`), you will need
+to add the flags `--ingress-class` to your ingress-nginx deployment:
 
 ```
 --ingress-class=nginx-outside --ingress-class-by-name=true

content/docs/installation/upgrading/upgrading-0.7-0.8.md

@@ -78,7 +78,7 @@ spec:
     - selector: {}
       http01:
         ingress:
-          class: nginx
+          ingressClassName: nginx
     - selector:
         # Any Certificate resources, or Ingress resources that use
         # ingress-shim and match the below label selector will use this
@@ -204,7 +204,7 @@ spec:
     - selector: {}
       http01:
         ingress:
-          class: nginx
+          ingressClassName: nginx
     - selector:
         # Any Certificate resources, or Ingress resources that use
         # ingress-shim and match the below label selector will use this