[enterprise-4.11] OBSDOCS-552: sample service config for Cluster Observability Operator tech preview

_topic_maps/_topic_map.yml

@@ -2373,6 +2373,8 @@ Topics:
     File: cluster-observability-operator-overview
   - Name: Installing the Cluster Observability Operator
     File: installing-the-cluster-observability-operator
+  - Name: Configuring the Cluster Observability Operator to monitor a service
+    File: configuring-the-cluster-observability-operator-to-monitor-a-service
 ---
 Name: Network Observability
 Dir: network_observability

modules/monitoring-creating-a-monitoringstack-object-for-cluster-observability-operator.adoc

@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// monitoring/cluster-observability-operator/configuring-the-cluster-observability-operator-to-monitor-a-service.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-a-monitoringstack-object-for-cluster-observability-operator_{context}"]
+= Creating a MonitoringStack object for the Cluster Observability Operator
+
+To scrape the metrics data exposed by the target `prometheus-coo-example-app` service, create a `MonitoringStack` object that references the `ServiceMonitor` object you created in the "Specifying how a service is monitored for Cluster Observability Operator" section.
+This `MonitoringStack` object can then discover the service and scrape the exposed metrics data from it.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` cluster role or as a user with administrative permissions for the namespace.
+* You have installed the Cluster Observability Operator.
+* You have deployed the `prometheus-coo-example-app` sample service in the `ns1-coo` namespace.
+* You have created a `ServiceMonitor` object named `prometheus-coo-example-monitor` in the `ns1-coo` namespace.
+
+.Procedure
+
+. Create a YAML file for the `MonitoringStack` object configuration. For this example, name the file `example-coo-monitoring-stack.yaml`.
+
+. Add the following `MonitoringStack` object configuration details:
++
+.Example `MonitoringStack` object
++
+[source,yaml]
+----
+apiVersion: monitoring.rhobs/v1alpha1
+kind: MonitoringStack
+metadata:
+  name: example-coo-monitoring-stack
+  namespace: ns1-coo
+spec:
+  logLevel: debug
+  retention: 1d
+  resourceSelector:
+    matchLabels:
+      k8s-app: prometheus-coo-example-monitor
+----
+
+. Apply the `MonitoringStack` object by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f example-coo-monitoring-stack.yaml
+----
+
+. Verify that the `MonitoringStack` object is available by running the following command and inspecting the output:
++
+[source,terminal]
+----
+$ oc -n ns1-coo get monitoringstack
+----
++
+.Example output
+[source,terminal]
+----
+NAME                         AGE
+example-coo-monitoring-stack   81m
+----

modules/monitoring-deploying-a-sample-service-for-cluster-observability-operator.adoc

@@ -0,0 +1,88 @@
+// Module included in the following assemblies:
+//
+// monitoring/cluster-observability-operator/configuring-the-cluster-observability-operator-to-monitor-a-service.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="deploying-a-sample-service-for-cluster-observability-operator_{context}"]
+= Deploying a sample service for Cluster Observability Operator
+
+This configuration deploys a sample service named `prometheus-coo-example-app` in the user-defined `ns1-coo` project. 
+The service exposes the custom `version` metric.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` cluster role or as a user with administrative permissions for the namespace.
+
+.Procedure
+
+. Create a YAML file named `prometheus-coo-example-app.yaml` that contains the following configuration details for a namespace, deployment, and service:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: ns1-coo
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: prometheus-coo-example-app
+  name: prometheus-coo-example-app
+  namespace: ns1-coo
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: prometheus-coo-example-app
+  template:
+    metadata:
+      labels:
+        app: prometheus-coo-example-app
+    spec:
+      containers:
+      - image: ghcr.io/rhobs/prometheus-example-app:0.4.1
+        imagePullPolicy: IfNotPresent
+        name: prometheus-coo-example-app
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: prometheus-coo-example-app
+  name: prometheus-coo-example-app
+  namespace: ns1-coo
+spec:
+  ports:
+  - port: 8080
+    protocol: TCP
+    targetPort: 8080
+    name: web
+  selector:
+    app: prometheus-coo-example-app
+  type: ClusterIP
+----
+
+. Save the file.
+
+. Apply the configuration to the cluster by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f prometheus-coo-example-app.yaml
+----
+
+. Verify that the pod is running by running the following command and observing the output:
++
+[source,terminal]
+----
+$ oc -n -ns1-coo get pod
+----
++
+.Example output
+[source,terminal]
+----
+NAME                                      READY     STATUS    RESTARTS   AGE
+prometheus-coo-example-app-0927545cb7-anskj   1/1       Running   0          81m
+----

