Merge pull request #76829 from openshift-cherrypick-robot/cherry-pick…

…-75588-to-enterprise-4.15

[enterprise-4.15] OBSDOCS-702: Clarify available endpoint auth methods in user workload…

modules/monitoring-example-remote-write-authentication-settings.adoc

@@ -183,12 +183,10 @@ metadata:
 stringData:
   id: <oauth2_id> <1>
   secret: <oauth2_secret> <2>
-  token: <oauth2_authentication_token> <3>
 type: Opaque
 ----
 <1> The Oauth 2.0 ID.
 <2> The OAuth 2.0 secret.
-<3> The OAuth 2.0 token.
 
 The following shows an `oauth2` remote write authentication sample configuration that uses a `Secret` object named `oauth2-credentials` in the `{namespace-name}` namespace:
 

modules/monitoring-example-service-endpoint-authentication-settings.adoc

@@ -0,0 +1,158 @@
+// Module included in the following assemblies:
+//
+// * observability/monitoring/configuring-the-monitoring-stack.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="example-service-endpoint-authentication-settings_{context}"]
+= Example service endpoint authentication settings
+
+You can configure authentication for service endpoints for user-defined project monitoring by using `ServiceMonitor` and `PodMonitor` custom resource definitions (CRDs). 
+
+The following samples show different authentication settings for a `ServiceMonitor` resource.
+Each sample shows how to configure a corresponding `Secret` object that contains authentication credentials and other relevant settings.
+
+== Sample YAML authentication with a bearer token
+
+The following sample shows bearer token settings for a `Secret` object named `example-bearer-auth` in the `ns1` namespace:
+
+.Example bearer token secret
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: example-bearer-auth
+  namespace: ns1
+stringData:
+  token: <authentication_token> #<1>
+----
+<1> Specify an authentication token.
+
+The following sample shows bearer token authentication settings for a `ServiceMonitor` CRD. The example uses a `Secret` object named `example-bearer-auth`:
+
+[id="sample-yaml-bearer-token_{context}"]
+.Example bearer token authentication settings
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: prometheus-example-monitor
+  namespace: ns1 
+spec:
+  endpoints: 
+  - authorization:
+      credentials:
+        key: token #<1>
+        name: example-bearer-auth #<2>
+    port: web
+  selector: 
+    matchLabels:
+      app: prometheus-example-app
+----
+<1> The key that contains the authentication token in the specified `Secret` object.
+<2> The name of the `Secret` object that contains the authentication credentials.
+
+[IMPORTANT]
+=====
+Do not use `bearerTokenFile` to configure bearer token. If you use the `bearerTokenFile` configuration, the `ServiceMonitor` resource is rejected.
+=====
+
+[id="sample-yaml-basic-auth_{context}"]
+== Sample YAML for Basic authentication
+
+The following sample shows Basic authentication settings for a `Secret` object named `example-basic-auth` in the `ns1` namespace:
+
+.Example Basic authentication secret
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: example-basic-auth
+  namespace: ns1
+stringData:
+  user: <basic_username> #<1>
+  password: <basic_password>  #<2>
+----
+<1> Specify a username for authentication.
+<2> Specify a password for authentication.
+
+The following sample shows Basic authentication settings for a `ServiceMonitor` CRD. The example uses a `Secret` object named `example-basic-auth`:
+
+.Example Basic authentication settings
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: prometheus-example-monitor
+  namespace: ns1 
+spec:
+  endpoints: 
+  - basicAuth:
+      username:
+        key: user #<1>
+        name: example-basic-auth #<2>
+      password:
+        key: password #<3>
+        name: example-basic-auth #<2>
+    port: web
+  selector: 
+    matchLabels:
+      app: prometheus-example-app
+----
+<1> The key that contains the username in the specified `Secret` object.
+<2> The name of the `Secret` object that contains the Basic authentication.
+<3> The key that contains the password in the specified `Secret` object.
+
+[id="sample-yaml-oauth-20_{context}"]
+== Sample YAML authentication with OAuth 2.0
+
+The following sample shows OAuth 2.0 settings for a `Secret` object named `example-oauth2` in the `ns1` namespace:
+
+.Example OAuth 2.0 secret
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: example-oauth2
+  namespace: ns1
+stringData:
+  id: <oauth2_id> #<1>
+  secret: <oauth2_secret> #<2>
+----
+<1> Specify an Oauth 2.0 ID.
+<2> Specify an Oauth 2.0 secret.
+
+The following sample shows OAuth 2.0 authentication settings for a `ServiceMonitor` CRD. The example uses a `Secret` object named `example-oauth2`:
+
+.Example OAuth 2.0 authentication settings
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: prometheus-example-monitor
+  namespace: ns1 
+spec:
+  endpoints: 
+  - oauth2:
+      clientId: 
+        secret:
+          key: id #<1>
+          name: example-oauth2 #<2>
+      clientSecret:
+        key: secret #<3>
+        name: example-oauth2 #<2>
+      tokenUrl: https://example.com/oauth2/token #<4>
+    port: web
+  selector: 
+    matchLabels:
+      app: prometheus-example-app
+----
+<1> The key that contains the OAuth 2.0 ID in the specified `Secret` object.
+<2> The name of the `Secret` object that contains the OAuth 2.0 credentials.
+<3> The key that contains the OAuth 2.0 secret in the specified `Secret` object.
+<4> The URL used to fetch a token with the specified `clientId` and `clientSecret`.

