Prior to OpenShift Container Platform 4, the Prometheus Cluster Monitoring stack was configured through the Ansible inventory file. For that purpose, the stack exposed a subset of its available configuration options as Ansible variables. You configured the stack before you installed OpenShift Container Platform.

In OpenShift Container Platform 4, Ansible is not the primary technology to install OpenShift Container Platform anymore. The installation program provides only a very low number of configuration options before installation. Configuring most OpenShift framework components, including the Prometheus Cluster Monitoring stack, happens post-installation.

This section explains what configuration is supported, shows how to configure the monitoring stack, and demonstrates several common configuration scenarios.

Prerequisites
  • The monitoring stack imposes additional resource requirements. Consult the computing resources recommendations in Scaling the Cluster Monitoring Operator and verify that you have sufficient resources.

Maintenance and support

The supported way of configuring OpenShift Container Platform Monitoring is by configuring it using the options described in this document. Do not use other configurations, as they are unsupported. Configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use configurations other than those described in this section, your changes will disappear because the cluster-monitoring-operator reconciles any differences. The operator reverses everything to the defined state by default and by design.

Explicitly unsupported cases include:

  • Creating additional ServiceMonitor objects in the openshift-monitoring namespace. This extends the targets the cluster monitoring Prometheus instance scrapes, which can cause collisions and load differences that cannot be accounted for. These factors might make the Prometheus setup unstable.

  • Creating unexpected ConfigMap objects or PrometheusRule objects. This causes the cluster monitoring Prometheus instance to include additional alerting and recording rules.

  • Modifying resources of the stack. The Prometheus Monitoring Stack ensures its resources are always in the state it expects them to be. If they are modified, the stack will reset them.

  • Using resources of the stack for your purposes. The resources created by the Prometheus Cluster Monitoring stack are not meant to be used by any other resources, as there are no guarantees about their backward compatibility.

  • Stopping the Cluster Monitoring Operator from reconciling the monitoring stack.

  • Adding new alerting rules.

  • Modifying the monitoring stack Grafana instance.

Creating cluster monitoring ConfigMap

To configure the Prometheus Cluster Monitoring stack, you must create the cluster monitoring ConfigMap.

Prerequisites
  • An installed oc CLI tool

  • Administrative privileges for the cluster

Procedure
  1. Check whether the cluster-monitoring-config ConfigMap object exists:

    $ oc -n openshift-monitoring get configmap cluster-monitoring-config
  2. If it does not exist, create it:

    $ oc -n openshift-monitoring create configmap cluster-monitoring-config
  3. Start editing the cluster-monitoring-config ConfigMap:

    $ oc -n openshift-monitoring edit configmap cluster-monitoring-config
  4. Create the data section if it does not exist yet:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |

Configuring the cluster monitoring stack

You can configure the Prometheus Cluster Monitoring stack using ConfigMaps. ConfigMaps configure the Cluster Monitoring Operator, which in turn configures components of the stack.

Prerequisites
  • Make sure you have the cluster-monitoring-config ConfigMap object with the data/config.yaml section.

Procedure
  1. Start editing the cluster-monitoring-config ConfigMap:

    $ oc -n openshift-monitoring edit configmap cluster-monitoring-config
  2. Put your configuration under data/config.yaml as key-value pair <component_name>: <component_configuration>:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        component:
          configuration for the component

    Substitute <component> and <configuration for the component> accordingly.

    For example, create this ConfigMap to configure a Persistent Volume Claim (PVC) for Prometheus:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        prometheusK8s:
          volumeClaimTemplate:
           spec:
             storageClassName: gluster-block
             resources:
               requests:
                 storage: 40Gi

    Here, prometheusK8s defines the Prometheus component and the following lines define its configuration.

Configurable monitoring components

This table shows the monitoring components you can configure and the keys used to specify the components in the ConfigMap:

Table 1. Configurable monitoring components
Component Key

Prometheus Operator

prometheusOperator

Prometheus

prometheusK8s

Alertmanager

alertmanagerMain

kube-state-metrics

kubeStateMetrics

Grafana

grafana

Telemeter Client

telemeterClient

Prometheus Adapter

k8sPrometheusAdapter

