OBSDOCS-781: Improve RBAC LokiStack permission docs

Author: abrennan89

logging/logging_alerts/custom-logging-alerts.adoc

@@ -17,7 +17,7 @@ Administrators can configure log-based alerts or recorded metrics for `applicati
 Application, audit, and infrastructure alerts are sent by default to the {product-title} monitoring stack Alertmanager in the `openshift-monitoring` namespace, unless you have disabled the local Alertmanager instance. If the Alertmanager that is used to monitor user-defined projects in the `openshift-user-workload-monitoring` namespace is enabled, application alerts are sent to the Alertmanager in this namespace by default.
 
 include::modules/configuring-logging-loki-ruler.adoc[leveloffset=+1]
-include::modules/loki-rbac-permissions.adoc[leveloffset=+1]
+include::modules/loki-rbac-rules-permissions.adoc[leveloffset=+1]
 
 ifdef::openshift-enterprise[]
 [role="_additional-resources"]

modules/loki-rbac-permissions.adoc

@@ -0,0 +1,67 @@
+// Module included in the following assemblies:
+//
+// * logging/logging_alerts/custom-logging-alerts.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="loki-rbac-rules-permissions_{context}"]
+= Authorizing LokiStack rules RBAC permissions
+
+Administrators can allow users to create and manage their own alerting and recording rules by binding cluster roles to usernames.
+Cluster roles are defined as `ClusterRole` objects that contain necessary role-based access control (RBAC) permissions for users.
+
+In logging 5.8 and later, the following cluster roles for alerting and recording rules are available for LokiStack:
+
+[options="header"]
+|===
+|Rule name |Description
+
+|`alertingrules.loki.grafana.com-v1-admin`
+|Users with this role have administrative-level access to manage alerting rules. This cluster role grants permissions to create, read, update, delete, list, and watch `AlertingRule` resources within the `loki.grafana.com/v1` API group.
+
+|`alertingrules.loki.grafana.com-v1-crdview`
+|Users with this role can view the definitions of Custom Resource Definitions (CRDs) related to `AlertingRule` resources within the `loki.grafana.com/v1` API group, but do not have permissions for modifying or managing these resources.
+
+|`alertingrules.loki.grafana.com-v1-edit`
+|Users with this role have permission to create, update, and delete `AlertingRule` resources.
+
+|`alertingrules.loki.grafana.com-v1-view`
+|Users with this role can read `AlertingRule` resources within the `loki.grafana.com/v1` API group. They can inspect configurations, labels, and annotations for existing alerting rules but cannot make any modifications to them.
+
+|`recordingrules.loki.grafana.com-v1-admin`
+|Users with this role have administrative-level access to manage recording rules. This cluster role grants permissions to create, read, update, delete, list, and watch `RecordingRule` resources within the `loki.grafana.com/v1` API group.
+
+|`recordingrules.loki.grafana.com-v1-crdview`
+|Users with this role can view the definitions of Custom Resource Definitions (CRDs) related to `RecordingRule` resources within the `loki.grafana.com/v1` API group, but do not have permissions for modifying or managing these resources.
+
+|`recordingrules.loki.grafana.com-v1-edit`
+|Users with this role have permission to create, update, and delete `RecordingRule` resources.
+
+|`recordingrules.loki.grafana.com-v1-view`
+|Users with this role can read `RecordingRule` resources within the `loki.grafana.com/v1` API group. They can inspect configurations, labels, and annotations for existing alerting rules but cannot make any modifications to them.
+
+|===
+
+[id="loki-rbac-rules-permissions-examples"]
+== Examples
+
+To apply cluster roles for a user, you must bind an existing cluster role to a specific username.
+
+Cluster roles can be cluster or namespace scoped, depending on which type of role binding you use.
+When a `RoleBinding` object is used, as when using the `oc adm policy add-role-to-user` command, the cluster role only applies to the specified namespace.
+When a `ClusterRoleBinding` object is used, as when using the `oc adm policy add-cluster-role-to-user` command, the cluster role applies to all namespaces in the cluster.
+
+The following example command gives the specified user create, read, update and delete (CRUD) permissions for alerting rules in a specific namespace in the cluster:
+
+.Example cluster role binding command for alerting rule CRUD permissions in a specific namespace
+[source,terminal]
+----
+$ oc adm policy add-role-to-user alertingrules.loki.grafana.com-v1-admin -n <namespace> <username>
+----
+
+The following command gives the specified user administrator permissions for alerting rules in all namespaces:
+
+.Example cluster role binding command for administrator permissions
+[source,terminal]
+----
+$ oc adm policy add-cluster-role-to-user alertingrules.loki.grafana.com-v1-admin <username>
+----