dynamic audit documentation

content/en/docs/tasks/debug-application-cluster/audit.md

@@ -96,6 +96,7 @@ Audit backends persist audit events to an external storage.
 
 - Log backend, which writes events to a disk
 - Webhook backend, which sends events to an external API
+- Dynamic backend, which configures webhook backends through an AuditSink API object.
 
 In both cases, audit events structure is defined by the API in the
 `audit.k8s.io` API group. The current version of the API is
@@ -146,6 +147,8 @@ audit backend using the following kube-apiserver flags:
 The webhook config file uses the kubeconfig format to specify the remote address of
 the service and credentials used to connect to it.
 
+In v1.13 webhook backends can be configured [dynamically](#dynamic-backend).
+
 ### Batching
 
 Both log and webhook backends support batching. Using webhook as an example, here's the list of
@@ -199,6 +202,56 @@ available for the log backend:
 
 By default truncate is disabled in both `webhook` and `log`, a cluster administrator should set `audit-log-truncate-enabled` or `audit-webhook-truncate-enabled` to enable the feature.
 
+### Dynamic backend
+
+{{< feature-state for_k8s_version="v1.13" state="alpha" >}}
+
+In Kubernetes version 1.13, you can configure dynamic audit webhook backends AuditSink API objects. 
+
+To enable dynamic auditing you must set the following apiserver flags:
+
+- `--audit-dynamic-configuration`: the primary switch. When the feature is at GA, the only required flag.   
+- `--feature-gates=DynamicAuditing=true`: feature gate at alpha and beta.   
+- `--runtime-config=auditregistration.k8s.io/v1alpha1=true`: enable API.   
+
+When enabled, an AuditSink object can be provisioned:
+
+```yaml
+apiVersion: auditregistration.k8s.io/v1alpha1
+kind: AuditSink
+metadata:
+  name: mysink
+spec:
+  policy:
+    level: Metadata
+    stages:
+    - ResponseComplete
+  webhook:
+    throttle:
+      qps: 10
+      burst: 15
+    clientConfig:
+      url: "https://audit.app"
+```
+
+For the complete API definition, see [AuditSink](/docs/reference/generated/kubernetes-api/v1.13/#auditsink-v1alpha1-auditregistration-k8s-io). Multiple objects will exist as independent solutions.
+
+Existing static backends that you configure with runtime flags are not affected by this feature. However, the dynamic backends share the truncate options of the static webhook. If webhook truncate options are set with runtime flags, they are applied to all dynamic backends.
+
+#### Policy
+
+The AuditSink policy differs from the legacy audit runtime policy. This is because the API object serves different use cases. The policy will continue to evolve to serve more use cases.
+
+The `level` field applies the given audit level to all requests. The `stages` field is now a whitelist of stages to record.
+
+#### Security
+
+Administrators should be aware that allowing write access to this feature grants read access to all cluster data. Access should be treated as a `cluster-admin` level privilege.
+
+#### Performance
+
+Currently, this feature has performance implications for the apiserver in the form of increased cpu and memory usage. This should be nominal for a small number of sinks, and performance impact testing will be done to understand its scope before the API progresses to beta.
+
 ## Multi-cluster setup
 
 If you're extending the Kubernetes API with the [aggregation layer][kube-aggregator], you can also