ingress-controller: add more docs for the certificate auto provisioning (#1418)

## Summary
Add some more documentation around the certificate auto provisioning
options.

## Related issues
-
[ENG-4055](https://linear.app/pomerium/issue/ENG-4055/documentation-document-new-certificate-controller)


## Checklist

- [x] reference any related issues
- [ ] updated docs
- [ ] updated unit tests
- [ ] updated UPGRADING.md
- [ ] add appropriate tag (`improvement` / `bug` / etc)
- [x] ready for review

Author: calebdoxsey

apis/ingress/v1/pomerium_types.go

@@ -383,7 +383,8 @@ type PomeriumSpec struct {
 
 	// CertificateAutoProvision sets the certificate auto provision settings.
 	// This is a fallback for routes that are not defined via Ingress or
-	// Gateway resources.
+	// Gateway resources. When configured, cert-manager certificate resources
+	// will be created for any routes which have no matching TLS certificate.
 	//
 	// +kubebuilder:validation:Optional
 	CertificateAutoProvision *CertificateAutoProvision `json:"certificateAutoProvision,omitzero"`
@@ -547,9 +548,16 @@ type SSH struct {
 
 // CertificateAutoProvision are the settings for automatically provisioning certificates.
 type CertificateAutoProvision struct {
+	// The cert-manager ClusterIssuer that will be used for new certificates.
+	// Certificates will be created in the same namespace as the controller
+	// pod.
+	//
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:MinLength=1
 	ClusterIssuer *string `json:"clusterIssuer"`
+	// The cert-manager Issuer that will be used for new certificates.
+	// Certificates will be created in the same namespace as the Issuer.
+	//
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:Format="namespace/name"

config/crd/bases/ingress.pomerium.io_pomerium.yaml

@@ -97,12 +97,20 @@ spec:
                 description: |-
                   CertificateAutoProvision sets the certificate auto provision settings.
                   This is a fallback for routes that are not defined via Ingress or
-                  Gateway resources.
+                  Gateway resources. When configured, cert-manager certificate resources
+                  will be created for any routes which have no matching TLS certificate.
                 properties:
                   clusterIssuer:
+                    description: |-
+                      The cert-manager ClusterIssuer that will be used for new certificates.
+                      Certificates will be created in the same namespace as the controller
+                      pod.
                     minLength: 1
                     type: string
                   issuer:
+                    description: |-
+                      The cert-manager Issuer that will be used for new certificates.
+                      Certificates will be created in the same namespace as the Issuer.
                     format: namespace/name
                     minLength: 1
                     type: string

deployment.yaml

@@ -239,12 +239,20 @@ spec:
                 description: |-
                   CertificateAutoProvision sets the certificate auto provision settings.
                   This is a fallback for routes that are not defined via Ingress or
-                  Gateway resources.
+                  Gateway resources. When configured, cert-manager certificate resources
+                  will be created for any routes which have no matching TLS certificate.
                 properties:
                   clusterIssuer:
+                    description: |-
+                      The cert-manager ClusterIssuer that will be used for new certificates.
+                      Certificates will be created in the same namespace as the controller
+                      pod.
                     minLength: 1
                     type: string
                   issuer:
+                    description: |-
+                      The cert-manager Issuer that will be used for new certificates.
+                      Certificates will be created in the same namespace as the Issuer.
                     format: namespace/name
                     minLength: 1
                     type: string

reference.md

@@ -98,7 +98,7 @@ PomeriumSpec defines Pomerium-specific configuration parameters.
                     (<a href="#certificateautoprovision">certificateAutoProvision</a>)
                 </p>
                 <p>
-                    CertificateAutoProvision sets the certificate auto provision settings. This is a fallback for routes that are not defined via Ingress or Gateway resources.
+                    CertificateAutoProvision sets the certificate auto provision settings. This is a fallback for routes that are not defined via Ingress or Gateway resources. When configured, cert-manager certificate resources will be created for any routes which have no matching TLS certificate.
                 </p>
             </td>
         </tr>
@@ -389,7 +389,7 @@ Authenticate sets authenticate service parameters. If not specified, a Pomerium-
 
 ### `certificateAutoProvision`
 
-CertificateAutoProvision sets the certificate auto provision settings. This is a fallback for routes that are not defined via Ingress or Gateway resources.
+CertificateAutoProvision sets the certificate auto provision settings. This is a fallback for routes that are not defined via Ingress or Gateway resources. When configured, cert-manager certificate resources will be created for any routes which have no matching TLS certificate.
 
 <table>
     <thead>
@@ -402,6 +402,7 @@ CertificateAutoProvision sets the certificate auto provision settings. This is a
                     <strong>string</strong>&#160;
                 </p>
                 <p>
+                    The cert-manager ClusterIssuer that will be used for new certificates. Certificates will be created in the same namespace as the controller pod.
                 </p>
             </td>
         </tr>
@@ -413,6 +414,7 @@ CertificateAutoProvision sets the certificate auto provision settings. This is a
                     (namespace/name)
                 </p>
                 <p>
+                    The cert-manager Issuer that will be used for new certificates. Certificates will be created in the same namespace as the Issuer.
                 </p>
                 Format: reference to Kubernetes resource with namespace prefix: <code>namespace/name</code> format.
             </td>