fine grained rbac

release_notes/acm_whats_new.adoc

@@ -51,6 +51,8 @@ See link:../console/console_intro.adoc#web-console[Web console] for more informa
 
 For new features that are related specifically to {mce-short}, see link:../clusters/release_notes/mce_whats_new.adoc#whats-new-mce[What's new for Cluster lifecycle with {mce-short}] in the _Cluster_ section of the documentation.
 
+- *Technolgy Preview:* Grant more specific permissions with fine-grained role-based access for your virtual machines. As a cluster administrator, you can manage and control permissions that are based on the namespace of a managed cluster, as well as the entire cluster. You can also grant permissions for individual virtual machines. See link:../secure_clusters/fine_grain_rbac.adoc/#fine-grain-rbac[Managing fine-grained role-based access control (Technology Preview)] for information.
+
 - You can now configure resource requests and limits on all add-ons. To learn more, see link:../add-ons/configure_klusterlet_addons.adoc#configure-klusterlet-addons[Configuring klusterlet add-ons].
 
 View other Cluster tasks and support information at link:../clusters/about/cluster_mce_overview.adoc#cluster_mce_overview[Cluster lifecycle with {mce-short} overview]. 

secure_cluster/fine_grain_rbac_cli.adoc

@@ -0,0 +1,199 @@
+[#fine-grain-rbac-cli]
+= Implementing fine-grained role-based access control in the terminal (Technology Preview)
+
+*Technology Preview:* {acm} supports fine-grained role-based access control (RBAC). As a cluster administrator, you can manage and control permissions with the `ClusterPermission` resource, which controls permissions at the namespace level on managed clusters, rather than at the cluster level. Grant permissions to a virtual machine namespace within a cluster without granting permission to the entire managed cluster, or virtual machine. 
+
+Learn how to set up for fine-grained role-based access control (RBAC) and the `ClusterPermission` resource from the terminal.
+
+*Required access:* Cluster administrator
+
+To learn about {ocp-short} default and virtualization roles and permissions, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/virtualization/about#authorization_virt-security-policies[Authorization] in the {ocp-short} documentation.
+
+See xref:../secure_cluster/rbac_implement_rhacm.adoc#rhacm-rbac-implement[Implementing role-based access control] for more details about {acm-short} role-based access.
+
+.Prerequisites
+
+See the following requirements to begin using fine-grained role-based access control:
+
+. Your `MultiClusterHub` custom resource `spec.overrides.components` field for `search` must `enabled` to retrieve a list of managed clusters namespaces that can represent virtual machines that are used for access control.
+. You need virtual machines.
+
+[#assign-fine-grain-rbac]
+== Assigning fine-grained role-based access control in the terminal
+
+You can grant access to the following roles for {ocp-virt-short}, which are extensions of the default roles:
+
+- `kubevirt.io:view`: only view resources
+- `kubevirt.io:edit`: modify resources
+- `kubevirt.io:admin`: view, modify, delete resources; grant permissions
+
+. Enable `fine-grained-rbac-preview` in the `MultiClusterHub` resource. 
+
+.. Run the following command:
+
++
+[source,bash]
+----
+oc edit mch -n open-cluster-management multiclusterhub
+----
+
+.. Edit to change the `configOverrides` specification from `enabled: false` to `enabled: true`. See the following example with the feature enabled:
+
++
+[source,yaml]
+----
+ - configOverrides: {}
+      enabled: true
+      name: fine-grained-rbac-preview
+----
+
++
+*Note:* Run `oc get mch -A` to get  the name and namespace of the `MultiClusterHub` resource if you do not use the `open-cluster-management` namespace.
+
+. Label your `local-cluster` with `environment=virtualization`. Run the following command:
++
+[source,bash]
+----
+oc label managedclusters local-cluster environment=virtualization
+----
+
+. Change the `policy-virt-clusterroles` to `enforce`, which adds the `kubevirt` `clusterroles` to the hub cluster. 
+
+.. Run the following command to get the policy:
+
++
+[source,bash]
+----
+oc get policy -n open-cluster-management-global-set policy-virt-clusterroles
+----
+
++
+.. Edit the `remediationAction` value from `inform` to `enforce`. *Important:* Two `remediationAction` specifications are in the policy, but you only need to change the later `remediationAction`. This does not apply to the first template in the YAML file. See the following sample:
+
++
+[source,yaml]
+----
+  remediationAction: enforce
+----
+
+. Create the following YAML file and name the file `acm-vm-rbac-required.yml` for later steps in the procedure. You can use a different name. If you choose a different name, you need to use it throughout the procedure:
+
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: acm-vm-rbac-required <1>
+rules:
+  - apiGroups: ["clusterview.open-cluster-management.io"]
+    resources: ["kubevirtprojects"]
+    verbs: ["list"]
+  - apiGroups: ["clusterview.open-cluster-management.io"]
+    resources: ["managedclusters"]
+    verbs: ["list","get","watch"]
+  - apiGroups: ["cluster.open-cluster-management.io"]
+    resources: ["managedclusters"]
+    verbs: ["get"]
+    resourceNames: ["cluster01", "cluster02", "cluster03"] <2>
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: acm-vm-rbac-required <3>
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: acm-vm-rbac-required <4> 
+subjects:
+  - kind: User <5>
+    apiGroup: rbac.authorization.k8s.io
+    name: user1 <6>
+----
+1. You can use a different name, but must continue to use that name.
+2. Add the names of the managed clusters that you want your User or Group to access.
+3. You can use any name, but this name must match the previous name that you used.
+4. Ensure the name matches the `ClusterRole` name.
+5. Choose a User or Group.
+6. Specify a User or Group name.
+
+. Apply the `ClusterRole` resource. Run the following command. Change the file name only if you changed it earlier in the process.
+
++
+[source,bash]
+----
+oc apply -f acm-vm-rbac-required.yml
+----
+
+. Create a YAML file for the `ClusterPermission` resource and name the file `cluster01-prod-admin.yml`. 
+
+. Assign fine-grain role-based access from the `ClusterPermission` resource by specifying the cluster name, managed cluster name, and Users or Group name:
+
++
+[source,bash]
+----
+apiVersion: rbac.open-cluster-management.io/v1alpha1
+kind: ClusterPermission
+metadata:
+  name: <cluster01-prod-admin> <1>
+  namespace: <cluster01> <2>
+spec:
+  roleBindings:
+    - name: cluster01-prod-admin <3>
+      namespace: prod <4>
+      roleRef:
+        name: kubevirt.io:admin
+        apiGroup: rbac.authorization.k8s.io
+        kind: ClusterRole
+      subjects:
+        - kind: User <5>
+          apiGroup: rbac.authorization.k8s.io
+          name: user1 <6>
+
+----
+1. Specify the cluster name for the permissions.
+2. Specify the managed cluster namespace for permissions.
+3. Use the cluster name for `RoleBindings`, which assigns roles to Users or Groups.
+4. Specify the namespace in the managed cluster to which the User or Group is granted access.
+5. Choose User or choose Group.
+6. Specify the User or Group name.
+
+. Run the following command to apply the file. Change the name of the file if you changed the name previously:
+
++
+[source,bash]
+----
+oc apply -f cluster01-prod-admin.yml
+----
+
+. *Optional:* If `observability` is enabled, create an additional `RoleBinding` on the hub cluster so that users can view virtual machine details in Grafana.
+
+.. Create the `RoleBinding` resource for Grafana access. See the following sample YAML file with `name: user-observability-grafana-access`:
+
++
+[source,yaml]
+----
+kind: RoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+ name: user-observability-grafana-access
+ namespace: cluster01
+subjects:
+ - kind: User
+   apiGroup: rbac.authorization.k8s.io
+   name: user1
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: view
+----
+
+.. Apply the `ClusterRoleBinding` resource with the following command:
+
++
+[source,bash]
+----
+oc apply -f user-observability-grafana-access.yml
+----
+
+

secure_cluster/fine_grain_rbac_ui.adoc

@@ -0,0 +1,144 @@
+[#fine-grain-rbac-cli]
+= Implementing fine-grained role-based access control with the console (Technology Preview)
+
+*Technology Preview:* {acm} supports fine-grained role-based access control (RBAC). As a cluster administrator, you can manage and control permissions with the `ClusterPermission` resource, which controls permissions at the namespace level on managed clusters, rather than at the cluster level. Grant permissions to a virtual machine namespace within a cluster without granting permission to the entire managed cluster, or virtual machine.
+
+Learn how to set up for fine-grained role-based access control (RBAC) and the `ClusterPermission` resource from the console.
+
+*Required access:* Cluster administrator
+
+To learn about {ocp-short} default and virtualization roles and permissions, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/virtualization/about#authorization_virt-security-policies[Authorization] in the {ocp-short} documentation.
+
+See xref:../secure_cluster/rbac_implement_rhacm.adoc#rhacm-rbac-implement[Implementing role-based access control] for more details about {acm-short} role-based access.
+
+.Prerequisites
+
+See the following requirements to begin using fine-grained role-based access control:
+
+. Your `MultiClusterHub` custom resource `spec.overrides.components` field for `search` must `enabled` to retrieve a list of managed clusters namespaces that can represent virtual machines that are used for access control.
+. You need virtual machines.
+
+[#assign-fine-grain-rbac]
+== Assigning fine-grained role-based access control in the console
+
+You can assign users to manage virtual machines with fine-grained role-based access control. Action are disabled in the console if the user-role access is not permitted. Slide the *YAML* option on to see the metadata that you enter populate the the YAML editor.
+
+You can grant access to the following roles for {ocp-virt-short}, which are extensions of the default roles:
+
+- `kubevirt.io:view`: only view resources
+- `kubevirt.io:edit`: modify resources
+- `kubevirt.io:admin`: view, modify, delete resources; grant permissions
+
+*Important:* As an administrator, you need to add either `Role bindings` or `Cluster role binding` for a valid `ClusterPermission` resource. You can also choose to add both. One cluster permission is used for each managed cluster.
+
+. Navigate to the your `MultiClusterHub` custom resource to edit the resource and enable the feature.
+.. From the `local-cluster` view, click *Operators* > *Installed Operators* > *Advanced Cluster Management for Kubernetes*. 
+.. Click the *MultiClusterHub* tab to edit the resource. 
+.. Slide the *YAML* option on to see the metadata in the YAML editor.
+.. In your `MultiClusterHub` custom resource `spec.overrides.components` field, set `fine-grained-rbac-preview` to `true` to enable the feature. Change the `configOverrides` specification to `enabled: true` in the YAML editor and save your changes. See the following example with `fine-grained-rbac-preview` enabled:
++
+[source,yaml]
+----
+ - configOverrides: {}
+      enabled: true
+      name: fine-grained-rbac-preview
+----
+. Label your `local-cluster` with `environment=virtualization`. 
+.. From the `All Clusters` view, click **Infrastructure** > *Clusters* >
+.. Find your `local-cluster` and click *Actions* to edit. 
+.. Add the `environment=virtualization` label and save your changes. See the following example:
++
+[source,bash]
+----
+environment=virtualization
+----
+. Change the `policy-virt-clusterroles` value for the `remediationAction` to `enforce`, which adds the `kubevirt` `clusterroles` to the hub cluster.
+.. Click *Governance* > *Policies*.
+.. Find the `policy-virt-clusterroles` policy and click *Actions* to change the `remediationAction` value to `enforce`.
+.. Slide the *YAML* option on to see the metadata in the YAML editor and save your changes. See the following YAML sample:
++
+----
+remediationAction: enforce
+----
+. Create a `ClusterRole` resource.
+.. From the `local-cluster` view, click *User Management* > *Roles* > *Create Role*.
+.. Add the following `ClusterRole` resource information to the YAML editor:
+
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: acm-vm-rbac-required <1>
+rules:
+  - apiGroups: ["clusterview.open-cluster-management.io"]
+    resources: ["kubevirtprojects"]
+    verbs: ["list"]
+  - apiGroups: ["clusterview.open-cluster-management.io"]
+    resources: ["managedclusters"]
+    verbs: ["list","get","watch"]
+  - apiGroups: ["cluster.open-cluster-management.io"]
+    resources: ["managedclusters"]
+    verbs: ["get"]
+    resourceNames: ["cluster01", "cluster02", "cluster03"] <2>
+----
+1. You can use a different name, but must continue to use that name during the process.
+2. Add the names of the managed clusters that you want your User or Group to access.
+
+. Create a `ClusterRoleBinding`. 
+.. From the `local-cluster` view, click *User Management* > *RoleBindings* > *Create bindings*.
+.. Choose `Cluster-wide role binding` for the _Binding type_.
+.. Add the `RoleBinding` name that matches the name of the `ClusterRole`, which for this example is `acm-vm-rbac-required`.
+.. Add the matching role name, which for this example is also `acm-vm-rbac-required`.
+.. For the _Subject_, select User or Group, enter the User or Group name, and save your changes.
+. Create a `ClusterPermission` resource to grant permissions at the namespace level.
+.. Click *Access control* > *Create permission*. 
+.. In the _Basic information_ window, add the cluster name and the User or Group that is granted permission.
+.. Choose the cluster or virtual machine with the specific namespace for that permission.
+. Add the `Role bindings` information, which sets permissions at the namespace level. 
+.. Add namespaces in the cluster or virtual machine.
+.. Add Users or Groups.
+.. Add roles, such as `kubevirt.io:view`, for fine-grained role-based access control. You can choose a combination of `RoleBindings`.
+. Add the `Cluster role binding` with the same information to set permissions at the cluster level. 
+. Review and click *Create permission* to create `ClusterPermission` resource as you see in the following example:
+
++
+[source,bash]
+----
+apiVersion: rbac.open-cluster-management.io/v1alpha1
+kind: ClusterPermission
+metadata:
+  name: <cluster01-prod-admin> <1>
+  namespace: <cluster01> <2>
+spec:
+  roleBindings:
+    - name: cluster01-prod-admin <3>
+      namespace: prod <4>
+      roleRef:
+        name: kubevirt.io:admin
+        apiGroup: rbac.authorization.k8s.io
+        kind: ClusterRole
+      subjects:
+        - kind: User <5>
+          apiGroup: rbac.authorization.k8s.io
+          name: user1 <6>
+
+----
+1. Specify the cluster name for the permissions.
+2. Specify the managed cluster namespace for permissions.
+3. Use the cluster name for `RoleBindings`, which assigns roles to Users or Groups.
+4. Specify the namespace in the managed cluster to which the User or Group is granted access.
+5. Choose User or choose Group.
+6. Specify the User or Group name.
+. Check for a `Ready` status in the console.
+. You can click *Edit permission* to edit the `Role bindings` and `Cluster role binding`.
+. *Optional:* Click *Export YAML* to use the resources for GitOps or in the terminal.
+. You can delete the `ClusterPermissions` resource when you are ready.
+
+. *Optional:* If `observability` is enabled, create an additional `RoleBinding` on the hub cluster so that users can view virtual machine details in Grafana.
+.. From the `local-cluster` view, click *User Management* > *RoleBindings* > *RoleBindings*.
+.. Choose `Namespace role binding` for the _Binding type_.
+.. Add the `observability-grafana-access``RoleBinding` name.
+.. Choose `view` for the _Role name_.
+.. For the _Subject_, select User or Group, enter the User or Group name, and save your changes.

secure_cluster/main.adoc

@@ -5,7 +5,9 @@ include::modules/common-attributes.adoc[]
 include::securing_cluster_intro.adoc[leveloffset=+1]
 include::rbac.adoc[leveloffset=+2]
 include::rbac_implement_rhacm.adoc[leveloffset=+2]
+include::fine_grain_rbac_ui.adoc[leveloffset=+2]
+include::fine_grain_rbac_cli.adoc[leveloffset=+2]
 include::certificates.adoc[leveloffset=+2]
 include::cert_manage.adoc[leveloffset=+2]
 include::cert_byo.adoc[leveloffset=+2]
-//we would then only need level 1 and all others level two if we remove the cert intro
+

secure_cluster/securing_cluster_intro.adoc

@@ -10,6 +10,7 @@ Use the role-based access control and authentication to identify the user associ
 
 * xref:../secure_cluster/rbac.adoc#rbac-rhacm[Role-based access control]
 * xref:../secure_cluster/rbac_implement_rhacm.adoc#rhacm-rbac-implement[Implementing role-based access control]
+* xref:../secure_cluster/fine_grain_rbac.adoc##fine-grain-rbac[Implementing fine-grained role-based access control (Technology Preview)]
 * xref:../secure_cluster/certificates.adoc#certificates[Certificates]
 * xref:../secure_cluster/cert_manage.adoc#cert-manage[Managing certificates]
 * xref:../secure_cluster/cert_byo.adoc#certificates-byo[Bringing your own observability Certificate Authority (CA) certificates]