Merge pull request #44713 from bburt-rh/RHDEVDOCS-3917-document-new-auth-methods-for-remote_write

RHDEVDOCS-3917 - document new authentication methods for remote_write in monitoring

Author: JStickler

modules/monitoring-configuring-remote-write-storage.adoc

@@ -21,15 +21,25 @@ Doing so has no impact on how or for how long Prometheus stores metrics.
 * You have installed the OpenShift CLI (`oc`).
 * You have set up a remote write compatible endpoint (such as Thanos) and know the endpoint URL.
 See the link:https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage[Prometheus remote endpoints and storage documentation] for information about endpoints that are compatible with the remote write feature.
-* You have set up authentication credentials for the remote write endpoint. 
+* You have set up authentication credentials in a `Secret` object for the remote write endpoint.
+You must create the secret in the same namespace as the Prometheus object for which you configure remote write:  the `openshift-monitoring` namespace for default platform monitoring or the `openshift-user-workload-monitoring` namespace for user workload monitoring.
+ 
 +
 [CAUTION]
 ====
-To reduce security risks, avoid sending metrics to an endpoint via unencrypted HTTP or without using authentication.
+To reduce security risks, use HTTPS and authentication to send metrics to an endpoint.
 ====
 
 .Procedure
 
+Follow these steps to configure remote write for default platform monitoring in the `cluster-monitoring-config` config map in the `openshift-monitoring` namespace.
+
+[NOTE]
+====
+If you configure remote write for the Prometheus instance that monitors user-defined projects, make similar edits to the `user-workload-monitoring-config` config map in the `openshift-user-workload-monitoring` namespace. 
+Note that the Prometheus config map component is called `prometheus` in the `user-workload-monitoring-config` `ConfigMap` object and not `prometheusK8s`, as it is in the `cluster-monitoring-config` `ConfigMap` object. 
+====
+
 . Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project:
 +
 [source,terminal]
@@ -52,89 +62,14 @@ data:
   config.yaml: |
     prometheusK8s:
       remoteWrite:
-      - url: "https://remote-write.endpoint"
-        <endpoint_authentication_credentials>
-----
-+
-For `endpoint_authentication_credentials` substitute the credentials for the endpoint.
-Currently supported authentication methods are basic authentication (`basicAuth`) and client TLS (`tlsConfig`) authentication.
-+
-* The following example configures basic authentication:
-+
-[source,yaml]
-----
-basicAuth:
-  username:
-    <usernameSecret>
-  password:
-    <passwordSecret>
-----
-Substitute `<usernameSecret>` and `<passwordSecret>` accordingly. 
-+
-The following sample shows basic authentication configured with `remoteWriteAuth` for the `name` values and `user` and `password` for the `key` values. These values contain the endpoint authentication credentials:
-+
-[source,yaml]
-----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: cluster-monitoring-config
-  namespace: openshift-monitoring
-data:
-  config.yaml: |
-    prometheusK8s:
-      remoteWrite:
-      - url: "https://remote-write.endpoint"
-        basicAuth:
-          username:
-            name: remoteWriteAuth
-            key: user
-          password:
-            name: remoteWriteAuth
-            key: password
-----
-+
-* The following example configures client TLS authentication:
-+
-[source,yaml]
-----
-tlsConfig:
-  ca:
-    <caSecret>
-  cert:
-    <certSecret>
-  keySecret:
-    <keySecret>
+      - url: "https://remote-write-endpoint.example.com" <1>
+        <endpoint_authentication_credentials> <2>
 ----
-Substitute `<caSecret>`, `<certSecret>`, and `<keySecret>` accordingly. 
 +
-The following sample shows a TLS authentication configuration using `selfsigned-mtls-bundle` for the `name` values and `ca.crt` for the `ca` `key` value, `client.crt` for the `cert` `key` value, and `client.key` for the `keySecret` `key` value:
-+
-[source,yaml]
-----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: cluster-monitoring-config
-  namespace: openshift-monitoring
-data:
-  config.yaml: |
-    prometheusK8s:
-      remoteWrite:
-      - url: "https://remote-write.endpoint"
-        tlsConfig:
-          ca:
-            secret:
-              name: selfsigned-mtls-bundle
-              key: ca.crt
-          cert:
-            secret:
-              name: selfsigned-mtls-bundle
-              key: client.crt
-          keySecret:
-            name: selfsigned-mtls-bundle
-            key: client.key
-----
+<1> The URL of the remote write endpoint.
+<2> The authentication method and credentials for the endpoint.
+Currently supported authentication methods are AWS Signature Version 4, authentication using HTTP an `Authorization` request header, basic authentication, OAuth 2.0, and TLS client. 
+See _Supported remote write authentication settings_ below for sample configurations of supported authentication methods.
 
 . Add write relabel configuration values after the authentication credentials:
 +
@@ -149,10 +84,11 @@ data:
   config.yaml: |
     prometheusK8s:
       remoteWrite:
-      - url: "https://remote-write.endpoint"
+      - url: "https://remote-write-endpoint.example.com"
         <endpoint_authentication_credentials>
-        <write_relabel_configs>
+        <write_relabel_configs> <1>
 ----
+<1> The write relabel configuration settings.
 +
 For `<write_relabel_configs>` substitute a list of write relabel configurations for metrics that you want to send to the remote endpoint.
 +
@@ -169,7 +105,7 @@ data:
   config.yaml: |
     prometheusK8s:
       remoteWrite:
-      - url: "https://remote-write.endpoint"
+      - url: "https://remote-write-endpoint.example.com"
         writeRelabelConfigs:
         - sourceLabels: [__name__]
           regex: 'my_metric'
@@ -179,29 +115,6 @@ data:
 +
 See the link:https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config[Prometheus relabel_config documentation] for information about write relabel configuration options.
 
-. If required, configure remote write for the Prometheus instance that monitors user-defined projects by changing the `name` and `namespace` `metadata` values as follows:
-+
-[source,yaml]
-----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: user-workload-monitoring-config
-  namespace: openshift-user-workload-monitoring
-data:
-  config.yaml: |
-    prometheus:
-      remoteWrite:
-      - url: "https://remote-write.endpoint"
-        <endpoint_authentication_credentials>
-        <write_relabel_configs>
-----
-+
-[NOTE]
-====
-The Prometheus config map component is called `prometheusK8s` in the `cluster-monitoring-config` `ConfigMap` object and `prometheus` in the `user-workload-monitoring-config` `ConfigMap` object.
-====
-
 . Save the file to apply the changes to the `ConfigMap` object.
 The pods affected by the new configuration restart automatically.
 +
@@ -214,4 +127,3 @@ Configurations applied to the `user-workload-monitoring-config` `ConfigMap` obje
 ====
 Saving changes to a monitoring `ConfigMap` object might redeploy the pods and other resources in the related project. Saving changes might also restart the running monitoring processes in that project.
 ====
-