API Alertmanager Groups and Alerts Observability

How to create a new Alert Group and Alert Rule

You always need an Alert Group to add an Alert Rule.

Below is an example on how to create a new Alert Group and alert rule. You will need to set the following environment variables: PROJECT_ID to your project ID, INSTANCE_ID to your instance ID and API_TOKEN to your api access token.

Create API credential : API Prerequisites Observability - STACKIT

Example: Create a new Alert Group

curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups" \
-H "accept: application/json" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"TestAlertGroup","interval":"60s","rules":[{"alert":"HostCheck","expr":"up == 0","for":"60s","labels":{"severity":"critical"},"annotations":{"testAnnotation":"testAnnotation"}}]}'

The request body in the curl request to update the Alert Group can be seen below:

{
 "name": "TestAlertGroup",
 "interval": "60s",
 "rules": [
 {
 "alert": "HostCheck",
 "expr": "up == 0",
 "for": "60s",
 "labels": {
    "severity": "critical"
    },
 "annotations": {
    "testAnnotation": "testAnnotation"
    }
 }
 ]
}

An explanation of the request body follows:

Level	Field	Description
Alert Group	Name	Name of the Alert Group
Alert Group	Interval	Time interval at which the alert rules are evaluated
Alert Group	Rules	Array of alert rules; multiple rules can be defined in one Alert Group
Rule	Alert	Name of the individual Alert Rule
Rule	Expr	Expression to evaluate (e.g., up == 0 means the process is down)
Rule	For	Duration the condition must be true before the alert is triggered
Rule	Labels	Key-value pairs used to categorize or filter the alert
Rule	Annotations	Additional metadata such as alert description or helpful information

In the request body above we used the expression up == 0, below are more kubernetes specific examples:

Kubernetes Node not Ready

kube_node_status_condition{condition='Ready',status='true'} == 0

Expression to Alert on Failed Pods

kube_pod_status_phase{phase='Failed'} > 0

More Kubernetes examples can be found here.

How to change an existing Alert Rule

You always need an Alert Group to modify an Alert Rule.

Below is an example on how to update an existing alert rule. You will need to set the following environment variables: PROJECT_ID to your project ID, INSTANCE_ID to your instance ID and API_TOKEN to your api access token.

Example: Update an Alert Group config using curl

curl -X PUT "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/TestAlertGroup" \
-H "Authorization: Bearer $API_TOKEN" \
-H "accept: application/json" \
-d '{"interval": "60s","rules": [{"alert": "HostCheck","expr": "up == 0","for": "60s","labels": {"severity": "critical"},"annotations": {"testAnnotation":"testAnnotation"}},{"alert": "SystemLoad","expr": "system_load1{} >= 5",  "for": "60s","labels": {"severity": "warning"}}]}'

The request body in the curl request to update the Alert Group can be seen below:

Example: Alert Group update request body

{
 "interval": "60s",
 "rules": [
 {
 "alert": "HostCheck",
 "expr": "up == 0",
 "for": "60s",
 "labels": {
 "severity": "critical"
 },
 "annotations": {
 "testAnnotation": "testAnnotation"
 }
 },
 {
 "alert": "SystemLoad",
 "expr": "system_load1{} >= 5",
 "for": "60s",
 "labels": {
 "severity": "warning"
 }
 }
 ]
}

How to change the name of an Alert Group

Unfortunately, it is not possible to change the name of an Alert Group. You have to delete it and to create a new group using the desired name.

How to delete an Alert Rule

You can delete a specific alert rule from an Alert Group. Below is an example on deleting an alert rule from an Alert Group. You will need to set the following environment variables: PROJECT_ID to your project ID, INSTANCE_ID to your instance ID and API_TOKEN to your api access token:

Example: Delete an alert rule

curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/TestAlertGroup/alertrules/SystemLoad" \
-H "accept: application/json" \
-H "Authorization: Bearer $API_TOKEN"

How to delete an Alert Group

If you delete Alert Group, all alert rules belong to that Alert rules also get delete.

Below is an example on deleting an Alert Group. You will need to set the following environment variables: PROJECT_ID to your project ID, INSTANCE_ID to your instance ID and API_TOKEN to your api access token:

Example: Delete an Alert Group

curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups?groupName=TestAlertGroup" \
-H  "accept: application/json" \
-H "Authorization: Bearer $API_TOKEN"

An alternative way of deleting an Alert Group is:

Example: Delete an Alert Group

curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/TestAlertGroup" \
-H  "accept: application/json" \
-H "Authorization: Bearer $API_TOKEN"