Add documentation for the kapp preflight check functionality (#726)

Signed-off-by: everettraven <[email protected]>

site/content/kapp/docs/develop/preflight.md

@@ -0,0 +1,24 @@
+---
+title: Preflight Checks
+---
+
+## Overview
+
+Once the change set is calculated (see [Diff](diff.md) section for details), kapp will run any of the optional preflight checks that have been enabled.
+
+If all enabled preflight checks are successful, kapp will continue to apply the changes in the change set (see [Apply](apply.md) section for further details).
+
+Preflight checks are enabled using the new `--preflight` flag when running `kapp deploy...` or `kapp app-group deploy...`. The `--preflight` flag follows the pattern `--preflight=CheckName=true,OtherCheck=false,...` to enable/disable preflight checks.
+
+Currently available preflight checks are:
+- `PermissionValidation` - *disabled by default* - Validates that a user has the permissions necessary to apply the changes in the change set. If a user does not have the appropriate permissions the preflight check will fail and no changes will be applied to the cluster.
+
+## PermissionValidation
+
+The `PermissionValidation` preflight check validates that a user has the permissions necessary to apply the changes in the change set to the cluster. If a user does not have the appropriate permissions to apply *all* of the changes, this check will fail and result in no changes being applied to the cluster.
+
+This preflight check is disabled by default but can be enabled with `--preflight=PermissionValidation=true` when running `kapp deploy...` or `kapp app-group deploy...`.
+
+The following permission checks are run when this check is enabled:
+- For all resources, verification that a user has the permissions to perform the change operation (`create`, `update`, `delete`).
+- For `ClusterRole`, `ClusterRoleBinding`, `Role`, and `RoleBinding` resources, verification that no privilege escalation occurs. This is done by checking each rule specified in the `(Cluster)Role` resource (or in the case of `(Cluster)RoleBinding` the referenced `(Cluster)Role`) and ensuring that a user has the same level of permissions. This check also accounts for users with the `escalate` and `bind` permissions that are allowed to perform privilege escalation.

site/data/kapp/docs/kapp-develop-toc.yml

@@ -17,6 +17,8 @@ toc:
         url: /apply-ordering
       - page: Apply Waiting
         url: /apply-waiting
+      - page: Preflight Checks
+        url: /preflight
   - title: Reference
     subfolderitems:
       - page: Configuration