OBSDOCS-290 - Loki Log Access

logging/cluster-logging-loki.adoc

@@ -37,6 +37,15 @@ ifdef::openshift-enterprise[]
 * xref:../nodes/scheduling/nodes-scheduler-pod-affinity.adoc#nodes-scheduler-pod-affinity[Placing pods relative to other pods using affinity and anti-affinity rules]
 endif::[]
 
+include::modules/logging-loki-log-access.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+ifdef::openshift-enterprise[]
+xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]
+endif::[]
+
 include::modules/logging-loki-retention.adoc[leveloffset=+1]
 
 include::modules/cluster-logging-forwarding-lokistack.adoc[leveloffset=+1]

modules/logging-loki-log-access.adoc

@@ -0,0 +1,94 @@
+// Module included in the following assemblies:
+//
+// * logging/cluster-logging-loki.adoc
+
+:_content-type: CONCEPT
+[id="logging-loki-log-access_{context}"]
+= Fine grained access for Loki logs
+In {logging} 5.8 and later, the ClusterLogging Operator does not grant all users access to logs by default.  As an administrator, you need to configure your users access unless the Operator was upgraded and prior configurations are in place. Depending on your configuration and need, you can configure fine grain access to logs using the following:
+
+* Cluster wide policies
+* Namespace scoped policies
+* Creation of custom admin groups
+
+As an administrator, you need to create the role bindings and cluster role bindings appropriate for your deployment. The ClusterLogging Operator provides the following cluster roles:
+
+* `cluster-logging-application-view` grants permission to read application logs.
+* `cluster-logging-infrastructure-view` grants permission to read infrastructure logs.
+* `cluster-logging-audit-view` grants permission to read audit logs.
+
+If you have upgraded from a prior version, an additional cluster role `logging-application-logs-reader` and associated cluster role binding `logging-all-authenticated-application-logs-reader` provide backward compatibility, allowing any authenticated user read access in their namespaces.
+
+[NOTE]
+====
+Users with access by namespace must provide a namespace when querying application logs.
+====
+
+== Cluster wide access
+Cluster role binding resources reference cluster roles, and set permissions cluster wide.
+
+.Example ClusterRoleBinding
+[source,yaml]
+----
+kind: ClusterRoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: logging-all-application-logs-reader
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: cluster-logging-application-view # <1>
+subjects: # <2>
+- kind: Group
+  name: system:authenticated
+  apiGroup: rbac.authorization.k8s.io
+----
+<1> Additional `ClusterRoles` are `cluster-logging-infrastructure-view`, and `cluster-logging-audit-view`.
+<2> Specifies the users or groups this object applies to.
+
+== Namespaced access
+
+`RoleBinding` resources can be used with `ClusterRole` objects to define the namespace a user or group has access to logs for.
+
+.Example RoleBinding
+[source,yaml]
+----
+kind: RoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: allow-read-logs
+  namespace: log-test-0 # <1>
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: cluster-logging-application-view
+subjects:
+- kind: User
+  apiGroup: rbac.authorization.k8s.io
+  name: testuser-0
+----
+<1> Specifies the namespace this `RoleBinding` applies to.
+
+== Custom admin group access
+
+If you have a large deployment with a number of users who require broader permissions, you can create a custom group using the `adminGroup` field. Users who are members of any group specified in the `adminGroups` field of the LokiStack CR are considered admins. Admin users have access to all application logs in all namespaces, if they also get assigned the `cluster-logging-application-view` role.
+
+.Example LokiStack CR
+[source,yaml]
+----
+apiVersion: loki.grafana.com/v1
+kind: LokiStack
+metadata:
+  name: logging-loki
+  namespace: openshift-logging
+spec:
+  tenants:
+    mode: openshift-logging # <1>
+    openshift:
+      adminGroups: # <2>
+      - cluster-admin
+      - custom-admin-group # <3>
+----
+<1> Custom admin groups are only available in this mode.
+<2> Entering an empty list `[]` value for this field disables admin groups.
+<3> Overrides the default groups (`system:cluster-admins`, `cluster-admin`, `dedicated-admin`)