From this list, only Prometheus and Alertmanager have extensive configuration options. All other components usually provide only the nodeSelector field for being deployed on a specified node.

Moving monitoring components to different nodes

You can move any of the monitoring stack components to specific nodes.

Prerequisites
  • Make sure you have the cluster-monitoring-config ConfigMap object with the data/config.yaml section.

Procedure
  1. Start editing the cluster-monitoring-config ConfigMap:

    $ oc -n openshift-monitoring edit configmap cluster-monitoring-config
  2. Specify the nodeSelector constraint for the component under data/config.yaml:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        component:
          nodeSelector:
            node key: node value
            node key: node value
            ...

    Substitute <component> accordingly and substitute <node key>: <node value> with the map of key-value pairs that specifies the destination node. Often, only a single key-value pair is used.

    The component can only run on a node that has each of the specified key-value pairs as labels. The node can have additional labels as well.

    For example, to move components to the node that is labeled foo: bar, use:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        prometheusOperator:
          nodeSelector:
            foo: bar
        prometheusK8s:
          nodeSelector:
            foo: bar
        alertmanagerMain:
          nodeSelector:
            foo: bar
        kubeStateMetrics:
          nodeSelector:
            foo: bar
        grafana:
          nodeSelector:
            foo: bar
        telemeterClient:
          nodeSelector:
            foo: bar
        k8sPrometheusAdapter:
          nodeSelector:
            foo: bar
Additional resources

Configuring persistent storage

Running cluster monitoring with persistent storage means that your metrics are stored to a Persistent Volume and can survive a pod being restarted or recreated. This is ideal if you require your metrics or alerting data to be guarded from data loss. For production environments, it is highly recommended to configure persistent storage.

In OpenShift Container Platform 4.1 deployed on bare metal, Prometheus and Alertmanager cannot have persistent storage and are ephemeral only. For use cases other than bare metal, you must use dynamic provisioning to use persistent storage. In particular, do not use NFS for the monitoring stack.

Prerequisites
  • Dedicate sufficient persistent storage to ensure that the disk does not become full. How much storage you need depends on the number of pods. For information on system requirements for persistent storage, see Prometheus database storage requirements.

  • Unless you enable dynamically-provisioned storage, make sure you have a Persistent Volume (PV) ready to be claimed by the Persistent Volume Claim (PVC), one PV for each replica. Since Prometheus has two replicas and Alertmanager has three replicas, you need five PVs to support the entire monitoring stack.

  • Use the block type of storage.

Configuring a persistent volume claim

For the Prometheus or Alertmanager to use a persistent volume (PV), you first must configure a persistent volume claim (PVC).

Prerequisites
  • Make sure you have the necessary storage class configured.

  • Make sure you have the cluster-monitoring-config ConfigMap object with the data/config.yaml section.

Procedure
  1. Edit the cluster-monitoring-config ConfigMap:

    $ oc -n openshift-monitoring edit configmap cluster-monitoring-config
  2. Put your PVC configuration for the component under data/config.yaml:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        component:
          volumeClaimTemplate:
            metadata:
              name: PVC name
            spec:
              storageClassName: storage class
              resources:
                requests:
                  storage: 40Gi

    See the Kubernetes documentation on PersistentVolumeClaims for information on how to specify volumeClaimTemplate.

    For example, to configure a PVC that claims any configured OpenShift Container Platform block PV as a persistent storage for Prometheus, use:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        prometheusK8s:
          volumeClaimTemplate:
            metadata:
              name: my-prometheus-claim
            spec:
              storageClassName: gluster-block
              resources:
                requests:
                  storage: 40Gi

    And to configure a PVC that claims any configured OpenShift Container Platform block PV as a persistent storage for Alertmanager, you can use:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        alertmanagerMain:
          volumeClaimTemplate:
            metadata:
              name: my-alertmanager-claim
            spec:
              storageClassName: gluster-block
              resources:
                requests:
                  storage: 40Gi

Modifying retention time for Prometheus metrics data

By default, the Prometheus Cluster Monitoring stack configures the retention time for Prometheus data to be 15 days. You can modify the retention time to change how soon the data is deleted.

