Add the user workload monitoring documentation

_topic_map.yml

@@ -988,6 +988,8 @@ Topics:
     File: examining-cluster-metrics
   - Name: Accessing Prometheus, Alertmanager, and Grafana
     File: prometheus-alertmanager-and-grafana
+- Name: User workload monitoring
+  File: user-workload-monitoring
 - Name: Exposing custom application metrics for autoscaling
   File: exposing-custom-application-metrics-for-autoscaling
 ---

modules/monitoring-accessing-user-workload-metrics.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * monitoring/user-workload-monitoring.adoc
+
+[id="accessing-user-workload-metrics_{context}"]
+= Accessing user workload metrics
+
+Once you have enabled user workload monitoring, deployed the workload, and, optionally, gave additional view permissions, you can access the custom metrics as the cluster administrator, as a developer, or as another user with permissions.
+
+.Prerequisites
+
+* You need to have deployed the workload that you want to monitor, such as an application or a service. This example uses the application described in "Deploying a sample application".
+* You need to have user workload monitoring enabled.
+* If accessing metrics as an arbitrary user, the user needs to have the permissions as described in "Granting a user access to metrics".
+
+.Procedure
+
+. Access the Prometheus web interface:
++
+* To access the metrics as a cluster administrator, go to the OpenShift Container Platform web console, switch to the Administrator Perspective, and click *Monitoring* -> *Metrics*.
+* To access the metrics as a developer or a user with permissions, go to the OpenShift Container Platform web console, switch to the Developer Perspective, then click *Advanced* -> *Metrics*. Select the project where the user workload resides.
+. Use the PromQL interface to run queries for user workload metrics. This works the same as with cluster metrics queries.
+
+.Additional resources
+
+* See the xref:../monitoring/cluster-monitoring/examining-cluster-metrics.adoc#examining-cluster-metrics[section on using the PromQL interface].

modules/monitoring-deploying-a-sample-application.adoc

@@ -0,0 +1,99 @@
+// Module included in the following assemblies:
+//
+// * monitoring/user-workload-monitoring.adoc
+
+[id="deploying-a-sample-application_{context}"]
+= Deploying a sample application
+
+To test user workload monitoring, you can deploy a sample application.
+
+.Procedure
+
+. Create a YAML file for the application configuration. In this example, it is called `prometheus-example-app.yaml`.
+
+. Fill the file with the configuration for deploying the application:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: ns1
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  labels:
+    app: prometheus-example-app
+  name: prometheus-example-app
+  namespace: ns1
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: prometheus-example-app
+  template:
+    metadata:
+      labels:
+        app: prometheus-example-app
+    spec:
+      containers:
+      - image: quay.io/brancz/prometheus-example-app:v0.1.0
+        imagePullPolicy: IfNotPresent
+        name: prometheus-example-app
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: prometheus-example-app
+  name: prometheus-example-app
+  namespace: ns1
+spec:
+  ports:
+  - port: 8080
+    protocol: TCP
+    targetPort: 8080
+    name: web
+  selector:
+    app: prometheus-example-app
+  type: ClusterIP
+---
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  labels:
+    k8s-app: prometheus-example-monitor
+  name: prometheus-example-monitor
+  namespace: ns1
+spec:
+  endpoints:
+  - interval: 30s
+    port: web
+    scheme: http
+  selector:
+    matchLabels:
+      app: prometheus-example-app
+----
++
+This configuration deploys an application named `prometheus-example-app` in the `ns1` namespace. This application exposes the custom `version` metric.
+
+. Apply the configuration file to the cluster:
++
+----
+$ oc apply -f prometheus-example-app.yaml
+----
++
+It will take some time to deploy the application.
+
+. You can check that the application is running and exposing metrics:
++
+----
+$ oc -n ns1 get pod
+NAME                                      READY     STATUS    RESTARTS   AGE
+prometheus-example-app-7857545cb7-sbgwq   1/1       Running   0          81m
+
+$ oc -n ns1 get servicemonitor
+NAME                         AGE
+prometheus-example-monitor   81m
+----

