Add webhook admission outline

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

@@ -12,6 +12,8 @@ content_template: templates/concept
 weight: 40
 ---
 
+{{< toc >}}
+
 {{% capture overview %}}
 The [admission controllers documentation](/docs/reference/access-authn-authz/admission-controllers/)
 introduces how to use standard, plugin-style admission controllers. However,
@@ -36,9 +38,9 @@ something with them. You can define two types of admission webhooks,
 [validating admission Webhook](/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook)
 and
 [mutating admission webhook](/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook).
-With validating admission Webhooks, you may reject requests to enforce custom
-admission policies. With mutating admission Webhooks, you may change requests to
-enforce custom defaults.
+Mutating admission Webhooks are invoked first, and can modify objects sent to the API server to enforce custom defaults.
+After all object modifications are complete, and after the incoming object is validated by the API server,
+validating admission Webhooks are invoked and can reject requests to enforce custom policies.
 
 ### Experimenting with admission webhooks
 
@@ -48,7 +50,7 @@ guides](/docs/reference/access-authn-authz/extensible-admission-controllers/#wri
 instructions if you intend to write/deploy production-grade admission webhooks.
 In the following, we describe how to quickly experiment with admission webhooks.
 
-### Prerequisites
+#### Prerequisites
 
 * Ensure that the Kubernetes cluster is at least as new as v1.9.
 
@@ -59,7 +61,7 @@ In the following, we describe how to quickly experiment with admission webhooks.
 
 * Ensure that the admissionregistration.k8s.io/v1beta1 API is enabled.
 
-### Write an admission webhook server
+#### Write an admission webhook server
 
 Please refer to the implementation of the [admission webhook
 server](https://github.com/kubernetes/kubernetes/blob/v1.13.0/test/images/webhook/main.go)
@@ -81,7 +83,7 @@ authenticate the identity of the clients, supposedly apiservers. If you need
 mutual TLS or other ways to authenticate the clients, see
 how to [authenticate apiservers](#authenticate-apiservers).
 
-### Deploy the admission webhook service
+#### Deploy the admission webhook service
 
 The webhook server in the e2e test is deployed in the Kubernetes cluster, via
 the [deployment API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#deployment-v1beta1-apps).
@@ -92,7 +94,7 @@ as the front-end of the webhook server. See
 You may also deploy your webhooks outside of the cluster. You will need to update
 your [webhook client configurations](https://github.com/kubernetes/kubernetes/blob/v1.13.0/staging/src/k8s.io/api/admissionregistration/v1beta1/types.go#L247) accordingly.
 
-### Configure admission webhooks on the fly
+#### Configure admission webhooks on the fly
 
 You can dynamically configure what resources are subject to what admission
 webhooks via
@@ -152,7 +154,7 @@ apiserver sends an `admissionReview` request to webhook as specified in the
 After you create the webhook configuration, the system will take a few seconds
 to honor the new configuration.
 
-### Authenticate apiservers
+#### Authenticate apiservers
 
 If your admission webhooks require authentication, you can configure the
 apiservers to use basic auth, bearer token, or a cert to authenticate itself to
@@ -210,4 +212,46 @@ users:
 ```
 
 Of course you need to set up the webhook server to handle these authentications.
+
+### API Reference
+
+To register admission webhooks, create `MutatingWebhookConfiguration` or `ValidatingWebhookConfiguration` API objects.
+Each configuration can contain one or more webhooks. Each webhook defines the following things.
+
+#### Matching requests
+
+TODO: rules docs and examples
+
+TODO: namespaceSelector docs and example
+
+TODO: objectSelector docs and example
+
+TODO: matchPolicy docs and example
+
+TODO: other examples
+
+#### Contacting the webhook
+
+TODO: clientConfig docs and examples
+
+#### Webhook payload and response
+
+TODO: admissionReviewVersions and AdmissionReview docs and examples
+
+#### Side effects
+
+TODO: sideEffects docs and examples
+
+#### Timeouts
+
+TODO: timeout docs and examples
+
+#### Reinvocation policy
+
+TODO: reinvocationPolicy docs and examples
+
+#### Failure policy
+
+TODO: failurePolicy docs and examples
+
 {{% /capture %}}

content/en/docs/setup/version-skew-policy.md

@@ -113,7 +113,7 @@ Pre-requisites:
 * The `kube-controller-manager`, `kube-scheduler`, and `cloud-controller-manager` instances that communicate with this server are at version **1.n** (this ensures they are not newer than the existing API server version, and are within 1 minor version of the new API server version)
 * `kubelet` instances on all nodes are at version **1.n** or **1.(n-1)** (this ensures they are not newer than the existing API server version, and are within 2 minor versions of the new API server version)
 * Registered admission webhooks are able to handle the data the new `kube-apiserver` instance will send them:
-  * `ValidatingWebhookConfiguration` and `MutatingWebhookConfiguration` objects are updated to include any new versions of REST resources added in **1.(n+1)**
+  * `ValidatingWebhookConfiguration` and `MutatingWebhookConfiguration` objects are updated to include any new versions of REST resources added in **1.(n+1)** (or use the [`matchPolicy: Equivalent` option](/docs/reference/access-authn-authz/extensible-admission-controllers/#match-policy) available in v1.15+)
   * The webhooks are able to handle any new versions of REST resources that will be sent to them, and any new fields added to existing versions in **1.(n+1)**
 
 Upgrade `kube-apiserver` to **1.(n+1)**