Add ImagePolicyWebhook docs

docs/admin/admission-controllers.md

@@ -78,6 +78,114 @@ If your cluster supports containers that run with escalated privileges, and you
 restrict the ability of end-users to exec commands in those containers, we strongly encourage
 enabling this plug-in.
 
+### ImagePolicyWebhook
+
+This plug-in will allow admission decisions to be made by a backend webhook.
+
+#### Configuration File Format
+It uses the admission controller config file (`--admission-controller-config-file`) to set configuration options for the behavior of the backend. This file may be json or yaml and has the following format:
+
+```javascript
+{
+  "imagePolicy": {
+     "kubeConfigFile": "path/to/kubeconfig/for/backend",
+     "allowTTL": 50,           // time in s to cache approval
+     "denyTTL": 50,            // time in s to cache denial
+     "retryBackoff": 500,      // time in ms to wait between retries
+     "defaultAllow": true      // determines behavior if the webhook backend fails
+  }
+}
+```
+
+The config file must reference a [kubeconfig](/docs/user-guide/kubeconfig-file/) formatted file which sets up the connection to the backend. It is required that the backend communicate over TLS.
+
+The kubeconfig's cluster field is used to refer to the remote service, user refers to the returned authorizer.
+
+```yaml
+# clusters refers to the remote service.
+clusters:
+- name: name-of-remote-imagepolicy-service
+  cluster:
+    certificate-authority: /path/to/ca.pem    # CA for verifying the remote service.
+    server: https://images.example.com/policy # URL of remote service to query. Must use 'https'.
+
+# users refers to the API server's webhook configuration.
+users:
+- name: name-of-api-server
+  user:
+    client-certificate: /path/to/cert.pem # cert for the webhook plugin to use
+    client-key: /path/to/key.pem          # key matching the cert
+```
+For additional HTTP configuration, refer to the [kubeconfig](/docs/user-guide/kubeconfig-file/) documentation.
+
+#### Request Payloads
+
+When faced with an admission decision, the API Server POSTs a JSON serialized api.imagepolicy.v1alpha1.ImageReview object describing the action. This object contains fields describing the containers being admitted, as well as any pod annotations that match `*.image-policy.k8s.io/*`.
+
+Note that webhook API objects are subject to the same versioning compatibility rules as other Kubernetes API objects. Implementers should be aware of looser compatibility promises for alpha objects and check the “apiVersion” field of the request to ensure correct deserialization. Additionally, the API Server must enable the imagepolicy.k8s.io/v1alpha1 API extensions group (`--runtime-config=imagepolicy.k8s.io/v1alpha1=true`).
+
+An example request body:
+
+```
+{  
+  "apiVersion":"imagepolicy.k8s.io/v1alpha1",
+  "kind":"ImageReview",
+  "spec":{  
+    "containers":[  
+      {  
+        "image":"myrepo/myimage:v1"
+      },
+      {  
+        "image":"myrepo/myimage@sha256:beb6bd6a68f114c1dc2ea4b28db81bdf91de202a9014972bec5e4d9171d90ed"
+      }
+    ],
+    "annotations":[  
+      "mycluster.image-policy.k8s.io/ticket-1234": "break-glass"
+    ],
+    "namespace":"mynamespace"
+  }
+}
+```
+
+The remote service is expected to fill the ImageReviewStatus field of the request and respond to either allow or disallow access. The response body’s “spec” field is ignored and may be omitted. A permissive response would return:
+
+```
+{
+  "apiVersion": "imagepolicy.k8s.io/v1alpha1",
+  "kind": "ImageReview",
+  "status": {
+    "allowed": true
+  }
+}
+```
+
+To disallow acceess, the service would return:
+
+```
+{
+  "apiVersion": "imagepolicy.k8s.io/v1alpha1",
+  "kind": "ImageReview",
+  "status": {
+    "allowed": false,
+    "reason": "image currently blacklisted"
+  }
+}
+```
+
+For further documentation refer to the `imagepolicy.v1alpha1` API objects and `plugin/pkg/admission/imagepolicy/admission.go`.
+
+#### Extending with Annotations
+
+All annotations on a Pod that match `*.image-policy.k8s.io/*` are sent to the webhook. Sending annotations allows users who are aware of the image policy backend to send extra information to it, and for different backends implementations to accept different information.
+
+Examples of information you might put here are:
+
+ * request to "break glass" to override a policy, in case of emergency.
+ * a ticket number from a ticket system that documents the break-glass request
+ * provide a hint to the policy server as to the imageID of the image being provided, to save it a lookup
+
+In any case, the annotations are provided by the user and are not validated by Kubernetes in any way. In the future, if an annotation is determined to be widely useful, it may be promoted to a named field of ImageReviewSpec.
+
 ### ServiceAccount
 
 This plug-in implements automation for [serviceAccounts](/docs/user-guide/service-accounts).