Document custom annotation behaviour

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

@@ -9,7 +9,11 @@ cert-manager v1.18 includes:
 
 ## Major Themes
 
-### TODO
+### Copy annotations from Ingress or Gateway to the Certificate
+
+We've added a new configuration option to the cert-manager controller: `--extra-certificate-annotations`, which allows you to specify annotation keys to be copied from an Ingress or Gateway resource to the resulting Certificate object.
+Read [Annotated Ingress resource: Copy annotations to the Certificate](../../usage/ingress.md#copy-annotations-to-the-certificate ), and
+[Annotated Gateway resource: Copy annotations to the Certificate](../../usage/gateway.md#copy-annotations-to-the-certificate), to learn more.
 
 ## Community
 

content/docs/usage/gateway.md

@@ -438,6 +438,40 @@ Certificate resources:
   configure `spec.privateKey.rotationPolicy` field to set the rotation policy of the private key for a Certificate.
   Valid values are `Never` and `Always`. If unset a rotation policy `Never` will be used.
 
+## Copy annotations to the Certificate
+
+> ℹ️ This feature was added in cert-manager `v1.18.0`.
+
+It is possible to copy any specific custom annotation into the generated `Certificate` objects.
+For example, to copy the annotation: `venafi.cert-manager.io/custom-fields` from the Gateway to the Certificate,
+you must first redeploy the cert-manager controller with the following extra argument:
+
+```
+--extra-certificate-annotations=venafi.cert-manager.io/custom-fields
+```
+
+Or if you use Helm, supply the following values:
+
+```yaml
+# values.yaml
+config:
+  ingressShimConfig:
+    extraCertificateAnnotations:
+    - venafi.cert-manager.io/custom-fields
+```
+
+Then you can add the annotation to the Gateway resource:
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: example
+  annotations:
+    # custom venafi configuration
+    venafi.cert-manager.io/custom-fields: `[ {"name": "field-name", "value": "field value"}]`
+```
+
 ## Inner workings diagram for developers
 
 <object data="/images/request-certificate-debug/gateway-shim-flow.svg"></object>

content/docs/usage/ingress.md

@@ -177,6 +177,41 @@ trigger Certificate resources to be automatically created:
   configure `spec.privateKey.rotationPolicy` field to set the rotation policy of the private key for a Certificate.
   Valid values are `Never` and `Always`. If unset a rotation policy `Never` will be used.
 
+## Copying annotations to the Certificate
+
+> ℹ️ This feature was added in cert-manager `v1.18.0`.
+
+It is possible to copy any specific custom annotation into the generated `Certificate` objects.
+For example, to copy the annotation: `venafi.cert-manager.io/custom-fields` from the Ingress to the Certificate,
+you must first redeploy the cert-manager controller with the following extra argument:
+
+```
+--extra-certificate-annotations=venafi.cert-manager.io/custom-fields
+```
+
+Or if you use Helm, supply the following values:
+
+```yaml
+# values.yaml
+config:
+  ingressShimConfig:
+    extraCertificateAnnotations:
+    - venafi.cert-manager.io/custom-fields
+```
+
+Then you can add the annotation to the Ingress resource:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  annotations:
+    # custom venafi configuration
+    venafi.cert-manager.io/custom-fields: `[ {"name": "field-name", "value": "field value"}]`
+  name: myIngress
+  namespace: myIngress
+```
+
 ## Generate multiple certificates with multiple ingresses
 
 If you need to generate certificates from multiple ingresses make sure it has the issuer annotation.