Merge pull request #1704 from wallrj/acme-profiles-docs

Add documentation for ACME certificate profiles

Author: cert-manager-prow[bot]

content/docs/configuration/acme/README.md

@@ -57,6 +57,9 @@ spec:
     # Let's Encrypt will use this to contact you about expiring
     # certificates, and issues related to your account.
     email: [email protected]
+    # If the ACME server supports profiles, you can specify the profile name here.
+    # See #acme-certificate-profiles below.
+    profile: tlsserver
     server: https://acme-staging-v02.api.letsencrypt.org/directory
     privateKeySecretRef:
       # Secret resource that will be used to store the account's private key.
@@ -80,6 +83,39 @@ Solvers come in the form of [`dns01`](./dns01/README.md) and
 these solver types, visit their respective documentation -
 [DNS01](./dns01/README.md), [HTTP01](./http01/README.md).
 
+### ACME Certificate Profiles
+
+> ℹ️ This feature is available in cert-manager `>= v1.18.0`.
+
+An ACME Server *may* offer a selection of different certificate profiles to ACME Clients.
+
+Use the optional `profile` field in the `Issuer` or `ClusterIssuer` to select a profile for your ACME orders.
+
+Let's Encrypt already offers [a selection of profiles](https://letsencrypt.org/docs/profiles/).
+Other ACME servers may not yet support profiles or they might offer different profiles, so check your ACME server's documentation to see what profiles are available.
+
+You can find out if your ACME server supports profiles by downloading the directory object.
+For example:
+
+```bash
+curl -fsSL https://acme-staging-v02.api.letsencrypt.org/directory
+```
+
+If profiles are supported you will see "profiles" among the fields of the JSON object.
+
+If you do not specify a profile, the ACME server will use its default profile,
+which in the case of Let's Encrypt, is the `classic` profile.
+
+> ⚠️ If you specify a profile and connect to an ACME server that does not yet support the [ACME Profiles Extension][rfc],
+> cert-manager will report an error on the CertificateRequest resource.
+>
+> ℹ️ If you specify a profile which the ACME server does not recognize,
+> cert-manager will report an error on the CertificateRequest resource.
+>
+> 📖 Read [ACME protocol extension for certificate profiles (IETF draft)][rfc] to learn more..
+
+[rfc]: https://datatracker.ietf.org/doc/draft-aaron-acme-profiles/
+
 ### External Account Bindings
 
 cert-manager supports using External Account Bindings with your ACME account.

content/docs/releases/release-notes/release-notes-1.18.md

@@ -7,7 +7,7 @@ cert-manager is the easiest way to automatically manage certificates in Kubernet
 
 ## Major Themes
 
-### ACME Certificate Profile Selection
+### ACME Certificate Profiles
 
 cert-manager now supports the selection of ACME certificate profiles, allowing
 users to request different categories of certificates from their ACME
@@ -23,6 +23,8 @@ for their certificate management needs.
 [tlsserver]: https://letsencrypt.org/docs/profiles/#tlsserver
 [shortlived]: https://letsencrypt.org/docs/profiles/#shortlived
 
+> 📖 Learn more by visiting the [ACME Issuer documentation](../../configuration/acme/README.md#acme-certificate-profiles).
+
 ### The default value of `Certificate.Spec.PrivateKey.RotationPolicy` is now `Always`
 
 > ⚠️ Breaking change

content/docs/troubleshooting/acme.md

@@ -122,6 +122,12 @@ $ kubectl get order <order-name> -ojsonpath='{.status.authorizations[x].url}'
 If the Order is not completing successfully, you can debug the challenges
 for the Order by running `kubectl describe` on the `Challenge` resource which is described in the following steps.
 
+### Common errors
+
+* `Issuer: strict decoding error: unknown field "spec.acme.profile"`: The `ClusterIssuer.spec.acme.profile` and `Issuer.spec.acme.profile` fields were added in cert-manager `>=v1.18.0`. You are probably trying to use the field with an older version of cert-manager.
+* `Failed to create Order: acme: certificate authority does not advertise a profile with name <profile-name>`: The ACME server supports [ACME Certificate Profiles](../configuration/acme/README.md#acme-certificate-profiles), but it does not have a profile matching the `profile` value in the `Issuer` or `ClusterIssuer`.
+* `Failed to create Order: acme: certificate authority does not support profiles`: The ACME server does not support [ACME Certificate Profiles](../configuration/acme/README.md#acme-certificate-profiles).
+
 ## 3. Troubleshooting Challenges
 
 In order to determine why an ACME Order is not being finished, we can debug

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

@@ -8,6 +8,8 @@ spec:
     server: https://acme-v02.api.letsencrypt.org/directory
     # Email address used for ACME registration
     email: [email protected]
+    # The ACME certificate profile
+    profile: tlsserver
     # Name of a secret used to store the ACME account private key
     privateKeySecretRef:
       name: letsencrypt-prod

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

@@ -8,6 +8,8 @@ spec:
     server: https://acme-staging-v02.api.letsencrypt.org/directory
     # Email address used for ACME registration
     email: [email protected]
+    # The ACME certificate profile
+    profile: tlsserver
     # Name of a secret used to store the ACME account private key
     privateKeySecretRef:
       name: letsencrypt-staging

content/docs/tutorials/acme/nginx-ingress.md

@@ -297,6 +297,7 @@ Metadata:
 Spec:
   Acme:
     Email:  [email protected]
+    Profile: tlsserver
     Private Key Secret Ref:
       Key:
       Name:  letsencrypt-staging

content/docs/tutorials/getting-started-with-cert-manager-on-google-kubernetes-engine-using-lets-encrypt-for-ingress-ssl/README.md

@@ -341,6 +341,7 @@ spec:
   acme:
     server: https://acme-staging-v02.api.letsencrypt.org/directory
     email: <email-address> # ❗ Replace this with your email address
+    profile: tlsserver
     privateKeySecretRef:
       name: letsencrypt-staging
     solvers:
@@ -495,6 +496,7 @@ spec:
   acme:
     server: https://acme-v02.api.letsencrypt.org/directory
     email: <email-address> # ❗ Replace this with your email address
+    profile: tlsserver
     privateKeySecretRef:
       name: letsencrypt-production
     solvers:

public/docs/tutorials/getting-started-aks-letsencrypt/clusterissuer-lets-encrypt-production.yaml

@@ -7,6 +7,7 @@ spec:
   acme:
     server: https://acme-v02.api.letsencrypt.org/directory
     email: $EMAIL_ADDRESS
+    profile: tlsserver
     privateKeySecretRef:
       name: letsencrypt-production
     solvers:

public/docs/tutorials/getting-started-aks-letsencrypt/clusterissuer-lets-encrypt-staging.yaml

@@ -7,6 +7,7 @@ spec:
   acme:
     server: https://acme-staging-v02.api.letsencrypt.org/directory
     email: $EMAIL_ADDRESS
+    profile: tlsserver
     privateKeySecretRef:
       name: letsencrypt-staging
     solvers:

public/docs/tutorials/getting-started-aws-letsencrypt/clusterissuer-lets-encrypt-production.yaml

@@ -7,6 +7,7 @@ spec:
   acme:
     server: https://acme-v02.api.letsencrypt.org/directory
     email: $EMAIL_ADDRESS
+    profile: tlsserver
     privateKeySecretRef:
       name: letsencrypt-production
     solvers: