Use gcx to manage alerting resources
gcx is a command-line interface (CLI) that you and coding agents can use to manage Grafana resources. It provides two ways to manage alerting resources:
gcx alertcommands to inspect and manage alerting resources, such as contact points, notification policies, and templates. Use them, from the CLI or with a coding agent, to check the state of your alert rules, review alert instances and history, make one-off changes, and manage resources thatgcx resourcesdoesn’t support, such as contact points.gcx resourcescommands to export and provision alerting resources as manifest files. Use them to keep alert rules in version control, review changes before you apply them, and apply the same alert rules to other Grafana instances. Provisioned alert rules and recording rules cannot be edited in the Grafana UI.
Before you begin
Authenticate
gcxwith the preferred method for your Grafana instance.To check which configuration
gcxuses, run:gcx config view
Manage resources with gcx alert
Use gcx alert to inspect and manage alerting resources. Each resource type has its own commands.
Note
The
gcx alertcommands are in active development.Run
gcx alert --helporgcx alert <RESOURCE> --helpto see what your version supports.
Caution
Contact points can contain credentials.
Grafana exports secure fields as
[REDACTED], so exported files don’t contain secrets. Replace these placeholders with the required values before provisioning.
Manage resources using CRUD operations
Use the operations available for each resource type to create, read, update, or delete resources. The following examples use contact points:
Create a contact point from a file. For example, save the following definition as
contact-point.yaml:name: team-webhook type: webhook settings: url: https://example.com/alertsThen create the contact point:
gcx alert contact-points create --filename contact-point.yamlList contact points to verify that the new one exists:
gcx alert contact-points listThis command returns the contact points with their UID, name, type, and provenance state.
┌──────────────────┬─────────────────┬──────────┬─────────────┐ │ UID │ NAME │ TYPE │ PROVENANCE │ ├────-─────────────┼──────-──────────┼──────────┼─────────────┤ │ dg40y30b347wgb │ team-webhook | webhook │ │ └──────-───────────┴─────────────────┴──────────┴─────────────┘Get an existing contact point and save it to a file for editing. Use
-o(--output) to choose the output format,jsonoryaml:gcx alert contact-points get <UID> -o yaml > contact-point.yamlUpdate a contact point. Edit the file and run
updatewith the contact pointUID:gcx alert contact-points update <UID> --filename contact-point.yamlDelete a contact point by its
UID:gcx alert contact-points delete <UID>gcxasks for confirmation before it deletes the contact point. To skip the prompt, add--force.
Some operations replace or update existing data:
gcx alert notification-policies setreplaces the entire notification policy tree. Export the current tree before you run it.gcx alert templates upsertcreates a template or updates it if a template with the same name exists.
Export resources for provisioning
Use export to save existing resources in the Grafana provisioning format:
gcx alert contact-points export --format yaml > contact-points.yamlUse the yaml format with
file provisioning or hcl with
Terraform.
Disable updates in the Grafana UI
By default, resources written by gcx alert are editable in the Grafana UI.
To prevent UI updates so that a resource can only be changed through provisioning, set --allow-ui-updates=false:
gcx alert contact-points create --filename contact-point.yaml --allow-ui-updates=falseThe allow-ui-updates flag is available on the following commands:
gcx alert contact-points createandupdategcx alert mute-timings createandupdategcx alert templates upsertgcx alert notification-policies set
Manage resources with gcx resources
Use gcx resources to export and provision alerting resources as manifest files that you can store in version control.
Use pull to export existing alert rules to a local directory:
gcx resources pull alertrules --path ./config/✔ 3 resources pulled, 0 errorsBy default, gcx resources pull writes JSON and names each file after metadata.name.
Use push to provision the alert rules saved into the directory.
gcx resources push alertrules --path ./config/✔ 3 resources pushed, 0 errorsTo push one resource, add its metadata.name to the selector:
gcx resources push alertrules/<UID> --path ./config/✔ 1 resources pushed, 0 errorsNote
Pushing an existing resource replaces it.
Provisioned alert rules and recording rules are marked as Provisioned in the Grafana UI and cannot be edited there. This prevents UI changes that would be overwritten when the resource is provisioned again.
Supported alerting resources
gcx resources supports a subset of alerting resource types.
The supported types depend on the API provided by your Grafana version. Resources that include secrets, such as contact points, are currently excluded.
To list the resource types your instance serves, run:
gcx resources list-types --no-schema -o text | grep alerting | grep -w v1beta1notifications.alerting.grafana.app v1beta1 routingtrees
notifications.alerting.grafana.app v1beta1 templategroups
notifications.alerting.grafana.app v1beta1 timeintervals
rules.alerting.grafana.app v1beta1 alertrules
rules.alerting.grafana.app v1beta1 recordingrules
rules.alerting.grafana.app v1beta1 rulesequencesProvision alert rules into a new Grafana instance
Before pushing alert rules to a new Grafana instance, check the following requirements.
Include the folders.
Alert rules belong to a folder, and that folder must exist in the target instance. If a folder is missing, the push fails with the following error:
403 Forbidden: alertrules.rules.alerting.grafana.app "<UID>" is forbidden: folder does not existYou can pull folders and alert rules into the same directory and push them together.
gcxpushes folders before other resources:gcx resources pull folders alertrules --path ./config/ gcx --context <NEW_INSTANCE> resources push folders alertrules --path ./config/Remove the group labels.
Pulled rules might include the
grafana.com/groupandgrafana.com/group-indexlabels. The target instance rejects rules with these labels when creating them:403 Forbidden: alertrules.rules.alerting.grafana.app "<UID>" is forbidden: cannot set group when creating a new ruleIf the push fails with this error, remove the
grafana.com/groupandgrafana.com/group-indexlabels from the alert rule files and push again.


