Document the ingressClassName field

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/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

content/docs/reference/api-docs.md

@@ -785,6 +785,17 @@ description: >-
         <p>Optional service type for Kubernetes solver service. Supported values are NodePort or ClusterIP. If unset, defaults to NodePort.</p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <code>ingressClassName</code>
+        <br />
+        <em>string</em>
+      </td>
+      <td>
+        <em>(Optional)</em>
+        <p> This field configures the field <code>ingressClassName</code> on the created Ingress resources used to solve ACME challenges that use this challenge solver. This is the recommended way of configuring the ingress class. Only one of <code>class</code>, <code>name</code> or <code>ingressClassName</code> may be specified. </p>
+      </td>
+    </tr>
     <tr>
       <td>
         <code>class</code>
@@ -793,7 +804,7 @@ description: >-
       </td>
       <td>
         <em>(Optional)</em>
-        <p>The ingress class to use when creating Ingress resources to solve ACME challenges that use this challenge solver. Only one of &lsquo;class&rsquo; or &lsquo;name&rsquo; may be specified.</p>
+        <p> This field configures the annotation <code>kubernetes.io/ingress.class</code> when creating Ingress resources to solve ACME challenges that use this challenge solver. Only one of <code>class</code>, <code>name</code> or <code>ingressClassName</code> may be specified. </p>
       </td>
     </tr>
     <tr>
@@ -975,6 +986,19 @@ description: >-
         <p>If specified, the pod&rsquo;s service account</p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <code>imagePullSecrets</code>
+        <br />
+        <em>
+          <a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#localobjectreference-v1-core">[]Kubernetes core/v1.LocalObjectReference</a>
+        </em>
+      </td>
+      <td>
+        <em>(Optional)</em>
+        <p>If specified, the pod&rsquo;s imagePullSecrets</p>
+      </td>
+    </tr>
   </tbody>
 </table>
 <h3 id="acme.cert-manager.io/v1.ACMEChallengeSolverHTTP01IngressPodTemplate">ACMEChallengeSolverHTTP01IngressPodTemplate</h3>
@@ -1011,7 +1035,7 @@ description: >-
       </td>
       <td>
         <em>(Optional)</em>
-        <p>PodSpec defines overrides for the HTTP01 challenge solver pod. Only the &lsquo;priorityClassName&rsquo;, &lsquo;nodeSelector&rsquo;, &lsquo;affinity&rsquo;, &lsquo;serviceAccountName&rsquo; and &lsquo;tolerations&rsquo; fields are supported currently. All other fields will be ignored.</p>
+        <p>PodSpec defines overrides for the HTTP01 challenge solver pod. Check ACMEChallengeSolverHTTP01IngressPodSpec to find out currently supported fields. All other fields will be ignored.</p>
         <br />
         <br />
         <table>
@@ -1074,6 +1098,19 @@ description: >-
               <p>If specified, the pod&rsquo;s service account</p>
             </td>
           </tr>
+          <tr>
+            <td>
+              <code>imagePullSecrets</code>
+              <br />
+              <em>
+                <a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#localobjectreference-v1-core">[]Kubernetes core/v1.LocalObjectReference</a>
+              </em>
+            </td>
+            <td>
+              <em>(Optional)</em>
+              <p>If specified, the pod&rsquo;s imagePullSecrets</p>
+            </td>
+          </tr>
         </table>
       </td>
     </tr>
@@ -4796,6 +4833,31 @@ description: >-
     </tr>
   </tbody>
 </table>
+<h3 id="cert-manager.io/v1.ServiceAccountRef">ServiceAccountRef</h3>
+<p> (<em>Appears on:</em> <a href="#cert-manager.io/v1.VaultKubernetesAuth">VaultKubernetesAuth</a>) </p>
+<div>
+  <p> ServiceAccountRef is a service account used by cert-manager to request a token. The audience cannot be configured. The audience is generated by cert-manager and takes the form <code>vault://namespace-name/issuer-name</code> for an Issuer and <code>vault://issuer-name</code> for a ClusterIssuer. The expiration of the token is also set by cert-manager to 10 minutes. </p>
+</div>
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>name</code>
+        <br />
+        <em>string</em>
+      </td>
+      <td>
+        <p>Name of the ServiceAccount used to request a token.</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
 <h3 id="cert-manager.io/v1.VaultAppRole">VaultAppRole</h3>
 <p> (<em>Appears on:</em> <a href="#cert-manager.io/v1.VaultAuth">VaultAuth</a>) </p>
 <div>
