---
title: Manage configuration groups
description: Group multiple Telegraf configurations into an ordered configuration group that agents retrieve from a single URL. Groups compose by reference, so updating a member configuration updates every group that includes it.
url: https://docs.influxdata.com/telegraf/controller/config-groups/
estimated_tokens: 694
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/config-groups/
date: '2026-08-25T08:20:28-06:00'
lastmod: '2026-08-25T08:20:28-06:00'
---

Configuration groups bundle multiple Telegraf configurations into an ordered
unit that agents retrieve in a single request. Instead of assigning each
agent its own stack of individual configurations, you assign the group.

Groups compose by reference, not by copy: a configuration can belong to
multiple groups, and editing a configuration propagates the change to every
group that includes it. This is what makes groups work as role profiles.
Build one base configuration with the system inputs every host runs, then
compose it with the configurations specific to a web server or a database
host. Tune the base configuration once and every role updates; there is no
drift between the web profile’s copy and the database profile’s copy,
because there are no copies. Groups also work as templates: a group that is
proven in production becomes the starting point for the next site or
deployment.

## How group TOML is rendered

When an agent or user requests a group’s TOML, Telegraf Controller renders
each member configuration in its listed order and concatenates the results
into a single TOML document. Each member’s section begins with a comment
that identifies the source configuration, so you can trace any plugin in the
merged output back to the configuration it came from.

Because members are rendered at request time:

* Changes to a member configuration appear in the group’s TOML immediately.
* Deleting a configuration removes it from every group that includes it.
* An empty group is valid and renders an empty configuration.

Groups cannot contain other groups; members are always individual
configurations.

## [Create and manage configuration groups](/telegraf/controller/config-groups/manage/)

Create Telegraf configuration groups, add and reorder member configurations, and manage group labels and lifecycle in Telegraf Controller.

## [Use configuration groups](/telegraf/controller/config-groups/use/)

Apply a Telegraf configuration group to your agents with a single URL, substitute values across member configurations, and keep agents up to date as the group changes.

## [Manage configuration group aliases](/telegraf/controller/config-groups/aliases/)

Assign aliases to Telegraf configuration groups and transfer an alias from a single configuration to a group to migrate agents without changing agent commands.

## Permissions

Configuration group operations require permissions on the**Config Groups** resource:

* **Read**: view groups and retrieve group TOML.
* **Write**: create groups, edit group details, and manage members, labels,
  and aliases.
* **Delete**: delete groups.

For how permissions map to user roles and API tokens, see[Authentication and authorization](/telegraf/controller/reference/authentication-authorization/).