Skip to main content
Connect Alertmanager to create and update incidents from firing and resolved alerts. OpenCluster receives webhooks; it does not call Alertmanager.

​
What OpenCluster uses it for

OpenCluster records the alert status, times, labels, annotations, fingerprint, and generator URL. It uses Alertmanager’s grouping key to group delivered alerts into an incident. The triggering alert becomes the starting context for an investigation.

​
Prerequisites

  • Prometheus Alertmanager 0.28.0 or later. Version 0.28.0 added the http_headers configuration used for the webhook secret; 0.27.0 and earlier reject it. OpenCluster tests the configuration below against Alertmanager 0.34.0.
  • Network access from Alertmanager to the OpenCluster intake endpoint over HTTPS.
  • The Admin role in OpenCluster.

​
Access

This integration is inbound only. The generated secret authenticates webhook deliveries in the X-OpenCluster-Token header. OpenCluster stores only a digest of the secret and cannot show it again. The static token authenticates the sender; it does not cryptographically sign the request body.

​
Connect

1

Create the integration

In Integrations, choose Prometheus Alertmanager, enter a name, and create the integration. Copy the webhook URL and secret from the response.
2

Configure Alertmanager

Add the receiver, then route alerts to it:
Reload Alertmanager after validating the configuration.

​
Verify

Fire a test alert, open the integration, and select Verify. Verification reports the time of the last accepted delivery. If no delivery has arrived, check the receiver, route, URL, secret, and network path.

​
During investigations

The alert supplies the incident timing, labels, annotations, runbook and dashboard URLs when present, and the generator URL. Alertmanager is not a live investigation source; OpenCluster cannot query silences, inhibitions, or other active alerts.

​
Delivery behavior

Deliveries can contain at most 2,048 alerts. Only firing and resolved statuses are accepted. If Alertmanager marks a delivery as truncated, OpenCluster records that the incident context is incomplete. One automatic Investigation opens per new Incident. Deliveries that join or resolve an existing Incident do not open another. Accepted duplicates and Incident updates can succeed even when the pending Investigation queue is full. When a new delivery cannot fit, none of its changes are recorded and 503 includes Retry-After. Accepted alert deliveries complete during admission. Exact retries remain idempotent and do not create another Alert Event, Incident, or Investigation.

​
Limitations

Alertmanager supplies alert lifecycle context, not runtime or change evidence. Its grouping key determines provisional Incident grouping and does not prove a shared cause. Connect Kubernetes, GitHub, or another evidence source when an Investigation needs to explain the alert.

​
Troubleshooting

  • Verify shows no delivery: send a firing test alert and check Alertmanager logs.
  • 401: replace the configured secret with the current value. Rotated secrets stop working immediately.
  • 400: confirm middleware has not changed Alertmanager’s version 4 webhook body. If an ungrouped batch exceeds the pending Investigation limit, split it into smaller deliveries or configure source grouping before retrying.
  • 503: honor Retry-After when present, reduce delivery frequency, or group alerts more aggressively. See the process-wide admission limit.

​
Rotate or disconnect

Rotating creates a new secret and invalidates the old one immediately. Update Alertmanager in the same maintenance step. Disable the integration to reject new deliveries while retaining incident history. Deletion is refused when retained records depend on the integration.

​
Next step

Connect an evidence source, then run the first Investigation from a test alert.

​
Availability

Prometheus Alertmanager is available in OSS v0.1. Alertmanager and its mark belong to the Prometheus project. Review the provider webhook contract.