modules/monitoring-specifying-how-a-service-is-monitored-by-cluster-observability-operator.adoc

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// monitoring/cluster-observability-operator/configuring-the-cluster-observability-operator-to-monitor-a-service.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="specifying-how-a-service-is-monitored-by-cluster-observability-operator_{context}"]
+= Specifying how a service is monitored by Cluster Observability Operator
+
+To use the metrics exposed by the sample service you created in the "Deploying a sample service for Cluster Observability Operator" section, you must configure monitoring components to scrape metrics from the `/metrics` endpoint. 
+
+You can create this configuration by using a `ServiceMonitor` object that specifies how the service is to be monitored, or a `PodMonitor` object that specifies how a pod is to be monitored. 
+The `ServiceMonitor` object requires a `Service` object. The `PodMonitor` object does not, which enables the `MonitoringStack` object to scrape metrics directly from the metrics endpoint exposed by a pod.
+
+This procedure shows how to create a `ServiceMonitor` object for a sample service named `prometheus-coo-example-app` in the `ns1-coo` namespace.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` cluster role or as a user with administrative permissions for the namespace.
+* You have installed the Cluster Observability Operator.
+* You have deployed the `prometheus-coo-example-app` sample service in the `ns1-coo` namespace.
++
+[NOTE]
+====
+The `prometheus-coo-example-app` sample service does not support TLS authentication. 
+====
+
+.Procedure
+
+. Create a YAML file named `example-coo-app-service-monitor.yaml` that contains the following `ServiceMonitor` object configuration details:
++
+[source,yaml]
+----
+apiVersion: monitoring.rhobs/v1alpha1
+kind: ServiceMonitor
+metadata:
+  labels:
+    k8s-app: prometheus-coo-example-monitor
+  name: prometheus-coo-example-monitor
+  namespace: ns1-coo
+spec:
+  endpoints:
+  - interval: 30s
+    port: web
+    scheme: http
+  selector:
+    matchLabels:
+      app: prometheus-coo-example-app
+----
++
+This configuration defines a `ServiceMonitor` object that the `MonitoringStack` object will reference to scrape the metrics data exposed by the `prometheus-coo-example-app` sample service.
+
+. Apply the configuration to the cluster by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f example-app-service-monitor.yaml
+----
+
+. Verify that the `ServiceMonitor` resource is created by running the following command and observing the output:
++
+[source,terminal]
+----
+$ oc -n ns1-coo get servicemonitor
+----
++
+.Example output
+[source,terminal]
+----
+NAME                         AGE
+prometheus-coo-example-monitor   81m
+----

monitoring/cluster_observability_operator/configuring-the-cluster-observability-operator-to-monitor-a-service.adoc

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="configuring-the-cluster-observability-operator-to-monitor-a-service"]
+= Configuring the Cluster Observability Operator to monitor a service
+include::_attributes/common-attributes.adoc[]
+:context: configuring_the_cluster_observability_operator_to_monitor_a_service
+
+toc::[]
+
+:FeatureName: The Cluster Observability Operator
+include::snippets/technology-preview.adoc[leveloffset=+2]
+
+You can monitor metrics for a service by configuring monitoring stacks managed by the Cluster Observability Operator (COO).
+
+To test monitoring a service, follow these steps:
+
+* Deploy a sample service that defines a service endpoint.
+* Create a `ServiceMonitor` object that specifies how the service is to be monitored by the COO.
+* Create a `MonitoringStack` object to discover the `ServiceMonitor` object.
+
+// Deploy a sample service for Cluster Observability Operator
+include::modules/monitoring-deploying-a-sample-service-for-cluster-observability-operator.adoc[leveloffset=+1]
+
+// Specify how the sample COO service is monitored
+include::modules/monitoring-specifying-how-a-service-is-monitored-by-cluster-observability-operator.adoc[leveloffset=+1]
+
+// Create a MonitoringStack object to discover the service monitor
+include::modules/monitoring-creating-a-monitoringstack-object-for-cluster-observability-operator.adoc[leveloffset=+1]