Admission Webhook new features doc

- kubernetes/kubernetes#74998
- kubernetes/kubernetes#74477
- kubernetes/kubernetes#74562

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

@@ -6,6 +6,7 @@ reviewers:
 - caesarxuchao
 - deads2k
 - liggitt
+- mbohlool
 title: Dynamic Admission Control
 content_template: templates/concept
 weight: 40
@@ -66,6 +67,13 @@ that is validated in a Kubernetes e2e test. The webhook handles the
 `admissionReview` requests sent by the apiservers, and sends back its decision
 wrapped in `admissionResponse`.
 
+the `admissionReview` request can have different versions (e.g. v1beta1 or `v1` in a future version).
+The webhook can define what version they accept using `admissionReviewVersions` field. API server
+will try to use first version in the list which it supports. If none of the versions specified
+in this list supported by API server, validation will fail for this object. If the webhook
+configuration has already been persisted, calls to the webhook will fail and be
+subject to the failure policy.
+
 The example admission webhook server leaves the `ClientAuth` field
 [empty](https://github.com/kubernetes/kubernetes/blob/v1.13.0/test/images/webhook/config.go#L47-L48),
 which defaults to `NoClientCert`. This means that the webhook server does not
@@ -111,18 +119,33 @@ webhooks:
     - CREATE
     resources:
     - pods
+    scope: "Namespaced"
   clientConfig:
     service:
       namespace: <namespace of the front-end service>
       name: <name of the front-end service>
+      port: 443
     caBundle: <pem encoded ca cert that signs the server cert used by the webhook>
+  admissionReviewVersions:
+  - v1beta1
+  timeoutSeconds: 1
 ```
 
+The scope field specifies if only cluster-scoped resources ("Cluster") or namespace-scoped resources
+will match this rule. "*" means that there are no scope restrictions.
+
 {{< note >}}
 When using `clientConfig.service`, the server cert must be valid for
 `<svc_name>.<svc_namespace>.svc`.
 {{< /note >}}
 
+{{< note >}}
+Default timeout for a webhook call is 30 seconds but starting kubernetes 1.14 you
+can set the timeout and it is encouraged to use a very small timeout for webhooks.
+If the webhook call timed out, it will be ignored or the API call will fail based
+on the failure policy.
+{{< /note >}}
+
 When an apiserver receives a request that matches one of the `rules`, the
 apiserver sends an `admissionReview` request to webhook as specified in the
 `clientConfig`.
@@ -131,10 +154,10 @@ After you create the webhook configuration, the system will take a few seconds
 to honor the new configuration.
 
 {{< note >}}
-When the webhook plugin is deployed into the Kubernetes cluster as a
-service, it has to expose its service on the 443 port. The communication
-between the API server and the webhook service may fail if a different port
-is used.
+Starting from kubernetes 1.14, apiserver can communicate on any port to deployed
+webhook services in kubernetes. Prior to that, the webhook service had to expose
+its service on the 443 port. Using port 443 for kubernetes 1.14 make sense if there
+is a chance of rolling back cluster to a prior version.
 {{< /note >}}
 
 ### Authenticate apiservers