> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Alertmanager Rules > Guide for creating AlertmanagerConfig CRDs, configuring Helm selectors so Alertmanager discovers them, converting alertmanager.yml to CRD syntax, applying examples and troubleshooting The Prometheus Operator exposes an AlertmanagerConfig CRD to register Alertmanager routes and receivers from Kubernetes. This guide shows how to create AlertmanagerConfig objects, ensure Alertmanager discovers them, and how to configure the Helm chart so the Alertmanager picks them up. AlertmanagerConfig objects defined in Kubernetes follow the Prometheus Operator CRD schema and are mapped to Alertmanager configuration. They are not automatically discovered unless Alertmanager's `alertmanagerConfigSelector` (and optionally `alertmanagerConfigNamespaceSelector`) are configured to match your labels. ## Basic AlertmanagerConfig example This is a minimal AlertmanagerConfig CRD that routes grouped alerts to a webhook receiver: ```yaml theme={null} apiVersion: monitoring.coreos.com/v1alpha1 kind: AlertmanagerConfig metadata: name: alert-config labels: resource: prometheus spec: route: groupBy: ["severity"] groupWait: 30s groupInterval: 5m repeatInterval: 12h receiver: "webhook" receivers: - name: "webhook" webhookConfigs: - url: "http://example.com/" ``` Key parts: * `metadata.labels` — used to match this object to Alertmanager instances (via `alertmanagerConfigSelector`). * `spec.route` — route behavior (grouping and timing). * `spec.receivers` — one or more receivers (here: webhook). ## Why Alertmanager might not pick up your AlertmanagerConfig When installed via the kube-prometheus-stack Helm chart, the Alertmanager StatefulSet/Deployment includes two fields in its spec: ```yaml theme={null} spec: alertmanagerConfigNamespaceSelector: {} alertmanagerConfigSelector: {} ``` By default these are empty, meaning Alertmanager will not match any AlertmanagerConfig objects. You must set `alertmanagerConfigSelector` (and optionally `alertmanagerConfigNamespaceSelector`) in the chart values so Alertmanager can discover AlertmanagerConfig objects by label. If you do not configure a selector in the Helm chart values, Alertmanager will ignore AlertmanagerConfig objects even if they exist in the cluster. ## Important syntax differences: alertmanager.yml vs AlertmanagerConfig CRD When converting an `alertmanager.yml` (standalone Alertmanager config) to an `AlertmanagerConfig` CRD, note two common differences: * Property naming: standalone `alertmanager.yml` uses snake\_case (e.g., `group_wait`), while the CRD uses camelCase (e.g., `groupWait`). * Label matchers: in `alertmanager.yml` you can write `job: kubernetes`. In the CRD matchers must be objects with `name` and `value`. Comparison: | Feature | alertmanager.yml (standalone) | AlertmanagerConfig CRD | | --------------- | ----------------------------------------------- | ---------------------------------------------------------------------- | | Grouping/timing | `group_wait: 30s` | `groupWait: 30s` | | Group by | `group_by: ['severity']` | `groupBy: ["severity"]` | | Matcher example | `routes:\n - matchers:\n job: kubernetes` | `routes:\n - matchers:\n - name: job\n value: kubernetes` | Example pair: alertmanager.yml ```yaml theme={null} route: receiver: staff group_by: ['severity'] group_wait: 30s group_interval: 5m repeat_interval: 12h routes: - matchers: job: kubernetes receiver: infra group_by: ['severity'] ``` AlertmanagerConfig CRD (equivalent) ```yaml theme={null} spec: route: groupBy: ["alertname"] groupWait: 30s groupInterval: 5m repeatInterval: 12h receiver: "webhook" routes: - matchers: - name: job value: kubernetes receiver: "infra" groupBy: ["severity"] ``` ## Configure the Helm chart so Alertmanager finds AlertmanagerConfig objects 1. Retrieve the default values for the kube-prometheus-stack chart: ```bash theme={null} helm show values prometheus-community/kube-prometheus-stack > values.yaml ``` 2. Edit `values.yaml` and set `alertmanagerConfigSelector` to match the labels you will use on AlertmanagerConfig objects. For example, to match `resource: prometheus`: ```yaml theme={null} alertmanagerConfigSelector: matchLabels: resource: prometheus ``` You can choose any label key/value pair; just use the same one on your AlertmanagerConfig objects. 3. Upgrade the Helm release using the modified values file: ```bash theme={null} helm upgrade prometheus prometheus-community/kube-prometheus-stack -f values.yaml ``` After the upgrade, the Alertmanager resource in the cluster should include the selector configuration: ```yaml theme={null} spec: alertmanagerConfigNamespaceSelector: {} alertmanagerConfigSelector: matchLabels: resource: prometheus ``` ## Create and apply an AlertmanagerConfig Create a file `alert.yaml` with the same example CRD (note `metadata.labels` matches the Helm selector): ```yaml theme={null} apiVersion: monitoring.coreos.com/v1alpha1 kind: AlertmanagerConfig metadata: name: alert-config labels: resource: prometheus spec: route: groupBy: ["severity"] groupWait: 30s groupInterval: 5m repeatInterval: 12h receiver: "webhook" receivers: - name: "webhook" webhookConfigs: - url: "http://example.com/" ``` Apply it: ```bash theme={null} kubectl apply -f alert.yaml # Expected output: # alertmanagerconfig.monitoring.coreos.com/alert-config created ``` Verify the resource exists: ```bash theme={null} kubectl get alertmanagerconfig # NAME AGE # alert-config 17s ``` ## Verify the Alertmanager configuration in the UI Port-forward to the Alertmanager service and inspect the configuration via the status page: 1. Find the Alertmanager service (commonly `alertmanager-operated`): ```bash theme={null} kubectl get svc ``` 2. Port-forward to 9093: ```bash theme={null} kubectl port-forward service/alertmanager-operated 9093:9093 ``` 3. Open [http://localhost:9093/](http://localhost:9093/) in your browser and inspect the “Status -> Configuration” page. You should see your webhook receiver and routing as part of the Alertmanager configuration generated from your AlertmanagerConfig CRD. ## Troubleshooting tips * If you see no AlertmanagerConfig objects in the Alertmanager UI but they exist in Kubernetes, re-check that: * The Helm chart `alertmanagerConfigSelector` matches the labels on your AlertmanagerConfig objects. * If you used namespace selectors, ensure `alertmanagerConfigNamespaceSelector` is set appropriately. * Use `kubectl get alertmanagers.monitoring.coreos.com -o yaml` to inspect the Alertmanager CRD instance spec and verify selectors. * Review the operator logs (Prometheus Operator) for errors about parsing AlertmanagerConfig objects. Useful references: * kube-prometheus-stack Helm chart: [https://github.com/prometheus-community/helm-charts](https://github.com/prometheus-community/helm-charts) * Prometheus Operator AlertmanagerConfig CRD: [https://github.com/prometheus-operator/prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) * Kubernetes basics: [https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/](https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/)