156 lines
5.2 KiB
Markdown
156 lines
5.2 KiB
Markdown
---
|
|
title: Use Telegraf configurations
|
|
seotitle: Use Telegraf configuration managed with Telegraf Controller
|
|
description: >
|
|
Use Telegraf configuration files managed with Telegraf Controller to configure
|
|
your running Telegraf agents.
|
|
menu:
|
|
telegraf_controller:
|
|
name: Use configurations
|
|
parent: Manage configurations
|
|
weight: 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](#apply-a-configuration-to-an-agent)
|
|
- [Set dynamic values](#set-dynamic-values)
|
|
- [Set parameter values](#set-parameter-values)
|
|
- [Set environment variables](#set-environment-variables)
|
|
- [Auto-update agents](#auto-update-agents)
|
|
- [Use {{% product-name %}} to build commands](#use-telegraf-controller-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:
|
|
|
|
```bash
|
|
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](/telegraf/controller/configs/dynamic-values/)
|
|
using parameters, environment variables, and secrets.
|
|
|
|
- [Set parameter values](#set-parameter-values)
|
|
- [Set environment variables](#set-environment-variables)
|
|
|
|
### Set parameter values
|
|
|
|
[Configuration parameters](/telegraf/controller/configs/dynamic-values/#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 %}}
|
|
```toml
|
|
[[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" %}}
|
|
```bash
|
|
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](/telegraf/controller/configs/dynamic-values/#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 %}}
|
|
```toml
|
|
[[inputs.http]]
|
|
urls = ["http://localhost:8080/metrics"]
|
|
|
|
[inputs.http.headers]
|
|
Authorization = "Bearer ${AUTH_TOKEN}"
|
|
```
|
|
{{% /telegraf/dynamic-values %}}
|
|
|
|
##### Set the environment variable before starting Telegraf
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](/telegraf/v1/configuration/#selectors-1). 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
|
|
|
|
<!-- TODO: Provide information about downloading configs when the functionality is added -->
|