Prerequisites
  • Make sure you have the cluster-monitoring-config ConfigMap object with the data/config.yaml section.

Procedure
  1. Start editing the cluster-monitoring-config ConfigMap:

    $ oc -n openshift-monitoring edit configmap cluster-monitoring-config
  2. Put your retention time configuration under data/config.yaml:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        prometheusK8s:
          retention: time specification

    Substitute <time specification> with a number directly followed by ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks), or y (years).

    For example, to configure retention time to be 24 hours, use:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
        prometheusK8s:
          retention: 24h

Configuring Alertmanager

The Prometheus Alertmanager is a component that manages incoming alerts, including:

  • Alert silencing

  • Alert inhibition

  • Alert aggregation

  • Reliable deduplication of alerts

  • Grouping alerts

  • Sending grouped alerts as notifications through receviers such as email, PagerDuty, and HipChat

Alertmanager default configuration

The default configuration of the OpenShift Container Platform Monitoring Alertmanager cluster is this:

global:
  resolve_timeout: 5m
route:
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 12h
  receiver: default
  routes:
  - match:
      alertname: Watchdog
    repeat_interval: 5m
    receiver: watchdog
receivers:
- name: default
- name: watchdog

OpenShift Container Platform monitoring ships with the Watchdog alert that always triggers by default to ensure the availability of the monitoring infrastructure.

Applying custom Alertmanager configuration

You can overwrite the default Alertmanager configuration by editing the alertmanager-main secret inside the openshift-monitoring namespace.

Prerequisites
  • An installed jq tool for processing JSON data

Procedure
  1. Print the currently active Alertmanager configuration into file alertmanager.yaml:

    $ oc -n openshift-monitoring get secret alertmanager-main --template='{{ index .data "alertmanager.yaml" }}' |base64 -d > alertmanager.yaml
  2. Change the configuration in file alertmanager.yaml to your new configuration:

    data:
     config.yaml: |
      global:
        resolve_timeout: 5m
      route:
        group_wait: 30s
        group_interval: 5m
        repeat_interval: 12h
        receiver: default
        routes:
        - match:
            alertname: Watchdog
          repeat_interval: 5m
          receiver: watchdog
        - match:
            service: _your service_ (1)
          routes:
          - match:
              _your matching rules_ (2)
            receiver: _receiver_ (3)
      receivers:
      - name: default
      - name: watchdog
      - name: _receiver_
        _receiver configuration_
    1 service specifies the service that fires the alerts.
    2 <your matching rules> specify the target alerts.
    3 receiver specifies the receiver to use for the alert.

    For example, this listing configures PagerDuty for notifications:

    data:
     config.yaml: |
      global:
        resolve_timeout: 5m
      route:
        group_wait: 30s
        group_interval: 5m
        repeat_interval: 12h
        receiver: default
        routes:
        - match:
            alertname: Watchdog
          repeat_interval: 5m
          receiver: watchdog
        - match:
            service: example-app
          routes:
          - match:
              severity: critical
            receiver: team-frontend-page
      receivers:
      - name: default
      - name: watchdog
      - name: team-frontend-page
        pagerduty_configs:
        - service_key: "your-key"

    With this configuration, alerts of critical severity fired by the example-app service are sent using the team-frontend-page receiver, which means that these alerts are paged to a chosen person.

  3. Apply the new configuration in the file:

    $ oc -n openshift-monitoring create secret generic alertmanager-main --from-literal=alertmanager.yaml="$(< alertmanager.yaml)" --dry-run -o=yaml | oc -n openshift-monitoring replace secret --filename=-
Additional resources

Alerting rules

OpenShift Container Platform Cluster Monitoring by default ships with a set of pre-defined alerting rules.

Note that:

  • The default alerting rules are used specifically for the OpenShift Container Platform cluster and nothing else. For example, you get alerts for a persistent volume in the cluster, but you do not get them for persistent volume in your custom namespace.

  • Currently you cannot add custom alerting rules.

  • Some alerting rules have identical names. This is intentional. They are sending alerts about the same event with different thresholds, with different severity, or both.

  • With the inhibition rules, the lower severity is inhibited when the higher severity is firing.

Additional resources
Next steps