@@ -4846,7 +4908,7 @@ description: >-
 <h3 id="cert-manager.io/v1.VaultAuth">VaultAuth</h3>
 <p> (<em>Appears on:</em> <a href="#cert-manager.io/v1.VaultIssuer">VaultIssuer</a>) </p>
 <div>
-  <p> Configuration used to authenticate with a Vault server. Only one of <code>tokenSecretRef</code>, <code>appRole</code> or <code>kubernetes</code> may be specified. </p>
+  <p> VaultAuth is configuration used to authenticate with a Vault server. The order of precedence is [<code>tokenSecretRef</code>, <code>appRole</code> or <code>kubernetes</code>]. </p>
 </div>
 <table>
   <thead>
@@ -5012,9 +5074,23 @@ description: >-
         </em>
       </td>
       <td>
+        <em>(Optional)</em>
         <p>The required Secret field containing a Kubernetes ServiceAccount JWT used for authenticating with Vault. Use of &lsquo;ambient credentials&rsquo; is not supported.</p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <code>serviceAccountRef</code>
+        <br />
+        <em>
+          <a href="#cert-manager.io/v1.ServiceAccountRef">ServiceAccountRef</a>
+        </em>
+      </td>
+      <td>
+        <em>(Optional)</em>
+        <p>A reference to a service account that will be used to request a bound token (also known as &ldquo;projected token&rdquo;). Compared to using &ldquo;secretRef&rdquo;, using this field means that you don&rsquo;t rely on statically bound tokens. To use this field, you must configure an RBAC rule to let cert-manager request a token.</p>
+      </td>
+    </tr>
     <tr>
       <td>
         <code>role</code>
@@ -5670,5 +5746,5 @@ description: >-
 </table>
 <hr />
 <p>
-  <em> Generated with <code>gen-crd-api-reference-docs</code> on git commit <code>7ebb5f515</code>. </em>
+  <em> Generated with <code>gen-crd-api-reference-docs</code> on git commit <code>ca9aaa0</code>. </em>
 </p>

content/docs/release-notes/release-notes-1.12.md

@@ -17,3 +17,9 @@ create an ephemeral service account token on your behalf and use that to
 authenticate to Vault.
 
 > 📖 Read about [Secretless Authentication with a Service Account](../configuration/vault.md#secretless-authentication-with-a-service-account).
+
+### Support for `ingressClassName` in the HTTP-01 solver
+
+cert-manager now supports the `ingressClassName` field in the HTTP-01 solver. We
+recommend using `ingressClassName` instead of the field `class` in your Issuers
+and ClusterIssuers.

content/docs/tutorials/acme/example/ingress-tls-final.yaml

@@ -3,10 +3,10 @@ kind: Ingress
 metadata:
   name: kuard
   annotations:
-    kubernetes.io/ingress.class: "nginx"    
     cert-manager.io/issuer: "letsencrypt-prod"
 
 spec:
+  ingressClassName: nginx
   tls:
   - hosts:
     - example.example.com

content/docs/tutorials/acme/example/ingress-tls.yaml

@@ -3,10 +3,10 @@ kind: Ingress
 metadata:
   name: kuard
   annotations:
-    kubernetes.io/ingress.class: "nginx"    
     cert-manager.io/issuer: "letsencrypt-staging"
 
 spec:
+  ingressClassName: nginx
   tls:
   - hosts:
     - example.example.com

content/docs/tutorials/acme/example/ingress.yaml

@@ -2,11 +2,10 @@ apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: kuard
-  annotations:
-    kubernetes.io/ingress.class: "nginx"    
+  annotations: {}
     #cert-manager.io/issuer: "letsencrypt-staging"
-
 spec:
+  ingressClassName: nginx
   tls:
   - hosts:
     - example.example.com

content/docs/tutorials/acme/example/pomerium-production-issuer.yaml

@@ -14,6 +14,6 @@ spec:
       name: letsencrypt-prod
     # Enable the HTTP-01 challenge provider
     solvers:
-    - http01:
-        ingress:
-          class: pomerium
+      - http01:
+          ingress:
+            ingressClassName: pomerium

content/docs/tutorials/acme/example/pomerium-staging-issuer.yaml

@@ -16,4 +16,4 @@ spec:
     solvers:
       - http01:
           ingress:
-            class:  pomerium
+            ingressClassName: pomerium