docs: add docs on mutation annotations (#2999)

Signed-off-by: Xander Grzywinski <[email protected]>
Co-authored-by: Rita Zhang <[email protected]>

website/docs/customize-startup.md

@@ -57,6 +57,8 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
 
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details
+
 ## Other Configuration Options
 
 For the complete list of configuration flags for your specific version of Gatekeeper, run the Gatekeeper binary with the `--help` flag. For example:

website/docs/mutation.md

@@ -252,6 +252,11 @@ must start with `:` or `@`. Also, if `assignPath` is set to a value which could
 be interpreted as a domain, such as `my.repo.lib/app`, then `assignDomain` must
 also be specified.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
+
 ## Examples
 
 ### Adding an annotation

website/versioned_docs/version-v3.10.x/customize-startup.md

@@ -53,6 +53,8 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
 
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details
+
 ## Other Configuration Options
 
 For the complete list of configuration flags for your specific version of Gatekeeper, run the Gatekeeper binary with the `--help` flag. For example:

website/versioned_docs/version-v3.10.x/mutation.md

@@ -213,6 +213,10 @@ spec:
 - `spec.parameters.values.fromList` holds the list of values that will be added or removed.
 - `operation` can be `merge` to insert values into the list if missing, or `prune` to remove values from the list. `merge` is default.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
 
 ## Examples
 

website/versioned_docs/version-v3.11.x/customize-startup.md

@@ -53,6 +53,8 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
 
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details
+
 ## Other Configuration Options
 
 For the complete list of configuration flags for your specific version of Gatekeeper, run the Gatekeeper binary with the `--help` flag. For example:

website/versioned_docs/version-v3.11.x/mutation.md

@@ -213,6 +213,10 @@ spec:
 - `spec.parameters.values.fromList` holds the list of values that will be added or removed.
 - `operation` can be `merge` to insert values into the list if missing, or `prune` to remove values from the list. `merge` is default.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
 
 ## Examples
 

website/versioned_docs/version-v3.12.x/customize-startup.md

@@ -57,6 +57,8 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
 
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details
+
 ## Other Configuration Options
 
 For the complete list of configuration flags for your specific version of Gatekeeper, run the Gatekeeper binary with the `--help` flag. For example:

website/versioned_docs/version-v3.12.x/mutation.md

@@ -252,6 +252,11 @@ must start with `:` or `@`. Also, if `assignPath` is set to a value which could
 be interpreted as a domain, such as `my.repo.lib/app`, then `assignDomain` must
 also be specified.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
+
 ## Examples
 
 ### Adding an annotation

website/versioned_docs/version-v3.13.x/customize-startup.md

@@ -57,6 +57,8 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
 
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details
+
 ## Other Configuration Options
 
 For the complete list of configuration flags for your specific version of Gatekeeper, run the Gatekeeper binary with the `--help` flag. For example:

website/versioned_docs/version-v3.13.x/mutation.md

@@ -252,6 +252,11 @@ must start with `:` or `@`. Also, if `assignPath` is set to a value which could
 be interpreted as a domain, such as `my.repo.lib/app`, then `assignDomain` must
 also be specified.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
+
 ## Examples
 
 ### Adding an annotation

website/versioned_docs/version-v3.7.x/customize-startup.md

@@ -52,3 +52,5 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
+
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details

website/versioned_docs/version-v3.7.x/mutation.md

@@ -211,6 +211,10 @@ spec:
 - `spec.parameters.values.fromList` holds the list of values that will be added or removed.
 - `operation` can be `merge` to insert values into the list if missing, or `prune` to remove values from the list. `merge` is default.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
 
 ## Examples
 

website/versioned_docs/version-v3.8.x/customize-startup.md

@@ -53,6 +53,8 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
 
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details
+
 ## Other Configuration Options
 
 For the complete list of configuration flags for your specific version of Gatekeeper, run the Gatekeeper binary with the `--help` flag. For example:

website/versioned_docs/version-v3.8.x/mutation.md

@@ -211,6 +211,10 @@ spec:
 - `spec.parameters.values.fromList` holds the list of values that will be added or removed.
 - `operation` can be `merge` to insert values into the list if missing, or `prune` to remove values from the list. `merge` is default.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
 
 ## Examples
 

website/versioned_docs/version-v3.9.x/customize-startup.md

@@ -53,6 +53,8 @@ The `--mutation-annotations` flag adds the following two annotations to mutated
 | `gatekeeper.sh/mutation-id` | The UUID of the mutation.                                                                                                                                     |
 | `gatekeeper.sh/mutations`   | A list of comma-separated mutations in the format of `<MutationType>/<MutationNamespace>/<MutationName>:<MutationGeneration>` that are applied to the object. |
 
+> ❗ Note that this will break the idempotence requirement that Kubernetes sets for mutation webhooks. See the [Kubernetes docs here](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence) for more details
+
 ## Other Configuration Options
 
 For the complete list of configuration flags for your specific version of Gatekeeper, run the Gatekeeper binary with the `--help` flag. For example:

website/versioned_docs/version-v3.9.x/mutation.md

@@ -211,6 +211,10 @@ spec:
 - `spec.parameters.values.fromList` holds the list of values that will be added or removed.
 - `operation` can be `merge` to insert values into the list if missing, or `prune` to remove values from the list. `merge` is default.
 
+### Mutation Annotations
+
+You can have two recording annotations applied at mutation time by enabling the `--mutation-annotations` flag. More details can be found on the
+[customize startup docs page](./customize-startup.md).
 
 ## Examples