Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Agent Management - Experimental
Agent Management is under active development. Backwards incompatible changes to its API are to be expected. Feedback is much appreciated. This is a feature that MAY NOT make it production.
Agent Management enables centralized management of fleets of Grafana Agents.
In this mode, Grafana Agent polls and dynamically reloads its configuration from a remote API server.
Remote Configurations are composed of a base configuration and a set of snippets. Snippets are applied conditionally via label matching.
Configuration
Agent Management can be used by passing the flag -enable-features=agent-management
. When enabled, the file referred to -config.file
will be loaded as an agent management configuration file.
Agent Management configuration files are YAML documents which conform the following schema:
API
Grafana Agents with Agent Management enabled continuously poll the API server for an up-to-date configuration. The API server is expected to implement a GET /agent-management/api/agent/v2/namespace/:namespace/remote_config
HTTP endpoint returning a successful response with the following body format:
# The base configuration for the Agent.
base_config: |
<grafana_agent_config>
# A set of snippets to be conditionally merged into the base configuration.
snippets:
[ <snippet_name>: <snippet_content> ... ]
grafana_agent_config
This is a standard Grafana Agent static mode configuration. Typically used to configure the server, remote_writes, and other global configuration.
snippet_content
The snippet content is a YAML document which conforms to the following schema:
# Config provides the actual snippet configuration.
config: |
[metrics_scrape_configs]:
- [<scrape_config> ... ]
[logs_scrape_configs]:
- [<promtail.scrape_config> ... ]
[integration_configs]:
[<integrations_config> ... ]
# Selector is a set of labels used to decide which snippets to apply to the final configuration.
selector:
[ <labelname>: <labelvalue> ... ]
Note: More information on the following types can be found in their respective documentation pages:
Note: Snippet selection is currently done in the API server. This behaviour is subject to change in the future.
Example response body
Note: Base configurations and snippets can contain go’s text/template actions. If you need preserve the literal value of a template action, you can escape it using backticks. For example:
{{ `{{ .template_var }}` }}