modules/monitoring-specifying-how-a-service-is-monitored.adoc

@@ -6,7 +6,6 @@
 [id="specifying-how-a-service-is-monitored_{context}"]
 = Specifying how a service is monitored
 
-[role="_abstract"]
 To use the metrics exposed by your service, you must configure {product-title} monitoring to scrape metrics from the `/metrics` endpoint. You can do this using a `ServiceMonitor` custom resource definition (CRD) that specifies how a service should be monitored, or a `PodMonitor` CRD that specifies how a pod should be monitored. The former requires a `Service` object, while the latter does not, allowing Prometheus to directly scrape metrics from the metrics endpoint exposed by a pod.
 
 This procedure shows you how to create a `ServiceMonitor` resource for a service in a user-defined project.
@@ -29,30 +28,29 @@ The `prometheus-example-app` sample service does not support TLS authentication.
 
 .Procedure
 
-. Create a YAML file for the `ServiceMonitor` resource configuration. In this example, the file is called `example-app-service-monitor.yaml`.
+. Create a new YAML configuration file named `example-app-service-monitor.yaml`.
 
-. Add the following `ServiceMonitor` resource configuration details:
+. Add a `ServiceMonitor` resource to the YAML file. The following example creates a service monitor named `prometheus-example-monitor` to scrape metrics exposed by the `prometheus-example-app` service in the `ns1` namespace:
 +
 [source,yaml]
 ----
 apiVersion: monitoring.coreos.com/v1
 kind: ServiceMonitor
 metadata:
-  labels:
-    k8s-app: prometheus-example-monitor
   name: prometheus-example-monitor
-  namespace: ns1
+  namespace: ns1 #<1>
 spec:
   endpoints:
   - interval: 30s
-    port: web
+    port: web #<2>
     scheme: http
-  selector:
+  selector: #<3>
     matchLabels:
       app: prometheus-example-app
 ----
-+
-This defines a `ServiceMonitor` resource that scrapes the metrics exposed by the `prometheus-example-app` sample service, which includes the `version` metric.
+<1> Specify a user-defined namespace where your service runs.
+<2> Specify endpoint ports to be scraped by Prometheus.
+<3> Configure a selector to match your service based on its metadata labels.
 +
 [NOTE]
 ====
@@ -68,11 +66,11 @@ $ oc apply -f example-app-service-monitor.yaml
 +
 It takes some time to deploy the `ServiceMonitor` resource.
 
-. You can check that the `ServiceMonitor` resource is running:
+. Verify that the `ServiceMonitor` resource is running:
 +
 [source,terminal]
 ----
-$ oc -n ns1 get servicemonitor
+$ oc -n <namespace> get servicemonitor
 ----
 +
 .Example output

observability/monitoring/managing-metrics.adoc

@@ -21,6 +21,7 @@ include::modules/monitoring-understanding-metrics.adoc[leveloffset=+1]
 include::modules/monitoring-setting-up-metrics-collection-for-user-defined-projects.adoc[leveloffset=+1]
 include::modules/monitoring-deploying-a-sample-service.adoc[leveloffset=+2]
 include::modules/monitoring-specifying-how-a-service-is-monitored.adoc[leveloffset=+2]
+include::modules/monitoring-example-service-endpoint-authentication-settings.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources