Move best practices from dynamic admission control page to best practices page

Moved content as-is (no text changes) for a more readable diff between commits.

The following sections werent moved:

* Idempotence main section (better content in new page)
* Intercepting all versions of an object (better content in new page)
* Guaranteeing the final state of an object is seen
* Avoiding operating in the kube-system namespace

Author: shannonxtreme

content/en/docs/concepts/cluster-administration/admission-webhooks-good-practices.md

@@ -283,11 +283,27 @@ Consider the following when modifying arrays:
 
 ### Avoid side effects {#avoid-side-effects}
 
-TODO: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#side-effects-1
+It is recommended that admission webhooks should avoid side effects if possible, which means the webhooks operate only on the
+content of the `AdmissionReview` sent to them, and do not make out-of-band changes. The `.webhooks[].sideEffects` field should
+be set to `None` if a webhook doesn't have any side effect.
+
+If side effects are required during the admission evaluation, they must be suppressed when processing an
+`AdmissionReview` object with `dryRun` set to `true`, and the `.webhooks[].sideEffects` field should be
+set to `NoneOnDryRun`. See [Side effects](#side-effects) for more detail.
 
 ### Avoid self-mutations {#avoid-self-mutation}
 
-TODO: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#avoiding-deadlocks-in-self-hosted-webhooks 
+A webhook running inside the cluster might cause deadlocks for its own deployment if it is configured
+to intercept resources required to start its own pods.
+
+For example, a mutating admission webhook is configured to admit `CREATE` pod requests only if a certain label is set in the
+pod (e.g. `"env": "prod"`). The webhook server runs in a deployment which doesn't set the `"env"` label.
+When a node that runs the webhook server pods
+becomes unhealthy, the webhook deployment will try to reschedule the pods to another node. However the requests will
+get rejected by the existing webhook server since the `"env"` label is unset, and the migration cannot happen.
+
+It is recommended to exclude the namespace where your webhook is running with a
+[namespaceSelector](#matching-requests-namespaceselector).
 
 ### Fail open and validate the final state {#fail-open-validate-final-state}
 
@@ -386,7 +402,39 @@ challenging. The following recommendations might help:
   multiple times by the same webhook. 
 * Ensure that the scope of each mutating webhook is specific and limited.
 
-TODO: bring examples from https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#idempotence
+#### Example of idempotent mutating admission webhooks:
+
+1. For a `CREATE` pod request, set the field `.spec.securityContext.runAsNonRoot` of the
+   pod to true, to enforce security best practices.
+
+2. For a `CREATE` pod request, if the field `.spec.containers[].resources.limits`
+   of a container is not set, set default resource limits.
+
+3. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar` if no container
+   with the name `foo-sidecar` already exists.
+
+In the cases above, the webhook can be safely reinvoked, or admit an object that already has the fields set.
+
+#### Example of non-idempotent mutating admission webhooks:
+
+1. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar`
+   suffixed with the current timestamp (e.g. `foo-sidecar-19700101-000000`).
+
+2. For a `CREATE`/`UPDATE` pod request, reject if the pod has label `"env"` set,
+   otherwise add an `"env": "prod"` label to the pod.
+
+3. For a `CREATE` pod request, blindly append a sidecar container named
+   `foo-sidecar` without looking to see if there is already a `foo-sidecar`
+   container in the pod.
+
+In the first case above, reinvoking the webhook can result in the same sidecar being injected multiple times to a pod, each time
+with a different container name. Similarly the webhook can inject duplicated containers if the sidecar already exists in
+a user-provided pod.
+
+In the second case above, reinvoking the webhook will result in the webhook failing on its own output.
+
+In the third case above, reinvoking the webhook will result in duplicated containers in the pod spec, which makes
+the request invalid and rejected by the API server.
 
 ## Mutation testing and validation {#mutation-testing-validation}
 
@@ -493,6 +541,15 @@ Consider situations like the preceding example when writing your webhooks.
 Exclude operations that are a result of Kubernetes responding to unavoidable
 incidents.
 
+It is recommended that admission webhooks should evaluate as quickly as possible (typically in
+milliseconds), since they add to API request latency.
+It is encouraged to use a small timeout for webhooks. See [Timeouts](#timeouts) for more detail.
+
+It is recommended that admission webhooks should leverage some format of load-balancing, to
+provide high availability and performance benefits. If a webhook is running within the cluster,
+you can run multiple webhook backends behind a service to leverage the load-balancing that service
+supports.
+
 ## Examples of good implementations {#example-good-implementations}
 
 {{% thirdparty-content %}}

content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md

@@ -1178,142 +1178,4 @@ apiserver_admission_webhook_rejection_count{error_type="no_error",name="deny-unw
 
 For recommendations and considerations when writing mutating admission webhooks,
 see
-[Mutating Webhooks Good Practices](/docs/concepts/security/mutating-webhooks-good-practices).
-
-### Idempotence
-
-An idempotent mutating admission webhook is able to successfully process an object it has already admitted
-and potentially modified. The admission can be applied multiple times without changing the result beyond
-the initial application.
-
-#### Example of idempotent mutating admission webhooks:
-
-1. For a `CREATE` pod request, set the field `.spec.securityContext.runAsNonRoot` of the
-   pod to true, to enforce security best practices.
-
-2. For a `CREATE` pod request, if the field `.spec.containers[].resources.limits`
-   of a container is not set, set default resource limits.
-
-3. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar` if no container
-   with the name `foo-sidecar` already exists.
-
-In the cases above, the webhook can be safely reinvoked, or admit an object that already has the fields set.
-
-#### Example of non-idempotent mutating admission webhooks:
-
-1. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar`
-   suffixed with the current timestamp (e.g. `foo-sidecar-19700101-000000`).
-
-2. For a `CREATE`/`UPDATE` pod request, reject if the pod has label `"env"` set,
-   otherwise add an `"env": "prod"` label to the pod.
-
-3. For a `CREATE` pod request, blindly append a sidecar container named
-   `foo-sidecar` without looking to see if there is already a `foo-sidecar`
-   container in the pod.
-
-In the first case above, reinvoking the webhook can result in the same sidecar being injected multiple times to a pod, each time
-with a different container name. Similarly the webhook can inject duplicated containers if the sidecar already exists in
-a user-provided pod.
-
-In the second case above, reinvoking the webhook will result in the webhook failing on its own output.
-
-In the third case above, reinvoking the webhook will result in duplicated containers in the pod spec, which makes
-the request invalid and rejected by the API server.
-
-### Intercepting all versions of an object
-
-It is recommended that admission webhooks should always intercept all versions of an object by setting `.webhooks[].matchPolicy`
-to `Equivalent`. It is also recommended that admission webhooks should prefer registering for stable versions of resources.
-Failure to intercept all versions of an object can result in admission policies not being enforced for requests in certain
-versions. See [Matching requests: matchPolicy](#matching-requests-matchpolicy) for examples.
-
-### Availability
-
-It is recommended that admission webhooks should evaluate as quickly as possible (typically in
-milliseconds), since they add to API request latency.
-It is encouraged to use a small timeout for webhooks. See [Timeouts](#timeouts) for more detail.
-
-It is recommended that admission webhooks should leverage some format of load-balancing, to
-provide high availability and performance benefits. If a webhook is running within the cluster,
-you can run multiple webhook backends behind a service to leverage the load-balancing that service
-supports.
-
-### Guaranteeing the final state of the object is seen
-
-Admission webhooks that need to guarantee they see the final state of the object in order to enforce policy
-should use a validating admission webhook, since objects can be modified after being seen by mutating webhooks.
-
-For example, a mutating admission webhook is configured to inject a sidecar container with name
-"foo-sidecar" on every `CREATE` pod request. If the sidecar *must* be present, a validating
-admisson webhook should also be configured to intercept `CREATE` pod requests, and validate that a
-container with name "foo-sidecar" with the expected configuration exists in the to-be-created
-object.
-
-### Avoiding deadlocks in self-hosted webhooks
-
-There are several ways that webhooks can cause deadlocks, where the cluster cannot make progress in
-scheduling pods:
-
-* A webhook running inside the cluster might cause deadlocks for its own deployment if it is configured
-  to intercept resources required to start its own pods.
-
-  For example, a mutating admission webhook is configured to admit **create** Pod requests only if a certain label is set in the
-  pod (such as `env: "prod"`). However, the webhook server runs as a Deployment that doesn't set the `env` label.
-  When a node that runs the webhook server pods
-  becomes unhealthy, the webhook deployment will try to reschedule the pods to another node. However the requests will
-  get rejected by the existing webhook server since the `env` label is unset, and the replacement Pod
-  cannot be created. Eventually, the entire Deployment for the webhook server may become unhealthy.
-
-  If you use admission webhooks to check Pods, consider excluding the namespace where your webhook
-  listener is running, by specifying a
-  [namespaceSelector](#matching-requests-namespaceselector).
-
-* If the cluster has multiple webhooks configured (possibly from independent applications deployed on
-  the cluster), they can form a cycle.  Webhook A must be called to process startup of webhook B's
-  pods and vice versa. If both webhook A and webhook B ever become unavailable at the same time (for
-  example, due to a cluster-wide outage or a node failure where both pods run on the same node)
-  deadlock occurs because neither webhook pod can be recreated without the other already running.
-
-  One way to prevent this is to exclude webhook A's pods from being acted on be webhook B. This
-  allows webhook A's pods to start, which in turn allows webhook B's pods to start. If you had a 
-  third webhook, webhook C, you'd need to exclude both webhook A and webhook B's pods from 
-  webhook C. This ensures that webhook A can _always_ start, which then allows webhook B's pods 
-  to start, which in turn allows webhook C's pods to start.
-
-  If you want to ensure protection that avoids these risks, [ValidatingAdmissionPolicies](/docs/reference/access-authn-authz/validating-admission-policy/)
-  can
-  provide many protection capabilities without introducing dependency cycles.
-
-* Admission webhooks can intercept resources used by critical cluster add-ons, such as CoreDNS,
-  network plugins, or storage plugins. These add-ons may be required to schedule or successfully run the
-  pods for a particular admission webhook on the cluster. This can cause a deadlock if both the 
-  webhook and critical add-on is unavailable at the same time.
-
-  You may wish to exclude cluster infrastructure namespaces from webhooks, or make sure that
-  the webhook does not depend on the particular add-on that it acts on.  For exmaple, running
-  a webhook as a host-networked pod ensures that it does not depend on a networking plugin.
-
-  If you want to ensure protection for a core add-on / or its namespace,
-  [ValidatingAdmissionPolicies](/docs/reference/access-authn-authz/validating-admission-policy/)
-  can
-  provide many protection capabilities without any dependency on worker nodes and Pods.
-
-### Side effects
-
-It is recommended that admission webhooks should avoid side effects if possible, which means the webhooks operate only on the
-content of the `AdmissionReview` sent to them, and do not make out-of-band changes. The `.webhooks[].sideEffects` field should
-be set to `None` if a webhook doesn't have any side effect.
-
-If side effects are required during the admission evaluation, they must be suppressed when processing an
-`AdmissionReview` object with `dryRun` set to `true`, and the `.webhooks[].sideEffects` field should be
-set to `NoneOnDryRun`. See [Side effects](#side-effects) for more detail.
-
-### Avoiding operating on the kube-system namespace
-
-The `kube-system` namespace contains objects created by the Kubernetes system,
-e.g. service accounts for the control plane components, pods like `kube-dns`.
-Accidentally mutating or rejecting requests in the `kube-system` namespace may
-cause the control plane components to stop functioning or introduce unknown behavior.
-If your admission webhooks don't intend to modify the behavior of the Kubernetes control
-plane, exclude the `kube-system` namespace from being intercepted using a
-[`namespaceSelector`](#matching-requests-namespaceselector).
+[Admission Webhooks Good Practices](/docs/concepts/cluster-administration/admission-webhooks-good-practices).