modules/monitoring-enabling-user-workload-monitoring.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * monitoring/user-workload-monitoring.adoc
+
+[id="enabling-user-workload-monitoring_{context}"]
+= Enabling user workload monitoring
+
+You can enable user workload monitoring using the cluster monitoring ConfigMap.
+
+.Prerequisites
+
+* Make sure you have the `cluster-monitoring-config` ConfigMap object with the `data/config.yaml` section.
+
+.Procedure
+
+. Start editing the `cluster-monitoring-config` ConfigMap:
++
+----
+$ oc -n openshift-monitoring edit configmap cluster-monitoring-config
+----
+
+. Set the `techPreviewUserWorkload` setting to `true` under `data/config.yaml`:
++
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-monitoring-config
+  namespace: openshift-monitoring
+data:
+  config.yaml: |
+    techPreviewUserWorkload:
+      enabled: true
+----
+
+. Save the file to apply the changes. The user workload monitoring is enabled automatically.
+
+.Additional resources
+
+* See xref:../monitoring/cluster-monitoring/configuring-the-monitoring-stack.adoc#configuring-the-monitoring-stack[Configuring the monitoring stack] to learn how to create `cluster-monitoring-config`.

modules/monitoring-examining-metrics-as-a-developer.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * monitoring/cluster-monitoring/examining-cluster-metrics.adoc
+
+[id="examining-metrics-as-a-developer_{context}"]
+= Examining metrics as a developer
+
+You might enable user workload monitoring for an application or service in a project. In that case, a developer of that project can examine the exposed custom metrics using the Developer Perspective in the Web console.
+
+:FeatureName: Examining metrics using the Developer Perspective
+include::modules/technology-preview.adoc[leveloffset=+0]
+
+.Procedure
+
+. Open the {product-title} Web console, switch to the Developer Perspective, and navigate to the *Advanced* -> *Metrics* page. Select the project where the user workload resides.
++
+image::monitoring-metrics-developer.png[]
+
+. Now you can work with custom metrics in the same way as with cluster metrics.
+

modules/monitoring-granting-a-user-access-to-metrics.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * monitoring/user-workload-monitoring.adoc
+
+[id="granting-a-user-access-to-metrics_{context}"]
+= Granting a user access to metrics
+
+By default, only cluster administrator users have access to user workload metrics. Using the soft tenancy feature, you can also grant metrics access to an arbitrary user, who only has access to a particular project.
+
+.Prerequisites
+
+* You need to have deployed the workload that you want to monitor, such as an application or a service. This example uses the application described in xref:../monitoring/user-workload-monitoring.adoc#deploying-a-sample-application[Deploying a sample application].
+* You need to have user workload monitoring enabled.
+* You need to have a user created. For the sake of an example, you can create the `johnsmith` user by running `oc create user johnsmith`.
+
+.Procedure
+
+. In the Web console, navigate to *User Management* -> *Role Bindings* -> *Create Binding*.
+. In the *Role Name* field, enter `cluster-monitoring-view`.
+. In the *Subject Name* enter name of the user, for example `johnsmith`.
+. Confirm the role binding. Now the user has been assigned the `cluster-monitoring-view` role, which allows him to access the metrics.

monitoring/cluster-monitoring/examining-cluster-metrics.adoc

@@ -10,6 +10,11 @@ toc::[]
 include::modules/monitoring-contents-of-the-metrics-ui.adoc[leveloffset=+1]
 include::modules/monitoring-running-metrics-queries.adoc[leveloffset=+1]
 include::modules/monitoring-exploring-the-visualized-metrics.adoc[leveloffset=+1]
+include::modules/monitoring-examining-metrics-as-a-developer.adoc[leveloffset=+1]
+
+.Additional resources
+
+See the xref:../../monitoring/user-workload-monitoring.adoc#user-workload-monitoring[User workload monitoring documentation].
 
 .Next steps
 

monitoring/user-workload-monitoring.adoc

@@ -0,0 +1,17 @@
+[id="user-workload-monitoring"]
+= User workload monitoring
+include::modules/common-attributes.adoc[]
+:context: user-workload-monitoring
+
+toc::[]
+
+You can use the Prometheus Cluster Monitoring stack to monitor your applications, services, or other custom workloads in addition to monitoring the cluster. This way, you do not need to use an additional monitoring solution. This helps keeping monitoring centralized.
+Additionally, you can extend the access to the custom metrics beyond cluster administrators. This enables developers and arbitrary users to access the metrics.
+
+:FeatureName: User workload monitoring
+include::modules/technology-preview.adoc[leveloffset=+0]
+
+include::modules/monitoring-enabling-user-workload-monitoring.adoc[leveloffset=+1]
+include::modules/monitoring-deploying-a-sample-application.adoc[leveloffset=+1]
+include::modules/monitoring-granting-a-user-access-to-metrics.adoc[leveloffset=+1]
+include::modules/monitoring-accessing-user-workload-metrics.adoc[leveloffset=+1]