update RBAC customizations and sub-project info (#1320)

* update RBAC customizations and sub-project info Signed-off-by: Jim Bugwadia <[email protected]> * fix links Signed-off-by: Jim Bugwadia <[email protected]> * fix links Signed-off-by: Jim Bugwadia <[email protected]> * update title Signed-off-by: Jim Bugwadia <[email protected]> * update quick start for generating secrets Signed-off-by: Jim Bugwadia <[email protected]> * reduce generate perms Signed-off-by: Jim Bugwadia <[email protected]> --------- Signed-off-by: Jim Bugwadia <[email protected]>
kyverno · Aug 26, 2024 · 2ee7df0 · 2ee7df0
1 parent cff961a
commit 2ee7df0
Show file tree

Hide file tree

Showing 9 changed files with 435 additions and 331 deletions.
diff --git a/config/_default/menus/menu.en.toml b/config/_default/menus/menu.en.toml
@@ -3,7 +3,7 @@
 [[main]]
   name = "About"
   weight = -103
-  url = "#kyverno-is-a-policy-engine-designed-for-kubernetes"
+  url = "#about-kyverno"
 
 [[main]]
   name = "Documentation"

diff --git a/content/en/_index.md b/content/en/_index.md
@@ -4,7 +4,7 @@ linkTitle = "Kyverno"
 +++
 
 {{< blocks/cover title="Kyverno" image_anchor="top" height="full" color="dark" >}}
-# Cloud Native Policy Management { class="text-center" }
+# Policy Management. Simplified. { class="text-center" }
 
 <div class="mt-5 mx-auto">
 	<a class="btn btn-lg btn-primary mr-3 mb-4" href="#about-kyverno">
@@ -28,14 +28,22 @@ linkTitle = "Kyverno"
 <br/>
 
 <h2>
-Kyverno is a policy engine built for Kubernetes and cloud native environments.
+Policy Management for Kubernetes and cloud native environments.
 </h2>
 <br/>
 
 <p style="line-height:1.5">
-Kyverno policies are declarative Kubernetes resources and <b>no new language</b> is required to write policies. This allows using familiar tools such as <code style="font-size: 1.35rem">kubectl</code>, <code style="font-size: 1.35rem">git</code>, and <code style="font-size: 1.35rem">kustomize</code> to manage policies. Kyverno policies can <b>validate, mutate, generate, and cleanup</b> any Kubernetes resource, including custom resrources. To help secure the software supply chain Kyverno policies can <b>verify OCI container image signatures and artifacts</b>.
+Kyverno policies are declarative YAML resources and <b>no new language</b> is required to write policies. This allows using familiar tools such as <code style="font-size: 1.35rem">kubectl</code>, <code style="font-size: 1.35rem">git</code>, and <code style="font-size: 1.35rem">kustomize</code> to manage policies. For efficient handling of complex logic, Kyverno supports both JMESPath and the Common Expressions Language (CEL) languages. 
 
-The **Kyverno CLI** can be used to test policies and validate resources off-cluster e.g. as part of a CI/CD pipeline. Kyverno policy reports and policy exceptions are also Kubernetes resources. The **Policy Reporter**  provides in-cluster report management with a graphical web-based user interface. **Kyverno JSON** allows applying Kyverno policies in non-Kubernetes environments and on any JSON payload. **Kyverno Chainsaw** provides declarative end-to-end testing for policies and controllers. 
+In Kubernetes environments, Kyverno policies can <b>validate, mutate, generate, and cleanup</b> any Kubernetes resource, including custom resources. To help secure the software supply chain Kyverno policies can <b>verify OCI container image signatures and artifacts</b>. Kyverno policy reports and policy exceptions are also Kubernetes API resources.
+
+The **Kyverno CLI** can be used to apply and test policies off-cluster e.g., as part of a CI/CD pipeline. 
+
+**Kyverno Policy Reporter**  provides in-cluster report management with a graphical web-based user interface. 
+
+**Kyverno JSON** allows applying Kyverno policies in non-Kubernetes environments and on any JSON payload.
+
+**Kyverno Chainsaw** provides declarative end-to-end testing for policies. 
 </p>
 
 <div class="mt-5 mx-auto">

diff --git a/content/en/docs/installation/customization.md b/content/en/docs/installation/customization.md
@@ -153,10 +153,14 @@ Kyverno uses Secrets created above to setup TLS communication with the Kubernete
 
 You can now install Kyverno by selecting one of the available methods from the [installation section](methods.md).
 
-### Roles and Permissions
+### Role Based Access Controls
 
-Kyverno creates several Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings some of which may need to be customized depending on additional functionality required. To view all ClusterRoles and Roles associated with Kyverno, use the command `kubectl get clusterroles,roles -A | grep kyverno`.
+Kyverno uses Kubernetes Role Based Access Controls (RBAC) to configure permissions for Kyverno controllers to allow access to other resources.
 
+Kyverno creates several Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings some of which may need to be customized depending on additional functionality required. 
+
+To view all ClusterRoles and Roles associated with Kyverno, use the command `kubectl get clusterroles,roles -A | grep kyverno`.
+
 #### Roles
 
 Kyverno creates the following Roles in its Namespace, one per controller type:
@@ -183,84 +187,138 @@ Kyverno uses [aggregated ClusterRoles](https://kubernetes.io/docs/reference/acce
 
 The following `ClusterRoles` provide Kyverno with permissions to policies and other Kubernetes resources across all Namespaces.
 
-* `kyverno:admission-controller:core`: aggregate ClusterRole for the admission controller
-* `kyverno:admission-controller`: aggregated (top-level) ClusterRole for the admission controller
-* `kyverno:reports-controller:core`: aggregate ClusterRole for the reports controller
-* `kyverno:reports-controller`: aggregated (top-level) ClusterRole for the reports controller
-* `kyverno:background-controller:core`: aggregate ClusterRole for the background controller
-* `kyverno:background-controller`: aggregated (top-level) ClusterRole for the background controller
-* `kyverno:cleanup-controller:core`: aggregate ClusterRole for the cleanup controller
-* `kyverno:cleanup-controller`: aggregated (top-level) ClusterRole for the cleanup controller
-* `kyverno-cleanup-jobs`: used by the helper CronJob to periodically remove excessive/stale admission reports if found
-* `kyverno:rbac:admin:policies`: aggregates to admin the ability to fully manage Kyverno policies
-* `kyverno:rbac:admin:policyreports`: aggregates to admin the ability to fully manage Policy Reports
-* `kyverno:rbac:admin:reports`: aggregates to admin the ability to fully manage intermediary admission and background reports
-* `kyverno:rbac:admin:updaterequests`: aggregates to admin the ability to fully manage UpdateRequests, intermediary resource for generate rules
-* `kyverno:rbac:view:policies`: aggregates to view the ability to view Kyverno policies
-* `kyverno:rbac:view:policyreports`: aggregates to view the ability to view Policy Reports
-* `kyverno:rbac:view:reports`: aggregates to view the ability to view intermediary admission and background reports
-* `kyverno:rbac:view:updaterequests`: aggregates to view the ability to view UpdateRequests, intermediary resource for generate rules
+Role Binding                       |        Service Account               | Role
+---------------------------------- | ------------------------------------ | -------------
+kyverno:admission-controller       | kyverno-admission-controller         | kyverno:admission-controller
+kyverno:admission-controller:view  | kyverno-admission-controller         | view
+kyverno:admission-controller:core  | --         | --
+kyverno:background-controller      | kyverno-background-controller        | kyverno:background-controller
+kyverno:background-controller:view | kyverno-background-controller        | view
+kyverno:background-controller:core | --        | --
+kyverno:cleanup-controller         |  kyverno-cleanup-controller          | kyverno:cleanup-controller
+kyverno:cleanup-controller:core    |  --         | --
+kyverno:reports-controller         |  kyverno-reports-controller          | kyverno:reports-controller
+kyverno:reports-controller:view    |  kyverno-reports-controller          | view
+kyverno:reports-controller:core    |  --          | --
+
 
 {{% alert title="Note" color="info" %}}
-Most Kyverno controllers' ClusterRoles include a rule which allows for `get`, `list`, and `read` permissions to all resources in the cluster. This is to ensure Kyverno functions smoothly despite the type and subject of future-installed policies. If this rule is removed, users must manually create and manage a number of different ClusterRoles applicable across potentially multiple controllers depending on the type and configuration of installed policies.
+The Kyverno admission, background, and reports controller have a role binding to the built-in `view` role. This allows these Kyverno controllers view access to most namespaced resources. You can customize this role during Helm installation using variables like `admissionController.rbac.viewRoleName`. 
 {{% /alert %}}
 
 #### Customizing Permissions
 
-Because the ClusterRoles used by Kyverno use the [aggregation feature](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles), extending the permission for Kyverno's use in cases like mutate existing or generate rules or generating ValidatingAdmissionPolicies is a simple matter of creating one or more new ClusterRoles which use the appropriate labels. It is not necessary to modify any existing ClusterRoles created as part of the Kyverno installation. Doing so is not recommended as changes may be lost during an upgrade. Since there are multiple controllers each with their own ServiceAccount, granting Kyverno additional permissions involves identifying the correct controller and using the labels needed to aggregate to that ClusterRole.
+Kyverno's default permissions are designed to cover commonly used and security non-critical resources. Hence, Kyverno will need to be configured with additional permissions for CRDs, or to allow access to security critical resources.
+
+The ClusterRoles installed by Kyverno use the [cluster role aggregation feature](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles), making it easy to extend the permissions for Kyverno's controllers. To extend a controller's permissions, add a new role with one or more of the following labels:
+
+Controller             | Role Aggregation Label              
+---------------------- | -----------------------------
+admission-controller   | rbac.kyverno.io/aggregate-to-admission-controller: "true"
+background-controller  | rbac.kyverno.io/aggregate-to-background-controller: "true"
+reports-controller     | rbac.kyverno.io/aggregate-to-reports-controller: "true"
+cleanup-controller     | rbac.kyverno.io/aggregate-to-cleanup-controller: "true"
+
+To avoid upgrade issues, it is highly recommended that default roles are not modified but new roles are used to extend them.
 
-For example, if a new Kyverno generate policy requires that Kyverno be able to create or modify Deployments, this is not a permission Kyverno has by default. Generate rules are handled by the background controller and so it will be necessary to create a new ClusterRole and assign it the aggregation labels specific to the background controller in order for those permissions to take effect.
+Since there are multiple controllers each with their own ServiceAccount, granting Kyverno additional permissions involves identifying the correct controller and using the labels needed to aggregate to that ClusterRole. The table below identifies required permissions for Kyverno features:
+
+Controller             | Permission Verbs | Required For              
+---------------------- | ----- | ------------------------------- 
+admission-controller   | view, list, ... | API Calls 
+admission-controller   | view, list, watch | Global Context
+background-controller  | update, view, list, watch | Mutate Policies
+background-controller  | create, update, delete, view, list, watch | Generate Policies
+reports-controller     | view, list, watch | Policy Reports
+cleanup-controller     | delete, view, list, watch | Cleanup Policies
+
+
+For example, if a new Kyverno generate policy requires that Kyverno be able to create and update Deployments, new permissions need to be provided. Generate rules are handled by the background controller and so it will be necessary to create a new ClusterRole and assign it the aggregation labels specific to the background controller in order for those permissions to take effect.
 
 This sample ClusterRole provides the Kyverno background controller additional permissions to create Deployments:
 
 ```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
-  labels:
-    app.kubernetes.io/component: background-controller
-    app.kubernetes.io/instance: kyverno
-    app.kubernetes.io/part-of: kyverno
   name: kyverno:create-deployments
+  labels:
+    rbac.kyverno.io/aggregate-to-background-controller: "true"  
 rules:
 - apiGroups:
   - apps
   resources:
   - deployments
   verbs:
   - create
+  - update
 ```
 
-Once a supplemental ClusterRole has been created, get the top-level ClusterRole for that controller to ensure aggregation has occurred.
+Once a supplemental ClusterRole has been created, check the top-level ClusterRole for that controller to ensure aggregation has occurred.
 
 ```sh
 kubectl get clusterrole kyverno:background-controller -o yaml
 ```
 
-Generating Kubernetes ValidatingAdmissionPolicies and their bindings are handled by the admission controller and it will be necessary to grant the controller the required permissions to generate these types. In this scenario, a ClusterRole should be created and assigned the aggregation labels for the admission controller in order for those permissions to take effect.
+Similary, if a Kyverno validate and mutate policies operates on a custom resource the background and reports controllers needs to be provided permissions to manage the resource:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: kyverno:crontab:edit
+  labels:
+    rbac.kyverno.io/aggregate-to-background-controller: "true"
+rules:
+- apiGroups:
+  - stable.example.com
+  resources:
+  - crontabs
+  verbs:
+  - update
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: kyverno:crontab:view
+  labels:
+    rbac.kyverno.io/aggregate-to-background-controller: "true"
+    rbac.kyverno.io/aggregate-to-reports-controller: "true"
+rules:
+- apiGroups:
+  - stable.example.com
+  resources:
+  - crontabs
+  verbs:
+  - get
+  - list
+  - watch
+```
+
+Generating Kubernetes ValidatingAdmissionPolicies and their bindings are handled by the admission controller and it is necessary to grant the controller the required permissions to generate these types. For this, a ClusterRole should be created and assigned the aggregation labels for the admission controller in order for those permissions to take effect.
 
 This sample ClusterRole provides the Kyverno admission controller additional permissions to create ValidatingAdmissionPolicies and ValidatingAdmissionPolicyBindings:
 
 ```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
-  labels:
-    app.kubernetes.io/component: admission-controller
-    app.kubernetes.io/instance: kyverno
-    app.kubernetes.io/part-of: kyverno
   name: kyverno:generate-validatingadmissionpolicy
+  labels:
+    rbac.kyverno.io/aggregate-to-admission-controller: "true"
 rules:
 - apiGroups:
   - admissionregistration.k8s.io
   resources:
   - validatingadmissionpolicies
   - validatingadmissionpolicybindings
   verbs:
+  - get
+  - list
+  - watch
   - create
   - update
   - delete
-  - list
 ```
 
 ### ConfigMap Keys