RHDEVDOCS-4842-how-to-configure-secrets-in-alertmanager

modules/monitoring-adding-a-secret-to-an-alertmanager-configuration.adoc

@@ -0,0 +1,104 @@
+// Module included in the following assemblies:
+//
+// * monitoring/configuring-the-monitoring-stack.adoc
+
+:_content-type: PROCEDURE
+[id="monitoring-adding-a-secret-to-an-alertmanager-configuration_{context}"]
+= Adding a secret to an Alertmanager configuration
+
+You can add secrets to the Alertmanager configuration for core platform monitoring components by editing the `cluster-monitoring-config` config map for the `openshift-monitoring` project.
+You can add secrets to the Alertmanager configuration for user-defined projects by editing the `user-workload-monitoring-config` config map in the `openshift-user-workload-monitoring` project.
+
+[NOTE]
+====
+To configure Alertmanager for user-defined projects to reference the same secret as exists in the `openshift-monitoring` project, you must create the same secret in both the `openshift-monitoring` project and the `openshift-user-workload-monitoring` project.
+==== 
+
+After you add a secret to the config map, the secret is mounted as a volume at `/etc/alertmanager/secrets/<secret_name>` within the `alertmanager` container for the Alertmanager pods.
+
+.Prerequisites
+
+* You have installed the OpenShift CLI (`oc`).
+* You have created the secret for the endpoint receiver.
+* *If you are configuring core {product-title} monitoring components in the `openshift-monitoring` project*:
+** You have access to the cluster as a user with the `cluster-admin` role.
+** You have created the `cluster-monitoring-config` config map.
+* *If you are configuring components that monitor user-defined projects*:
+** A cluster administrator has enabled monitoring for user-defined projects
+** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project.
+
+.Procedure
+
+. To add a secret configuration to Alertmanager for core platform monitoring, edit the `cluster-monitoring-config` config map in the `openshift-monitoring` project:
++
+[source,terminal]
+----
+$ oc -n openshift-monitoring edit configmap cluster-monitoring-config
+----
+
+. Add a `secrets:` section under `data/config.yaml/alertmanagerMain`.
+
+. Add the configuration details for the secret in this section:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-monitoring-config
+  namespace: openshift-monitoring
+data:
+  config.yaml: |
+    alertmanagerMain:
+      secrets: <1>
+      - <secret_name> <2>
+      - <secret_receiver_credentials> <3>
+----
+<1> This section contains the secret or secrets to be mounted into Alertmanager.
+The secrets must be located within the same namespace as the Alertmanager object.
+<2> The name of the `Secret` object that contains the authentication credentials.
+<3> The key or keys in the specified `Secret` object that contain authentication credentials.
++
+The following sample config map settings configure Alertmanager to use a secret named `test-secret` and an authentication secret that uses a token named `test-api-receiver-token` in the `Secret` object:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-monitoring-config
+  namespace: openshift-monitoring
+data:
+  config.yaml: |
+    alertmanagerMain:
+      secrets:
+      - test-secret
+      - test-api-receiver-token
+----
+
+. Optional: To add the secret for use by Alertmanager in user-defined projects, add the secret name and key information under `data/config.yaml/alertmanager/secrets` in the `user-workload-monitoring-config` config map in the `openshift-user-workload-monitoring` project:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: user-workload-monitoring-config
+  namespace: openshift-user-workload-monitoring
+data:
+  config.yaml: |
+    alertmanager:
+      enabled: true
+      secrets:
+      - test-secret
+      - test-api-receiver-token
+----
++
+[NOTE]
+====
+Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects.
+====
+
+. Save the file to apply the changes to the `ConfigMap` object. 
+The new configuration is applied automatically.
+

modules/monitoring-configuring-external-alertmanagers.adoc

@@ -4,7 +4,7 @@
 
 :_content-type: PROCEDURE
 [id="monitoring-configuring-external-alertmanagers_{context}"]
-= Configuring external alertmanager instances
+= Configuring external Alertmanager instances
 
 The {product-title} monitoring stack includes a local Alertmanager instance that routes alerts from Prometheus.
 You can add external Alertmanager instances by configuring the `cluster-monitoring-config` config map in either the `openshift-monitoring` project or the `user-workload-monitoring-config` project.

modules/monitoring-configuring-secrets-for-alertmanager.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+// * monitoring/configuring-the-monitoring-stack.adoc
+
+:_content-type: CONCEPT
+[id="monitoring-configuring-secrets-for-alertmanager_{context}"]
+= Configuring secrets for Alertmanager
+
+The {product-title} monitoring stack includes Alertmanager, which routes alerts from Prometheus to endpoint receivers.
+If you need to authenticate with a receiver so that Alertmanager can send alerts to it, you can configure Alertmanager to use a secret that contains authentication credentials for the receiver.
+
+For example, you can configure Alertmanager to use a secret to authenticate with an endpoint receiver that requires a certificate issued by a private Certificate Authority (CA). 
+You can also configure Alertmanager to use a secret to authenticate with a receiver that requires a password file for Basic HTTP authentication.
+In either case, authentication details are contained in the `Secret` object rather than in the `ConfigMap` object.

monitoring/configuring-the-monitoring-stack.adoc

@@ -131,6 +131,10 @@ include::modules/monitoring-creating-scrape-sample-alerts.adoc[leveloffset=+2]
 //Configuring external alertmanagers
 include::modules/monitoring-configuring-external-alertmanagers.adoc[leveloffset=1]
 
+//Configuring secrets for Alertmanager
+include::modules/monitoring-configuring-secrets-for-alertmanager.adoc[leveloffset=1]
+include::modules/monitoring-adding-a-secret-to-an-alertmanager-configuration.adoc[leveloffset=2]
+
 //Attaching additional labels to your time series and alerts
 include::modules/monitoring-attaching-additional-labels-to-your-time-series-and-alerts.adoc[leveloffset=+1]