From 96656ea15cd40cf3f02e6975fb4ba77590eb63a8 Mon Sep 17 00:00:00 2001
From: Mehdy Bohlool <mehdy@google.com>
Date: Wed, 13 Mar 2019 12:53:50 -0700
Subject: [PATCH] Admission Webhook new features doc

- kubernetes/kubernetes#74998
- kubernetes/kubernetes#74477
- kubernetes/kubernetes#74562
---
 .../extensible-admission-controllers.md       | 31 ++++++++++++++++---
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md b/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md
index b4ca5a0696466..a5c2a0b644931 100644
--- a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md
+++ b/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