Configure usage groups for Grafana Cloud Metrics

This documentation provides guidance on configuring usage groups for Grafana Cloud customers. It covers how to create usage group configurations for tenants that do not yet have them, as well as how to view, update, or delete existing configurations.

By following this guide, you can manage usage groups in a consistent and reliable way using the automated workflow, ensuring configurations are correctly applied and maintained across Mimir environments.

Before you begin

Before configuring usage groups, make sure the following prerequisites are met:

Familiarize yourself with what usage groups are used for and the syntax constraints for defining them. For more information, refer to Usage groups for Grafana Cloud Metrics.
Verify that you have access to the Grafana instance with Organization Admin privileges. For more information, refer to About users and permissions.
Create a temporary service account with Admin rights, and add a token for that service account to be used with the Grafana CLI.
Install and set up the Grafana CLI to interact with your Grafana Cloud resources. This documentation uses gcx CLI, but it remains fully compatible with the deprecated grafanactl CLI. For instructions on installation, configuration, and usage, refer to Introduction to Grafana CLI.
Note
For the remainder of this documentation, it is assumed that gcx CLI is configured to use the <CONTEXT> context.

Configuration of Usage Groups

Usage groups are managed through an automated, declarative workflow. You define the configuration using a MimirUsageGroupsConfiguration Kubernetes Custom Resource.

After submission, the configuration is automatically validated and normalized. If valid, it is propagated and applied to the appropriate Mimir environment associated with your stack using Grafana and GEM-specific tooling.

With this approach you can create, update, or delete usage groups reliably, without requiring support intervention.

MimirUsageGroupsConfiguration resources

MimirUsageGroupsConfiguration resources define usage groups. They follow the standard Kubernetes resource structure, with the spec section containing the configuration.

The following example shows a basic configuration:

apiVersion: mimir.ext.grafana.com/v1alpha1
kind: MimirUsageGroupsConfiguration
metadata:
  name: config
spec:
  usageGroups:
    grafanacloud_usage_group/errors: '{status=~"5.."}'
    grafanacloud_usage_group/production: '{env=~"prod.*"}'

The following fields are mandatory when defining a MimirUsageGroupsConfiguration resource:

apiVersion: Specifies the API version of the resource, and is currently:
YAML
```
apiVersion: mimir.ext.grafana.com/v1alpha1
```
kind: Specifies the type of Kubernetes resource, and must be:
YAML
```
kind: MimirUsageGroupsConfiguration
```
metadata.names: Defines a unique name for the resource within the namespace related to the customer’s stack.
Example:
YAML
```
metadata:
  name: config
```
spec.usageGroups: This is the most important field, containing the actual usage group definitions.
- It is a map of <name>: <matcher> pairs.
- The key is the usage group name (must follow required naming conventions, such as the grafanacloud_usage_group/ prefix). For more details, refer to Usage group naming conventions.
- The value is a Prometheus-style label matcher expression that defines which metrics belong to the group. For more details, refer to Define label selectors. The configuration is validated and normalized automatically before being applied.