adding auditing docs

site/content/docs/contributing/1.0-roadmap.md

@@ -46,8 +46,6 @@ To reach "GA" [grade][deprecation-policy] kind needs to at minimum:
 - [x] Support non-AMD64 architectures (namely ARM) - [#166]
 - [ ] Automated publishing of Kubernetes release based kind "node" images - [#197]
 - [x] Support for runtimes other than docker/default including podman, ignite etc.
-- [ ] Enable audit-logging
-  - TODO: should this be post-GA? this could probably be an extension
 - [x] First class support for skewed node (Kubernetes) versions (I believe this is relatively first-class now, things should work fine if you specify different node images)
 - ... TBD, more will be added here ...
 

site/content/docs/user/auditing.md

@@ -0,0 +1,150 @@
+---
+title: "Auditing"
+menu:
+  main:
+    parent: "user"
+    identifier: "user-auditing"
+    weight: 3
+description: |-
+    This guide covers how to enable Kubernetes API [auditing] on a kind cluster.
+
+    [auditing]: https://kubernetes.io/docs/tasks/debug-application-cluster/audit/
+---
+
+## Overview
+
+Kubernetes auditing provides a security-relevant, chronological set of records documenting the sequence of actions in a cluster. Auditing requires a file to define the [audit policy] and a backend configuration to store the logged events. Auditing supports two types of backends: log (file) & webhook. The following exercise uses the log backend.
+
+Steps:
+
+- Create the audit policy files and directory
+- Mount the local audit directory into the kind control plane
+- Expose the control plane mounts to the API server
+- Enable the auditing API flags
+- Create a cluster
+
+## Setup
+
+### Create a directory for API auditing files
+
+{{< codeFromInline lang="bash" >}}
+mkdir /tmp/api/
+{{< /codeFromInline >}}
+
+{{< securitygoose >}}
+Do not use the `/tmp` directory for your audit logs in production because it's generally accessible by all users of a system. This tutorial is for local testing and demonstration purposes only.
+{{</ securitygoose >}}
+
+### Create an `audit-policy.yaml` file
+
+The [audit policy] defines the level of granularity outputted by the Kubernetes API server. The example below logs all requests at the "Metadata" level. See the [audit policy] docs for more examples. 
+
+{{< codeFromInline lang="bash" >}}
+cat <<EOF > /tmp/api/audit-policy.yaml
+apiVersion: audit.k8s.io/v1
+kind: Policy
+rules:
+- level: Metadata
+EOF
+{{< /codeFromInline >}}
+
+### Create a `kind-config.yaml` file.
+
+To enable audit logging, use kind's [configuration file] to pass additional setup instructions. Kind uses `kubeadm` to provision the cluster and the configuration file has the ability to pass `kubeadmConfigPatches` for further customization.
+
+{{< codeFromInline lang="bash" >}}
+cat <<EOF > kind-config.yaml
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+  kubeadmConfigPatches:
+  - |
+    kind: ClusterConfiguration
+    apiServer:
+        # enable auditing flags on the API server
+        extraArgs:
+          audit-log-path: /etc/kubernetes/audit/audit.log
+          audit-policy-file: /etc/kubernetes/audit/audit-policy.yaml
+        # mount the control plane exposed directory
+        extraVolumes:
+          - name: audit-policy
+            hostPath: /etc/kubernetes/audit
+            mountPath: /etc/kubernetes/audit
+            readOnly: false
+            pathType: "DirectoryOrCreate"
+  # expose the local directory to the control plane
+  extraMounts:
+  - hostPath: /tmp/api/
+    containerPath: /etc/kubernetes/audit
+    # need "write" ability for log files
+    readOnly: false
+    selinuxRelabel: false
+    propagation: None
+EOF
+{{< /codeFromInline >}}
+
+### Validate your directory is clean
+
+This optional step ensures that no previous log files exist and the audit policy file is present.
+
+```bash
+$ ls -lah /tmp/api/
+total 12K
+drwxrwxr-x  2 user user 4.0K Aug 20 02:05 .
+drwxrwxrwt 14 root   root   4.0K Aug 20 02:09 ..
+-rw-rw-r--  1 user user  108 Aug 20 01:49 audit-policy.yaml
+```
+
+## Launch a new cluster
+
+{{< codeFromInline lang="bash" >}}
+kind create cluster --config kind-config.yaml
+{{< /codeFromInline >}}
+
+## View audit logs
+
+Once the cluster is running, view the log files in `/tmp/api/audit.log` depending on your container runtime configuration `sudo` may or may not be necessary.
+
+{{< codeFromInline lang="bash" >}}
+sudo cat /tmp/api/audit.log
+{{< /codeFromInline >}}
+
+## Troubleshooting
+
+If logs are not present, let's ensure a few things are in place.
+
+### Is the local directory mounted in the control-plane?
+
+{{< codeFromInline lang="bash" >}}
+docker exec kind-control-plane ls /etc/kubernetes/audit
+{{< /codeFromInline >}}
+
+Expected output:
+
+```bash
+audit-policy.yaml
+audit.log
+```
+
+### Does the API server contain the mounts and arguments?
+
+{{< codeFromInline lang="bash" >}}
+docker exec kind-control-plane cat /etc/kubernetes/manifests/kube-apiserver.yaml | grep audit
+{{< /codeFromInline >}}
+
+Expected output:
+
+```bash
+    - --audit-log-path=/etc/kubernetes/audit/audit.log
+    - --audit-policy-file=/etc/kubernetes/audit/audit-policy.yaml
+    - mountPath: /etc/kubernetes/audit
+      name: audit-policy
+      path: /etc/kubernetes/audit
+    name: audit-policy
+```
+
+If the control plane requires further debugging use `docker exec -it kind-control-plane bash` to start an interactive terminal session with the container.
+
+[audit policy]: https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#audit-policy
+[configuration file]: /docs/user/configuration