|
| 1 | +// Module included in the following assemblies: |
| 2 | +// |
| 3 | +// * observability/monitoring/managing-alerts.adoc |
| 4 | + |
| 5 | +:_mod-docs-content-type: PROCEDURE |
| 6 | +[id="creating-cross-project-alerting-rules-for-user-defined-projects_{context}"] |
| 7 | += Creating cross-project alerting rules for user-defined projects |
| 8 | + |
| 9 | +You can create alerting rules for user-defined projects that are not bound to their project of origin by configuring a project in the `user-workload-monitoring-config` config map. This allows you to create generic alerting rules that get applied to multiple user-defined projects instead of having individual `PrometheusRule` objects in each user project. |
| 10 | + |
| 11 | +.Prerequisites |
| 12 | + |
| 13 | +ifndef::openshift-dedicated,openshift-rosa[] |
| 14 | +* If you are a cluster administrator, you have access to the cluster as a user with the `cluster-admin` cluster role. |
| 15 | +* If you are a non-administrator user, you have access to the cluster as a user with the following user roles: |
| 16 | +** The `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project to edit the `user-workload-monitoring-config` config map. |
| 17 | +** The `monitoring-rules-edit` cluster role for the project where you want to create an alerting rule. |
| 18 | +* A cluster administrator has enabled monitoring for user-defined projects. |
| 19 | +endif::openshift-dedicated,openshift-rosa[] |
| 20 | +ifdef::openshift-dedicated,openshift-rosa[] |
| 21 | +* You have access to the cluster as a user with the `dedicated-admin` role. |
| 22 | ++ |
| 23 | +[NOTE] |
| 24 | +==== |
| 25 | +If you are a non-administrator user, you can still create cross-project alerting rules if you have the `monitoring-rules-edit` cluster role for the project where you want to create an alerting rule. However, that project needs to be configured in the `user-workload-monitoring-config` config map under the `namespacesWithoutLabelEnforcement` property, which can be done only by cluster administrators. |
| 26 | +==== |
| 27 | +* The `user-workload-monitoring-config` `ConfigMap` object exists. This object is created by default when the cluster is created. |
| 28 | +endif::openshift-dedicated,openshift-rosa[] |
| 29 | +* You have installed the OpenShift CLI (`oc`). |
| 30 | +
|
| 31 | +.Procedure |
| 32 | + |
| 33 | +. Edit the `user-workload-monitoring-config` config map in the `openshift-user-workload-monitoring` project: |
| 34 | ++ |
| 35 | +[source,terminal] |
| 36 | +---- |
| 37 | +$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config |
| 38 | +---- |
| 39 | + |
| 40 | +. Configure projects in which you want to create alerting rules that are not bound to a specific project: |
| 41 | ++ |
| 42 | +[source,yaml] |
| 43 | +---- |
| 44 | +apiVersion: v1 |
| 45 | +kind: ConfigMap |
| 46 | +metadata: |
| 47 | + name: user-workload-monitoring-config |
| 48 | + namespace: openshift-user-workload-monitoring |
| 49 | +data: |
| 50 | + config.yaml: | |
| 51 | + namespacesWithoutLabelEnforcement: [ <namespace> ] # <1> |
| 52 | + # ... |
| 53 | +---- |
| 54 | +<1> Specify one or more projects in which you want to create cross-project alerting rules. Prometheus and Thanos Ruler for user-defined monitoring do not enforce the `namespace` label in `PrometheusRule` objects created in these projects. |
| 55 | + |
| 56 | +. Create a YAML file for alerting rules. In this example, it is called `example-cross-project-alerting-rule.yaml`. |
| 57 | + |
| 58 | +. Add an alerting rule configuration to the YAML file. |
| 59 | +The following example creates a new cross-project alerting rule called `example-security`. The alerting rule fires when a user project does not enforce the restricted pod security policy: |
| 60 | ++ |
| 61 | +.Example cross-project alerting rule |
| 62 | +[source,yaml] |
| 63 | +---- |
| 64 | +apiVersion: monitoring.coreos.com/v1 |
| 65 | +kind: PrometheusRule |
| 66 | +metadata: |
| 67 | + name: example-security |
| 68 | +namespace: ns1 #<1> |
| 69 | +spec: |
| 70 | + groups: |
| 71 | + - name: pod-security-policy |
| 72 | + rules: |
| 73 | + - alert: "ProjectNotEnforcingRestrictedPolicy" # <2> |
| 74 | + for: 5m # <3> |
| 75 | + expr: kube_namespace_labels{namespace!~"(openshift|kube).*|default",label_pod_security_kubernetes_io_enforce!="restricted"} # <4> |
| 76 | + annotations: |
| 77 | + message: "Restricted policy not enforced. Project {{ $labels.namespace }} does not enforce the restricted pod security policy." #<5> |
| 78 | + labels: |
| 79 | + severity: warning # <6> |
| 80 | +---- |
| 81 | +<1> Ensure that you specify the project that you defined in the `namespacesWithoutLabelEnforcement` field. |
| 82 | +<2> The name of the alerting rule you want to create. |
| 83 | +<3> The duration for which the condition should be true before an alert is fired. |
| 84 | +<4> The PromQL query expression that defines the new rule. |
| 85 | +<5> The message associated with the alert. |
| 86 | +<6> The severity that alerting rule assigns to the alert. |
| 87 | ++ |
| 88 | +[IMPORTANT] |
| 89 | +==== |
| 90 | +Ensure that you create a specific cross-project alerting rule in only one of the projects that you specified in the `namespacesWithoutLabelEnforcement` field. |
| 91 | +If you create the same cross-project alerting rule in multiple projects, it results in repeated alerts. |
| 92 | +==== |
| 93 | +
|
| 94 | +. Apply the configuration file to the cluster: |
| 95 | ++ |
| 96 | +[source,terminal] |
| 97 | +---- |
| 98 | +$ oc apply -f example-cross-project-alerting-rule.yaml |
| 99 | +---- |
0 commit comments