docs-v2/content/telegraf/controller/configs/use.md

title	seotitle	description	menu	weight
Use Telegraf configurations	Use Telegraf configuration managed with Telegraf Controller	Use Telegraf configuration files managed with Telegraf Controller to configure your running Telegraf agents.	telegraf_controller name parent Use configurations Manage configurations	104

Use Telegraf Controller to centralize management of your Telegraf configurations and keep your agents consistent across environments. Apply the configuration by pointing your agents to the configuration URL.

• Apply a configuration to an agent
• Set dynamic values
  • Set parameter values
  • Set environment variables
• Auto-update agents
• Use {{% product-name %}} to build commands

Apply a configuration to an agent

When starting a Telegraf agent, use a --config flag with the {{% product-name %}} configuration TOML API URL—for example:

telegraf \
  --config "http://localhost:8888/api/configs/xxxxxx/toml"

[!Note] A single Telegraf agent can use multiple configurations. Provide each with a distinct --config flag. Telegraf merges the configurations at runtime.

Telegraf retrieves and validates the configuration from {{% product-name %}} and then starts the telegraf process using the loaded configuration.

Set dynamic values

Telegraf and {{% product-name %}} let you dynamically set values in your configuration files using parameters, environment variables, and secrets.

• Set parameter values
• Set environment variables

Set parameter values

Configuration parameters use the &{param_name[:default_value]} syntax in TOML configurations. Use URL-encoded query parameters in your configuration URL to define parameter values—for example:

Configuration TOML with a parameter

{{% telegraf/dynamic-values %}}

[[outputs.heartbeat]]
  instance_id = "&{agent_id}"
  # ...

{{% /telegraf/dynamic-values %}}

Set the parameter value in the configuration URL

{{% code-callout "agent_id=my-agent-123" "magenta" %}}

telegraf \
  --config "http://localhost:8888/api/configs/xxxxxx/toml?agent_id=my-agent-123"

{{% /code-callout %}}

[!Important] If you request a configuration without providing values for required parameters, {{% product-name %}} returns an error.

Set environment variables

Telegraf environment variables use the ${VAR_NAME[:-default_value]} syntax in TOML configurations. Set environment variable values in the Telegraf agent's environment before starting Telegraf—for example:

Configuration TOML with an environment variable

{{% telegraf/dynamic-values %}}

[[inputs.http]]
  urls = ["http://localhost:8080/metrics"]

  [inputs.http.headers]
    Authorization = "Bearer ${AUTH_TOKEN}"

{{% /telegraf/dynamic-values %}}

Set the environment variable before starting Telegraf

AUTH_TOKEN=x00x0xx00xxxX0xXXx0000xxxX000x00XXxXx

telegraf \
  --config "http://localhost:8888/api/configs/xxxxxx/toml"

Auto-update agents

For agents to automatically recognize and load updates to their configuration, include the --config-url-watch-interval with a duration value that specifies how often the agent should check for updates—for example:

telegraf \
  --config https://locahost:8888/api/configs/xxxxxx/toml \
  --config-url-watch-interval 1h

In this example, the agent will check for configuration changes every hour and automatically reload the configuration if the configuration has been updated.

Use {{% product-name %}} to build commands

{{% product-name %}} provides a tool for building telegraf commands using parameters, environment variables, auto-update functionality, and Telegraf label selectors. To use this tool:

1. In the {{% product-name %}} web interface, select Configurations in the navigation bar.

2. Click the name of the configuration you want to use.

3. Click Use this Configuration to open the modal window.

   {{< img-hd src="/img/telegraf/controller-command-builder.png" alt="Build Telegraf commands with Telegraf Controller" />}}

4. Define dynamic values and select options for your command:

   • Set environment variable values
   • Set parameter values
   • Enable automatic configuration updates and specify the check interval
   • Add label selectors to run certain plugins based on configuration labels

5. Click Copy Commands to copy the contents of the codeblock to your clipboard. The tool provides commands for Linux, macOS, and Windows (PowerShell).

   [!Warning] Your browser may not allow the Copy Commands button to copy to your clipboard under the following conditions:

   • You're using an IP or domain name other than 0.0.0.0 or localhost and
   • You're using HTTP, not HTTPS