---
title: "Configure usage groups for Grafana Cloud Metrics | Grafana Cloud documentation"
description: "Configure usage groups to gain visibility into who or whose systems are sending metrics to Grafana Cloud Metrics."
---

# Configure usage groups for Grafana Cloud Metrics

> Caution
> 
> Self-service configuration for this feature is not available yet. If you would like to configure or update it, contact Grafana Labs Support.

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](/docs/grafana-cloud/cost-management-and-billing/analyze-costs/metrics-costs/usage-groups/).
- Verify that you have access to the Grafana instance with Organization Admin privileges. For more information, refer to [About users and permissions](/docs/grafana/latest/administration/roles-and-permissions/).
- [Create a temporary service account with Admin rights](/docs/grafana/latest/administration/service-accounts/#create-a-service-account), and [add a token for that service account](/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-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](/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/).
  
  > 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](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

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:

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
  
  ```yaml
  apiVersion: mimir.ext.grafana.com/v1alpha1
  ```
- `kind`: Specifies the type of Kubernetes resource, and must be:
  
  YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
  
  ```yaml
  kind: MimirUsageGroupsConfiguration
  ```
- `metadata.names`: Defines a unique name for the resource within the namespace related to the customer’s stack.
  
  Example:
  
  YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
  
  ```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](/docs/grafana-cloud/cost-management-and-billing/analyze-costs/metrics-costs/usage-groups/#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](/docs/grafana-cloud/cost-management-and-billing/analyze-costs/metrics-costs/usage-groups/#define-label-selectors). The configuration is validated and normalized automatically before being applied.

## Related topics

- [Create usage groups for a customer without existing configuration](/docs/grafana-cloud/cost-management-and-billing/analyze-costs/metrics-costs/usage-groups/configure-usage-groups/create-new/)
- [Update usage groups for a customer with an existing configuration](/docs/grafana-cloud/cost-management-and-billing/analyze-costs/metrics-costs/usage-groups/configure-usage-groups/update-existing/)
- [Delete all usage groups for a customer with an existing configuration](/docs/grafana-cloud/cost-management-and-billing/analyze-costs/metrics-costs/usage-groups/configure-usage-groups/delete-existing/)