From db9f32484f58d236bae1a49d602e97ff2464f6df Mon Sep 17 00:00:00 2001 From: Bryce Palmer Date: Wed, 21 Feb 2024 11:06:07 -0500 Subject: [PATCH] Add documentation for the kapp preflight check functionality (#726) Signed-off-by: everettraven --- site/content/kapp/docs/develop/preflight.md | 24 +++++++++++++++++++++ site/data/kapp/docs/kapp-develop-toc.yml | 2 ++ 2 files changed, 26 insertions(+) create mode 100644 site/content/kapp/docs/develop/preflight.md diff --git a/site/content/kapp/docs/develop/preflight.md b/site/content/kapp/docs/develop/preflight.md new file mode 100644 index 000000000..c8cc42efb --- /dev/null +++ b/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. diff --git a/site/data/kapp/docs/kapp-develop-toc.yml b/site/data/kapp/docs/kapp-develop-toc.yml index 4ed002083..ec2f4d474 100644 --- a/site/data/kapp/docs/kapp-develop-toc.yml +++ b/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