Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'master' into feat-api-uplift

claude/fix-docs-build-issue-VL3Et
Jason Stirnaman 2026-01-01 20:00:09 -06:00 committed by GitHub
parent 59daf1733d dc62d0d011
commit dddc246830
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
45 changed files with 2092 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.ci/link-checker/production.lycherc.toml
View File

@ -68,6 +68,10 @@ exclude = [
# InfluxData support URLs (certificate/SSL issues in CI)
"^https?://support\\.influxdata\\.com",
"^https?://influxdata\\.com/slack",
# NSSM download URLs (403 errors for automated requests)
"^https?://nssm\\.cc/download",
# AI platforms (often block automated requests)
"^https?://claude\\.ai",
@ -143,4 +147,4 @@ no_progress = true # Disable progress bar in CI
# Summary settings
show_success_count = true
show_skipped_count = true
show_skipped_count = true

4
.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt
View File

@ -19,12 +19,15 @@ FlightQuery
GBs?
Grafana|\{\{.*grafana.*\}\}
HostURL
[Hh]ardcod(e|ed|es|ing)
InfluxDB Cloud
InfluxDB OSS
InfluxDB-specific
Influxer
JavaScript
KBs?
[Kk]eybind(s|ing)?
[Kk]eymap(s)?
LogicalPlan
[Mm]axim(ize|um)
[Mm]inim(ize|um)
@ -33,6 +36,7 @@ MBs?
PBs?
Parquet
\w*-?\w*parquet\w*-\w*
[Pp]repopulat(e|es|ed|ing)
Redoc
SQLAlchemy
SQLAlchemy

14
assets/js/components/doc-search.js
View File

@ -45,8 +45,8 @@ export default function DocSearch({ component }) {
}
const multiVersion = ['influxdb'];
// Use object-based lookups instead of conditionals for version and product names
// These can be replaced with data from productData in the future
// Use object-based lookups instead of conditionals for version and product
// names. These can be replaced with data from productData in the future.
// Version display name mappings
const versionDisplayNames = {
@ -57,6 +57,7 @@ export default function DocSearch({ component }) {
'cloud-dedicated': 'Cloud Dedicated',
clustered: 'Clustered',
explorer: 'Explorer',
controller: 'Controller',
};
// Product display name mappings
@ -67,6 +68,7 @@ export default function DocSearch({ component }) {
enterprise_influxdb: 'InfluxDB Enterprise',
flux: 'Flux',
telegraf: 'Telegraf',
controller: 'Telegraf Controller',
chronograf: 'Chronograf',
kapacitor: 'Kapacitor',
platform: 'InfluxData Platform',
@ -105,10 +107,10 @@ export default function DocSearch({ component }) {
hit.version = version;
hit.hierarchy.lvl0 =
hit.hierarchy.lvl0 +
` <span class=\"search-product-version\">${product} ${version}</span>`;
` <span class="search-product-version">${product} ${version}</span>`;
hit._highlightResult.hierarchy.lvl0.value =
hit._highlightResult.hierarchy.lvl0.value +
` <span class=\"search-product-version\">${product} ${version}</span>`;
` <span class="search-product-version">${product} ${version}</span>`;
});
return hits;
},
@ -119,9 +121,9 @@ export default function DocSearch({ component }) {
autocompleteOptions: {
templates: {
header:
'<div class="search-all-content"><a href="https:\/\/support.influxdata.com" target="_blank">Search all InfluxData content <span class="icon-arrow-up-right"></span></a>',
'<div class="search-all-content"><a href="https://support.influxdata.com" target="_blank">Search all InfluxData content <span class="icon-arrow-up-right"></span></a>',
empty:
'<div class="search-no-results"><p>Not finding what you\'re looking for?</p> <a href="https:\/\/support.influxdata.com" target="_blank">Search all InfluxData content <span class="icon-arrow-up-right"></span></a></div>',
'<div class="search-no-results"><p>Not finding what you\'re looking for?</p> <a href="https://support.influxdata.com" target="_blank">Search all InfluxData content <span class="icon-arrow-up-right"></span></a></div>',
},
},
});

2
assets/js/utils/product-mappings.ts
View File

@ -110,6 +110,7 @@ const URL_PATTERN_MAP: Record<string, string> = {
'/influxdb/v1': 'influxdb',
'/enterprise_influxdb/': 'enterprise_influxdb',
'/telegraf/': 'telegraf',
'/telegraf/controller/': 'telegraf_controller',
'/chronograf/': 'chronograf',
'/kapacitor/': 'kapacitor',
'/flux/': 'flux',
@ -151,6 +152,7 @@ const PRODUCT_FALLBACK_MAP: Record<string, ProductInfo> = {
influxdb: { name: 'InfluxDB', version: 'v1' }, // Will be refined below
enterprise_influxdb: { name: 'InfluxDB Enterprise v1', version: 'v1' },
telegraf: { name: 'Telegraf', version: 'v1' },
telegraf_controller: { name: 'Telegraf Controller', version: 'controller' },
chronograf: { name: 'Chronograf', version: 'v1' },
kapacitor: { name: 'Kapacitor', version: 'v1' },
flux: { name: 'Flux', version: 'v0' },

31
assets/styles/layouts/article/_code.scss
View File

@ -160,6 +160,37 @@ span.code-callout, .code-placeholder {
}
.code-placeholder-key code {color: $code-placeholder !important}
////// SPECIAL CODE HIGHLIGHTING FOR TELEGRAF CONTROLLER DYNAMIC VALUES ////////
pre span.tc-dynamic-value {
border: 1px solid;
border-radius: 6px;
padding: 0 .25rem;
--param-color: #ff79c6;
--param-bg: #ff79c633;
--env-color: #0092b8;
--env-bg: #0092b833;
--secret-color: #9a09ff;
--secret-bg: #9809ff33;
&.param {
color: var(--param-color);
background: var(--param-bg);
border-color: var(--param-color);
}
&.env {
color: var(--env-color);
background: var(--env-bg);
border-color: var(--env-color);
}
&.secret {
color: var(--secret-color);
background: var(--secret-bg);
border-color: var(--secret-color);
}
}
////////////////////////////////////////////////////////////////////////////////
///////////////////////////////// MEDIA QUERIES ////////////////////////////////

9
assets/styles/layouts/article/blocks/_special-state.scss
View File

@ -15,6 +15,15 @@
p {margin-bottom: 1rem;}
.btn {
border-radius: $radius * 2;
@include gradient($grad-burningDusk);
&:after {
background: linear-gradient(45deg, #a8085a, #7b14d6);
}
}
.expand-wrapper {
border: none;
margin: .5rem 0 1.5rem;

6
content/influxdb/v2/install/upgrade/v1-to-v2/_index.md
View File

@ -1,12 +1,12 @@
---
title: Upgrade from InfluxDB 1.x to 2.7
title: Upgrade from InfluxDB 1.x to {{< current-version >}}
description: >
Explore different methods for upgrading from InfluxDB 1.x to InfluxDB 2.7 and
Explore different methods for upgrading from InfluxDB 1.x to InfluxDB {{< current-version >}} and
choose the best one for your use case.
menu:
influxdb_v2:
parent: Upgrade InfluxDB
name: InfluxDB 1.x to 2.7
name: InfluxDB 1.x to 2.8
weight: 11
aliases:
- /influxdb/v2/upgrade/v1-to-v2/

8
content/influxdb/v2/install/upgrade/v1-to-v2/automatic-upgrade.md
View File

@ -1,11 +1,11 @@
---
title: Automatically upgrade from InfluxDB 1.x to 2.7
list_title: Automatically upgrade from 1.x to 2.7
title: Automatically upgrade from InfluxDB 1.x to {{< current-version >}}
list_title: Automatically upgrade from 1.x to {{< current-version >}}
description: >
Use the `influx upgrade` tool to automatically upgrade from InfluxDB 1.x to InfluxDB 2.7.
Use the `influx upgrade` tool to automatically upgrade from InfluxDB 1.x to InfluxDB {{< current-version >}}.
menu:
influxdb_v2:
parent: InfluxDB 1.x to 2.7
parent: InfluxDB 1.x to 2.8
name: Automatically upgrade
weight: 10
aliases:

6
content/influxdb/v2/install/upgrade/v1-to-v2/docker.md
View File

@ -1,12 +1,12 @@
---
title: Upgrade from InfluxDB 1.x to 2.7 with Docker
list_title: Upgrade from 1.x to 2.7 with Docker
title: Upgrade from InfluxDB 1.x to {{< current-version >}} with Docker
list_title: Upgrade from 1.x to {{< current-version >}} with Docker
description: >
Use the automated upgrade process built into the InfluxDB 2.x Docker image to
update InfluxDB 1.x Docker deployments to InfluxDB 2.x.
menu:
influxdb_v2:
parent: InfluxDB 1.x to 2.7
parent: InfluxDB 1.x to 2.8
name: Upgrade with Docker
weight: 101
aliases:

8
content/influxdb/v2/install/upgrade/v1-to-v2/manual-upgrade.md
View File

@ -1,13 +1,13 @@
---
title: Manually upgrade from InfluxDB 1.x to 2.7
list_title: Manually upgrade from 1.x to 2.7
title: Manually upgrade from InfluxDB 1.x to {{< current-version >}}
list_title: Manually upgrade from 1.x to {{< current-version >}}
description: >
To manually upgrade from InfluxDB 1.x to InfluxDB 2.7, migrate data, create
To manually upgrade from InfluxDB 1.x to InfluxDB {{< current-version >}}, migrate data, create
v1-compatible authorizations, and create database and retention policy
(DBRP) mappings.
menu:
influxdb_v2:
parent: InfluxDB 1.x to 2.7
parent: InfluxDB 1.x to 2.8
name: Manually upgrade
weight: 11
aliases:

4
content/influxdb/v2/install/upgrade/v1-to-v2/migrate-cqs.md
View File

@ -6,7 +6,7 @@ description: >
InfluxDB 2.x tasks.
menu:
influxdb_v2:
parent: InfluxDB 1.x to 2.7
parent: InfluxDB 1.x to 2.8
name: Migrate CQs
weight: 102
aliases:
@ -123,7 +123,7 @@ See [other resources available to help](#other-helpful-resources).
#### INTO clause
The `INTO` clause defines the measurement to write results to.
`INTO` also supports fully-qualified measurements that include the database and retention policy.
`INTO` also supports fully qualified measurements that include the database and retention policy.
In InfluxDB OSS {{< current-version >}}, database and retention policy combinations are mapped to specific buckets
(for more information, see [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/)).

4
content/influxdb/v2/install/upgrade/v2-beta-to-v2.md
View File

@ -1,13 +1,13 @@
---
title: Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0
description: >
To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.x, first
To upgrade from InfluxDB 2.0 beta 16 or earlier to {{< current-version >}}, first
follow these steps to upgrade your InfluxDB beta instance, data, and resources
to InfluxDB 2.0.
menu:
influxdb_v2:
parent: Upgrade InfluxDB
name: InfluxDB 2.0 beta to 2.0
name: InfluxDB 2.0 beta to 2.8
aliases:
- /influxdb/v2.0/reference/rc0-upgrade-guide/
- /influxdb/v2.0/reference/rc1-upgrade-guide/

6
content/influxdb/v2/install/upgrade/v2-to-v2.md
View File

@ -1,12 +1,12 @@
---
title: Upgrade from InfluxDB 2.x to InfluxDB 2.7
title: Upgrade from InfluxDB 2.x to {{< current-version >}}
description: >
To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.7 (stable),
To upgrade from InfluxDB 2.0 beta 16 or earlier to {{< current-version >}},
manually upgrade all resources and data to the latest version by completing these steps.
menu:
influxdb_v2:
parent: Upgrade InfluxDB
name: InfluxDB 2.x to 2.7
name: InfluxDB 2.x to 2.8
weight: 9
aliases:
- /influxdb/v2/upgrade/v2-to-v2/

41
content/telegraf/controller/_index.md Normal file
View File

@ -0,0 +1,41 @@
---
title: Telegraf Controller documentation
description: >
Documentation for Telegraf Controller, the application for managing Telegraf
deployments at scale. Create and manage Telegraf configurations, monitor
the health of your agents, and more.
menu:
telegraf_controller:
name: Telegraf Controller
weight: 1
---
**Telegraf Controller** is a centralized application for managing Telegraf
deployments at scale. Use it to define configurations once and apply them
consistently across fleets of agents. Monitor agent health and roll out updates
without manually editing individual agents.
## Key features
- Create and manage agent configurations
- Connect agents to Telegraf Controller
- Monitor the overall health of your agent deployment
- Roll out changes safely and verify agent status
- Apply custom logic to agents to identify when they are considered "not reporting"
{{< img-hd src="/img/telegraf/controller-agents-list.png" alt="Telegraf Controller agent summary" />}}
## Configuration and agent workflow
- Create and store Telegraf configurations in Telegraf Controller
- Start a Telegraf agent, pulling its configuration from Telegraf Controller,
and have it regularly check for configuration updates.
- Agents use the [Telegraf Heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/)
(available with Telegraf v1.37+) to report their status back to
Telegraf Controller
- Telegraf Controller provides agent-specific and deployment-wide health
information.
- When you update a configuration, agents see the change and load the updated
configuration.
{{< children hlevel="h2" >}}

28
content/telegraf/controller/agents/_index.md Normal file
View File

@ -0,0 +1,28 @@
---
title: Manage Telegraf agents
seotitle: Manage Telegraf agents with Telegraf Controller
description: >
Use {{% product-name %}} to monitor the Telegraf agents that report through
the heartbeat output plugin, view their details, and manage reporting rules.
menu:
telegraf_controller:
name: Manage agents
weight: 4
---
{{% product-name %}} tracks agents that send heartbeats through the Telegraf
heartbeat output plugin.
Each heartbeat includes a unique `instance_id` (also called "agent ID") so
Controller can distinguish one agent from another.
- {{% product-name %}} automatically creates agents the first time a heartbeat
arrives from a unique agent.
- Click the **More button ({{% icon "tc-more" %}})** in the agent list and select
**View Details** to see information and reporting history for an agent.
- Reporting rules define how long an agent can go without sending a heartbeat
before {{% product-name "short" %}} marks it as **Not Reporting**. They can
also automatically delete agents that haven't reported in a specified amount
of time.
- You can assign a reporting rule from the agent list or an agent details page.
{{< children hlevel="h2" >}}

77
content/telegraf/controller/agents/create.md Normal file
View File

@ -0,0 +1,77 @@
---
title: Create agents in Telegraf Controller
list_title: Create agents
description: >
Learn how Telegraf Controller creates agents from heartbeat plugin reports
and how to verify new agents in the UI.
menu:
telegraf_controller:
name: Create agents
parent: Manage agents
weight: 101
---
Agents represent Telegraf instances that send heartbeat data to {{% product-name %}}
through the heartbeat output plugin.
{{% product-name "short" %}} uses the heartbeat payload to create and track each agent.
<!-- TOC -->
- [How agent creation works](#how-agent-creation-works)
- [Configure agents](#configure-agents)
- [Verify a new agent](#verify-a-new-agent)
<!-- /TOC -->
## How agent creation works
- The [heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/) in
a Telegraf configuration reports agent data back to the `/agents/heartbeat`
endpoint of your {{% product-name %}} instance.
- The heartbeat payload includes a unique `instance_id` (also referred to as
an "agent ID") for the agent.
- When the first heartbeat arrives for an agent, {{% product-name %}}
automatically creates the agent record and marks it with the reported status.
Subsequent agent heartbeats update the existing agent record.
## Configure agents
[Heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/) configuration
options determine what agent data Telegraf sends to {{% product-name %}}.
The following heartbeat plugin configuration options are available:
- **url**: _({{% req %}})_ URL of heartbeat endpoint.
- **instance_id**: _({{% req %}})_ Unique identifier for the Telegraf instance
or agent (also known as the agent ID).
- **token**: Authorization token for the heartbeat endpoint
- **interval**: Interval for sending heartbeat messages. Default is `1m` (every minute).
- **include**: Information to include in the heartbeat message.
Available options are:
- **hostname**: Hostname of the machine running Telegraf.
- **statistics**: ({{% req text="Recommended" color="magenta" %}})
Agent metrics including number of metrics collected and written since the
last heartbeat, logged error and warning counts, etc.
- **configs**: ({{% req text="Recommended" color="magenta" %}})
Redacted list of configurations loaded by the Telegraf instance.
- **headers**: HTTP headers to include with the heartbeat request.
### Example heartbeat output plugin
The following is an example heartbeat output plugin configuration that uses
an `agent_id` [configuration parameter](#) to specify the `instance_id`.
```toml
[[outputs.heartbeat]]
url = "http://telegraf_controller.example.com/agents/heartbeat"
instance_id = "&{agent_id}"
interval = "1m"
include = ["hostname", "statistics", "configs"]
[outputs.heartbeat.headers]
User-Agent = "telegraf"
```
## Verify a new agent
1. Open {{% product-name %}} and go to **Agents**.
2. Confirm the agent appears in the list with the expected `instance_id`.
3. Click the **More button ({{% icon "tc-more" %}})** and select
**View Details** to verify metadata, labels, and the reporting rule assignment.

49
content/telegraf/controller/agents/delete.md Normal file
View File

@ -0,0 +1,49 @@
---
title: Delete agents from Telegraf Controller
list_title: Delete agents
description: >
Remove individual or multiple Telegraf agents from {{% product-name %}}.
menu:
telegraf_controller:
name: Delete agents
parent: Manage agents
weight: 105
---
Remove individual or multiple Telegraf agents from {{% product-name %}}.
<!-- TOC -->
- [Delete a single agent](#delete-a-single-agent)
- [Delete multiple agents](#delete-multiple-agents)
- [Automatically delete agents](#automatically-delete-agents)
<!-- /TOC -->
> [!Note]
> Deleting an agent from {{% product-name %}} does not affect the running
> Telegraf instance; it only deletes the record of the agent from Telegraf
> Controller.
## Delete a single agent
1. In **Agents**, find the agent you want to remove.
2. Click the **More button ({{% icon "tc-more" %}})** and select
**{{% icon "trash" %}} Delete Agent**.
3. Confirm the deletion.
## Delete multiple agents
1. In **Agents**, select the checkboxes for the agents you want to remove.
2. Select **{{% icon "trash" %}} Delete Agents**.
3. Confirm the deletion.
## Automatically delete agents
Use [reporting rules](/telegraf/controller/agents/reporting-rules) to
automatically delete agents that have not reported in a specified amount of time.
1. [Create a reporting rule](/telegraf/controller/agents/reporting-rules/#create-a-reporting-rule)
with auto-delete enabled.
2. [Assign the newly created rule to agents](/telegraf/controller/agents/reporting-rules/#assign-a-reporting-rule-to-agents).
If agents assigned to the reporting rule do not report in the defined auto-delete
threshold, they are automatically deleted.

108
content/telegraf/controller/agents/reporting-rules.md Normal file
View File

@ -0,0 +1,108 @@
---
title: Define agent reporting rules
description: >
Define reporting rules that determine when Telegraf Controller marks
agents as not reporting and optionally automatically delete not reporting
agents.
menu:
telegraf_controller:
name: Define reporting rules
parent: Manage agents
weight: 103
---
Reporting rules define how long an agent can go without sending a heartbeat
before {{% product-name %}} changes its status to **Not Reporting**. They can
also automatically delete agents that haven't reported in a specified amount of
time.
{{% product-name %}} requires a default reporting rule. Newly created agents
are automatically assigned to the current default reporting rule.
Manage reporting rules in the **Reporting Rules** section of
{{% product-name "short" %}}, then assign them to agents from either the agent
list or an agent details page.
<!-- TOC -->
- [Create a reporting rule](#create-a-reporting-rule)
- [Update a reporting rule](#update-a-reporting-rule)
- [Delete a reporting rule](#delete-a-reporting-rule)
- [Set a default reporting rule](#set-a-default-reporting-rule)
- [From the reporting rules list](#from-the-reporting-rules-list)
- [From reporting rule details](#from-reporting-rule-details)
- [Assign a reporting rule to agents](#assign-a-reporting-rule-to-agents)
- [From the agent list](#from-the-agent-list)
- [From an agent details page](#from-an-agent-details-page)
<!-- /TOC -->
## Create a reporting rule
1. In Telegraf Controller, go to **Reporting Rules**.
2. Select **+ Add Rule**.
3. Enter the following:
- **Description**: Reporting rule description
- **Not Reporting Threshold**: The maximum time an agent can go without
reporting before {{% product-name "short" %}} assigns the "Not Reporting"
status.
- **Auto-delete agents**: Enable to automatically delete agents that haven't
reported in the defined auto-delete threshold.
- **Default Rule**: Enable to make the rule the default reporting rule.
4. Save the rule.
## Update a reporting rule
1. In **Reporting Rules**, click the **More button ({{% icon "tc-more" %}})**
of the rule you want to update.
2. Select **Edit**.
3. Edit the description, not reporting threshold, auto-delete settings, or make
the rule the default reporting rule.
4. Save your changes.
## Delete a reporting rule
1. In **Reporting Rules**, click the **More button ({{% icon "tc-more" %}})**
of the rule you want to delete.
2. Select **Delete** and confirm.
> [!Important]
>
> #### You cannot delete the default reporting rule
>
> To delete a reporting rule that is currently the default rule, first assign
> a new rule as the default reporting rule.
>
> #### Agents assigned to a deleted reporting rule
>
> When you delete a reporting rule, any agents assigned to the deleted rule
> automatically inherit the default reporting rule.
## Set a default reporting rule
### From the reporting rules list
1. In **Reporting Rules**, click the **More button ({{% icon "tc-more" %}})**
of the rule you want to make the default.
2. Select **Make Default**.
### From reporting rule details
1. In **Reporting Rules**, click the **More button ({{% icon "tc-more" %}})**
of the rule you want to make the default.
2. Select **Edit**.
3. Toggle **Default Rule** to true.
4. Save your changes.
## Assign a reporting rule to agents
### From the agent list
1. In **Agents**, select one or more agents.
2. Select **Assign Rule**.
3. Choose a rule and assign it.
### From an agent details page
1. In **Agents**, click the **More button ({{% icon "tc-more" %}})** for an
agent and select **View Details**.
2. In the **Reporting Rule** section, select **Change**.
3. Choose a rule and apply it.

30
content/telegraf/controller/agents/status.md Normal file
View File

@ -0,0 +1,30 @@
---
title: Set agent statuses
description: >
Understand how {{% product-name %}} receives and displays agent statuses from
the heartbeat output plugin.
menu:
telegraf_controller:
name: Set agent statuses
parent: Manage agents
weight: 104
---
Agent statuses come from the Telegraf heartbeat output plugin and are sent with
each heartbeat request.
The plugin reports an `ok` status.
> [!Note]
> A future Telegraf release will let you configure logic that sets the status value.
{{% product-name %}} also applies reporting rules to detect stale agents.
If an agent does not send a heartbeat within the rule's threshold, Controller
marks the agent as **Not Reporting** until it resumes sending heartbeats.
## View an agent's status
1. In {{% product-name %}}, go to **Agents**.
2. Check the **Status** column for each agent.
3. To see more details, click the **More button ({{% icon "tc-more" %}})** and
select **View Details**.
4. The details page shows the reported status, reporting rule assignment, and
the time of the last heartbeat.

60
content/telegraf/controller/configs/_index.md Normal file
View File

@ -0,0 +1,60 @@
---
title: Manage Telegraf configurations
seotitle: Manage Telegraf configurations with Telegraf Controller
description: >
Use Telegraf Controller to create, update, and delete Telegraf configurations.
menu:
telegraf_controller:
name: Manage configurations
weight: 3
---
Telegraf Controller provides a visual interface for managing Telegraf
configurations. Configurations define what metrics Telegraf collects, how it
processes those metrics, and where it sends the metrics.
## View configurations
Navigate to the **Configurations** section from the main navigation menu.
This displays a list of all existing configurations.
### List view
The **Configurations** page displays all configurations with:
- Search bar for filtering by name or description
- Label filters for organization
- Sort options
### Configuration details
On the **Configurations** page, click a configuration name to view and
update the configuration.
{{< children hlevel="h2" >}}
## Best practices
### Organization
- Use descriptive names that indicate purpose
- Add detailed descriptions for complex configurations
- Apply consistent labeling schemes
- Group related configurations with labels
### Performance
- Set appropriate collection intervals based on metric importance
- Configure buffer sizes to handle peak loads
- Use filters to reduce unnecessary metric collection
- Test configurations before deployment
### Security
- Use secret stores for sensitive credentials
- Avoid hardcoding passwords in configurations
- Implement least-privilege access principles
- Regularly audit configuration access
### Maintenance
- Review and update configurations periodically
- Remove unused configurations
- Document configuration purposes and dependencies
- Test changes in development before production

84
content/telegraf/controller/configs/create.md Normal file
View File

@ -0,0 +1,84 @@
---
title: Create a Telegraf configuration
seotitle: Create Telegraf configurations with Telegraf Controller
description: >
Use Telegraf Controller to create Telegraf TOML configuration files.
Upload existing configurations, write raw TOML in the Code Editor, or use
the Telegraf Builder visual interface to manage and configure plugins.
menu:
telegraf_controller:
name: Create a configuration
parent: Manage configurations
weight: 101
related:
- /telegraf/controller/configs/dynamic-values/
---
Create a configuration to define how Telegraf collects, processes, and writes
metrics. Telegraf Controller stores the configuration as TOML that you can use
across agents. Upload existing configurations, write raw TOML in the Code
Editor, or use the Telegraf Builder visual interface to manage and configure
plugins.
## Create a configuration
1. In the {{% product-name %}} web interface, select **Configurations** in the
navigation bar.
2. Click **{{% icon "plus" %}} Add Config**.
3. Enter a configuration name and optional description.
4. Use the {{% product-name %}} [Code Editor](#use-the-code-editor) or
[Telegraf Builder](#use-the-telegraf-builder) to provide or build the
Telegraf configuration TOML.
5. Click **Create Configuration**.
### Use the Code Editor
The {{% product-name %}} **Code Editor** is an in-browser TOML editor that lets
you upload or manually write Telegraf configuration TOML.
_For detailed information about using the Code Editor, see
[Use the Code Editor](/telegraf/controller/configs/ui/code-editor)._
{{< img-hd src="/img/telegraf/controller-code-editor.png" alt="Telegraf Controller Code Editor" />}}
### Use the Telegraf Builder
The **Telegraf Builder** is a visual interface for adding and configuring
Telegraf plugins in a Telegraf configuration.
_For detailed information about using the Telegraf Builder, see
[Use the Telegraf Builder](/telegraf/controller/configs/ui/telegraf-builder)._
{{< img-hd src="/img/telegraf/controller-telegraf-builder.png" alt="Telegraf Builder in Telegraf Controller" />}}
> [!Warning]
> #### The Telegraf Builder does not support all Telegraf plugins
>
> We are in the process of adding support for more Telegraf plugins in the
> Telegraf Builder. You can use plugins that are not currently supported by the
> builder, but you must add and edit them with the Code Editor.
## Heartbeat output plugin {note="Telegraf 1.37+"}
When adding a configuration, {{% product-name %}} prepopulates the
configuration with a [Telegraf heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/).
This plugin reports agent information back to the {{% product-name %}} heartbeat
API and lets you monitor the health of your deployed Telegraf agents.
```toml
[[outputs.heartbeat]]
url = "http://localhost:8000/agents/heartbeat"
instance_id = "&{agent_id}"
interval = "1m"
include = ["hostname", "statistics", "configs"]
```
To monitor agents with {{% product-name %}}, include a heartbeat plugin in
your Telegraf configurations.
## Next steps
- Use [dynamic values](/telegraf/controller/configs/dynamic-values/)
to keep configurations portable across environments.
- [Apply the configuration](/telegraf/controller/configs/use/) to your
Telegraf agents.

57
content/telegraf/controller/configs/delete.md Normal file
View File

@ -0,0 +1,57 @@
---
title: Delete configurations
seotitle: Delete Telegraf configurations from Telegraf Controller
description: >
Delete one or more Telegraf configurations from {{% product-name %}}.
menu:
telegraf_controller:
name: Delete configurations
parent: Manage configurations
weight: 105
---
Delete configurations you no longer use to keep {{% product-name %}} organized.
> [!Warning]
> Deleting a configuration permanently removes it from {{% product-name %}}.
> Export the TOML if you need a backup.
## Before you delete
You cannot delete a configuration that is currently used by actively
reporting agents.
To delete a configuration:
- Confirm no agents rely on the configuration.
- Delete agents or reassign agents to another configuration if needed.
## Delete a single configuration
Delete configuration from either the configurations list page or the
configuration detail page.
### From the configurations list page
1. In the {{% product-name %}} web interface, select **Configurations** in the
navigation bar.
2. Click the **More button ({{% icon "tc-more" %}})** next to the configuration
you want to delete and select **{{% icon "trash" %}} Delete**.
3. Confirm the deletion.
### From the configuration detail page
1. In the {{% product-name %}} web interface, select **Configurations** in the
navigation bar.
2. Click the name of the configuration you want to delete to view the
configuration detail page.
3. Select the **Manage** tab.
4. Under **Delete Configuration**, click **Delete**.
5. Confirm the deletion.
## Delete multiple configurations
1. In the {{% product-name %}} web interface, select **Configurations** in the
navigation bar.
2. Use the select boxes to select all of the configurations you want to delete.
3. In the bulk options menu that appears, click **{{% icon "trash" %}} Delete**.
4. Confirm the deletion.

176
content/telegraf/controller/configs/dynamic-values.md Normal file
View File

@ -0,0 +1,176 @@
---
title: Use dynamic values in configurations
seotitle: Use dynamic values in Telegraf configurations with Telegraf Controller
description: >
Use parameters, environment variables, and secrets to dynamically set values
in your Telegraf configurations.
menu:
telegraf_controller:
name: Use dynamic values
parent: Manage configurations
weight: 103
---
Use dynamic values in your Telegraf configurations and reuse a single
configuration for multiple distinct agents or across environments.
Telegraf Controller supports the following dynamic value types:
- **Parameters** for values you want to set or override per agent.
- **Environment variables** for values provided by the running Telegraf agent.
- **Secrets** for sensitive values stored in an external secret store.
## Parameters
Use parameters for values that change between agents, deployments, or environments.
Define the parameter where the configuration is easy to find, and then
reference it in plugin settings. _Configuration parameters are a feature of
{{% product-name %}} and are not part of the Telegraf project._
> [!Important]
> #### Do not use parameters for sensitive information
>
> Do not use parameters to provide sensitive information in agent configurations.
> Parameter values are passed over the network.
> Use environment variables or secrets to provide sensitive information to agents.
Use the following syntax:
```
&{param_name[:default_value]}
```
Parameters do not require a default value. Any parameter without a default
value is considered required and must [be defined](#define-parameters) when
requesting the configuration from {{% product-name %}}.
### Use parameters in Telegraf configurations
{{% telegraf/dynamic-values %}}
```toml
[[outputs.influxdb_v2]]
# Parameter with a default value
urls = ["&{db_host:https://localhost:8181}"]
[[outputs.heartbeat]]
# Required parameter without a default value
instance_id = "&{agent_id}"
```
{{% /telegraf/dynamic-values %}}
The example above uses two parameters:
- `db_host` with a default value of `https://localhost:8181`
- `agent_id` ({{< req >}})
### Define parameters
Use URL-encoded query parameters to define parameter values when requesting a
configuration's TOML. The {{% product-name %}} API returns the TOML with replaced
parameters.
_For readability, the following example uses Shell variables to build the
configuration URL with query parameters for each configuration parameter:_
<!--pytest.mark.skip-->
```sh
configUrl="http://localhost:8888/api/configs/xxxxxx/toml"
params="?db_host=https%3A%2F%2Fmydomain%3A8181"
params+="&agent_id=agent123"
configUrl+=$params
telegraf \
--config $configUrl
```
If requesting the [example configuration](#use-parameters-in-telegraf-configurations)
above, Telegraf would load the following TOML configuration:
```toml
[[outputs.influxdb_v2]]
# Parameter with a default value
urls = ["https://mydomain:8181"]
[[outputs.heartbeat]]
# Required parameter without a default value
instance_id = "agent123"
```
## Environment Variables
Use environment variables for values that Telegraf reads from the agent
environment at runtime.
Provide a default to keep the configuration portable across environments.
Use the following syntax:
```sh
${VAR_NAME[:-default_value]}
```
Environment variables do not require a default value. Any environment variable
without a default value is considered required and must be defined in the
Telegraf agent's environment when using the configuration.
For more information about Telegraf environment variable syntax, see
[Telegraf configuration options—Set environment variables](/telegraf/v1/configuration/#set-environment-variables).
### Use environment variables in Telegraf configurations
{{% telegraf/dynamic-values %}}
```toml
[[inputs.http]]
urls = ["${API_ENDPOINT:-http://localhost:8080}/metrics"]
[inputs.http.headers]
Authorization = "Bearer ${AUTH_TOKEN}"
```
{{% /telegraf/dynamic-values %}}
The example above uses two environment variables:
- `API_ENDPOINT` with a default value of `http://localhost:8080`
- `AUTH_TOKEN` ({{< req >}})
### Define environment variables at runtime
Telegraf loads environment variables from the agent runtime environment.
<!--pytest.mark.skip-->
```sh
API_ENDPOINT=https://mydomain.com/metrics
AUTH_TOKEN=x00x0xx00xxxX0xXXx0000xxxX000x00XXxXx
telegraf \
--config "http://localhost:8888/api/configs/xxxxxx/toml"
```
## Secrets
Use secrets for credentials or tokens you do not want to store in plain text.
Secrets require a secret store and its corresponding `secretstores` plugin.
{{% telegraf/dynamic-values %}}
```toml
# Configure a secret store plugin
[[secretstores.vault]]
id = "my_vault"
address = "my_vault:8200"
token_file = "/path/to/auth/token"
# ...
# Use secrets from the configured secret store
[[outputs.influxdb_v2]]
host = "my_influxdb.com:8181"
token = "@{my_vault:influx_token}"
```
{{% /telegraf/dynamic-values %}}
For more information about Telegraf secrets and secret stores, see
[Telegraf configuration options—Secret stores](/telegraf/v1/configuration/#secret-stores).
When using secrets:
- Configure the secret store plugin in the same configuration.
- Use a stable `id` so references to a secret store remain consistent.
- Ensure the Telegraf agent can reach and authenticate with the secret store.

20
content/telegraf/controller/configs/ui/_index.md Normal file
View File

@ -0,0 +1,20 @@
---
title: Telegraf configuration UI tools
description: >
Use Telegraf configuration user interface tools in {{% product-name %}} to
create, edit, and update Telegraf TOML configuration files.
Upload or write raw TOML in the **Code Editor** or use the
**Telegraf Builder** visual interface to manage and configure plugins.
menu:
telegraf_controller:
name: Configuration UI tools
parent: Manage configurations
weight: 103
---
Use Telegraf configuration user interface tools in Telegraf Controller to
create, edit, and update Telegraf TOML configuration files.
Upload or write raw TOML in the **Code Editor** or use
the **Telegraf Builder** visual interface to manage and configure plugins.
{{< children hlevel="h2" >}}

106
content/telegraf/controller/configs/ui/code-editor.md Normal file
View File

@ -0,0 +1,106 @@
---
title: Use the Code Editor
description: >
Use the {{% product-name %}} **Code Editor** to upload, write, or edit raw
Telegraf configuration TOML.
menu:
telegraf_controller:
name: Code Editor
parent: Configuration UI tools
weight: 201
related:
- /telegraf/controller/configs/dynamic-values/
---
Use the {{% product-name %}} **Code Editor** to upload, write, or edit raw
Telegraf configuration TOML.
{{< img-hd src="/img/telegraf/controller-code-editor.png" alt="Telegraf Controller Code Editor" />}}
The Code Editor is the default view when managing a configuration. If it is not
displayed, click the **Code Editor** tab.
> [!Important]
> #### Switching from the Code Editor to the Telegraf Builder
>
> Switching from the Code Editor to the Telegraf Builder will reformat the TOML.
> When reformatting, Telegraf Builder does **not** preserve the following:
>
> - Comments
> - Indentation
> - Plugin Order
## Upload TOML
To upload a Telegraf configuration file to {{% product-name %}}, click
**Upload files** to open a file selection dialogue box or drag and drop your
configuration file into the Code Editor.
{{% product-name %}} supports TOML-formatted files with the following extensions:
- `.toml`
- `.conf`
- `.txt`
> [!Important]
> Uploaded configuration files fully replace any existing configuration TOML.
## Manually write or edit TOML
The Code Editor is a feature-rich, browser-based editor that lets you write
code using keyboard shortcuts similar to those in popular editors and IDEs.
### Keymaps
The Code Editor uses CodeMirror's default keymaps.
The following bindings come from the reference keymaps.
- {{< keybind mac="←" other="ArrowLeft" >}}: Move left one character (Shift selects)
- {{< keybind mac="→" other="ArrowRight" >}}: Move right one character (Shift selects)
- {{< keybind mac="↑" other="ArrowUp" >}}: Move up one line (Shift selects)
- {{< keybind mac="↓" other="ArrowDown" >}}: Move down one line (Shift selects)
- {{< keybind mac="⌥←" other="Ctrl+ArrowLeft" >}}: Move left by word group (Shift selects)
- {{< keybind mac="⌥→" other="Ctrl+ArrowRight" >}}: Move right by word group (Shift selects)
- {{< keybind mac="⌃←" other="Alt+ArrowLeft" >}}: Move left by syntax unit (Shift selects)
- {{< keybind mac="⌃→" other="Alt+ArrowRight" >}}: Move right by syntax unit (Shift selects)
- {{< keybind all="⌘←" >}} (macOS only): Move to line start (Shift selects)
- {{< keybind all="⌘→" >}} (macOS only): Move to line end (Shift selects)
- {{< keybind mac="⌥↑" other="Alt+ArrowUp" >}}: Move line up
- {{< keybind mac="⌥↓" other="Alt+ArrowDown" >}}: Move line down
- {{< keybind mac="⇧⌥↑" other="Shift+Alt+ArrowUp" >}}: Copy line up
- {{< keybind mac="⇧⌥↓" other="Shift+Alt+ArrowDown" >}}: Copy line down
- {{< keybind mac="⌘⌥↑" other="Ctrl+Alt+ArrowUp" >}}: Add cursor above
- {{< keybind mac="⌘⌥↓" other="Ctrl+Alt+ArrowDown" >}}: Add cursor below
- {{< keybind all="⌘↑" >}} (macOS only) or {{< keybind mac="⌘Home" other="Ctrl+Home" >}}: Move to document start (Shift selects)
- {{< keybind all="⌘↓" >}} (macOS only) or {{< keybind mac="⌘Home" other="Ctrl+End" >}}: Move to document end (Shift selects)
- {{< keybind all="⌃↑" >}} (macOS only) or {{< keybind mac="PageUp" other="PageUp" >}}: Page up (Shift selects)
- {{< keybind all="⌃↓" >}} (macOS only) or {{< keybind mac="PageDown" other="PageDown" >}}: Page down (Shift selects)
- {{< keybind mac="Home" other="Home" >}}: Move to line boundary backward (Shift selects)
- {{< keybind mac="End" other="End" >}}: Move to line boundary forward (Shift selects)
- {{< keybind mac="↩" other="Enter" >}} and {{< keybind mac="⇧↩" other="Shift+Enter" >}}: Insert newline and indent
- {{< keybind mac="⌘↩" other="Ctrl+Enter" >}}: Insert blank line
- {{< keybind mac="⌘A" other="Ctrl+A" >}}: Select all
- {{< keybind mac="⌃L" other="Alt+L" >}}: Select line
- {{< keybind mac="⌘I" other="Ctrl+I" >}}: Select parent syntax
- {{< keybind mac="Esc" other="Esc" >}}: Simplify selection
- {{< keybind mac="⌘[" other="Ctrl+[" >}}: Indent less
- {{< keybind mac="⌘]" other="Ctrl+]" >}}: Indent more
- {{< keybind mac="⇧⌘K" other="Shift+Ctrl+K" >}}: Delete line
- {{< keybind mac="⇧⌘&bsol;" other="Shift+Ctrl+&bsol;" >}}: Jump to matching bracket
- {{< keybind mac="⌘/" other="Ctrl+/" >}}: Toggle line comment
- {{< keybind mac="⇧⌥A" other="Shift+Alt+A" >}}: Toggle block comment
- {{< keybind mac="⌫" other="Backspace" >}}: Delete character backward
- {{< keybind mac="fn⌫" other="Delete" >}}: Delete character forward
- {{< keybind mac="⌥⌫" other="Ctrl+Backspace" >}}: Delete word group backward
- {{< keybind mac="⌥ fn⌫" other="Ctrl+Delete" >}}: Delete word group forward
- {{< keybind all="⌘⌫" >}} (macOS only): Delete to line start
- {{< keybind all="⌘ fn⌫" >}} (macOS only): Delete to line end
### Dynamic value syntax highlighting
The {{% product-name %}} Code Editor automatically applies special syntax
highlighting to dynamic values (parameters, environment variables, and secrets)
in your configuration TOML to make them more visible.
For more information about using dynamic values, see
[Use dynamic values](/telegraf/controller/configs/dynamic-values/).

122
content/telegraf/controller/configs/ui/telegraf-builder.md Normal file
View File

@ -0,0 +1,122 @@
---
title: Use the Telegraf Builder
description: >
Use the **Telegraf Builder** visual interface in {{% product-name %}} to
manage and configure Telegraf plugins.
menu:
telegraf_controller:
name: Telegraf Builder
parent: Configuration UI tools
weight: 202
---
The **Telegraf Builder** is a visual interface for managing and configuring
Telegraf plugins in a configuration. The builder is available when creating or
updating a configuration.
{{< img-hd src="/img/telegraf/controller-telegraf-builder.png" alt="Telegraf Builder in Telegraf Controller" />}}
The Telegraf builder is divided into two main panes:
- [Plugin Library pane](#plugin-library-pane): Search for and add supported plugins
- [Configuration pane](#configuration-pane): Manage agent and plugin settings
## Plugin Library pane
The **Plugin Library** pane provides a list of all Telegraf plugins supported
in the builder grouped by plugin type.
> [!Important]
> #### The Telegraf Builder does not support all Telegraf plugins
>
> We are in the process of adding support for more Telegraf plugins in the
> Telegraf Builder. You can use plugins that are not currently supported by the
> builder, but you must add and edit them with the Code Editor.
- **Search plugins**: Use the search bar in the Plugin Library pane to search
for Telegraf plugins. Search by plugin name, identifier, or description.
- **Add plugins to your configuration**: Click **{{% icon "plus" %}}** next to the
plugin to add it to your configuration.
## Configuration pane
The **Configuration** pane lets you manage agent and plugin-specific settings.
Configuration options and plugins are each represented by "cards".
Click on a card or expand or hide its contents.
Each configuration has at least two cards: [Agent Settings](#agent-settings)
and [Global Tags](#global-tags).
### Agent settings
Agent settings are those that specify how the agent runs rather than
plugin-specific settings. Agent settings only need to be included in a
configuration when they vary from the
[default Telegraf agent settings](/telegraf/v1/configuration/#agent-configuration).
**To include agent settings in your configuration:**
1. On the **Agent Settings** card, enable the
**{{% icon "toggle" %}} Include in config** toggle.
2. Define custom settings for any of the available Telegraf agent settings.
### Global tags
Telegraf applies global tags to all metrics that it emits. Global tags are not
required and only need to be included in a configuration when set.
**To include global tags in your configuration:**
1. On the **Global Tags** card, enable the
**{{% icon "toggle" %}} Include in config** toggle.
2. Click **{{% icon "plus" %}} Add Global Tag**.
3. Provide a key and a value for the global tag.
4. Repeat steps 2-3 for additional global tags.
### Plugin cards
The Telegraf Builder represents each Telegraf plugin as a card. Plugin cards
have three tabs:
- [Plugin](#plugin): Plugin-specific settings
- [Customize](#customize): Plugin customization options
- [Filter](#filter): Plugin metric filters
#### Plugin
The **Plugin** tab in a plugin card lets you customize settings specific
to that plugin.
> [!Note]
> You can use [dynamic values](/telegraf/controller/configs/dynamic-values/)
> when defining plugin settings in the Telegraf Builder.
#### Customize
The **Customize** tab in a plugin card lets you apply plugin customizations
including the following:
- **Add a plugin alias**: Aliases help to identify plugins in your
configuration. They are especially helpful when you have more than one of the
same plugin. When you define a plugin alias, the builder uses the alias as the
plugin name on the plugin card.
- **Add configuration labels**: Telegraf configuration labels let you label and
select what plugins to run when starting Telegraf. For more information about
using labels and selectors, see
[Plugin selection via labels and selectors](/telegraf/v1/configuration/#plugin-selection-via-labels-and-selectors)
- **Other customizations specific to the plugin type**
#### Filter
The **Filter** tab on a plugin card lets you add metric filters to the plugin.
These filters include `namepass`, `namedrop`, `tagpass`, `tagdrop`, and others.
For more information about using Telegraf plugin filters, see
[Metric filtering](/telegraf/v1/configuration/#metric-filtering).
#### Remove a plugin from the configuration
To remove a plugin from the configuration, click the **{{% icon "trash" %}}**
icon on the plugin card.

51
content/telegraf/controller/configs/update.md Normal file
View File

@ -0,0 +1,51 @@
---
title: Update a Telegraf configuration
seotitle: Update a Telegraf configuration with Telegraf Controller
description: >
Use Telegraf Controller to update Telegraf TOML configuration files.
menu:
telegraf_controller:
name: Update a configuration
parent: Manage configurations
weight: 102
---
Update a configuration to change plugin settings, parameters, and agent-level
options.
## Update a configuration
1. In the {{% product-name %}} web interface, select **Configurations** in the
navigation bar.
2. Click the name of the configuration you want to edit or click the
**More button ({{% icon "tc-more" %}})** and select
**{{% icon "eye" %}} View/Edit**.
3. Update global settings, labels, parameters, and plugin settings as needed.
4. Review the TOML preview and resolve any validation errors.
5. Click **Save**.
### Update configuration name and description
1. In the {{% product-name %}} web interface, select **Configurations** in the
navigation bar.
2. Click the name of the configuration you want to edit or click the
**More button ({{% icon "tc-more" %}})** and select
**{{% icon "eye" %}} View/Edit**.
3. Under **Configuration Information**, click the text under **Name** or
**Description**. The name or description will load into a form field.
4. Provide a new name or description and click **{{% icon "check" %}}**.
## 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.

155
content/telegraf/controller/configs/use.md Normal file
View File

@ -0,0 +1,155 @@
---
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 -->

439
content/telegraf/controller/install/_index.md Normal file
View File

@ -0,0 +1,439 @@
---
title: Install Telegraf Controller
description: >
Download and install Telegraf Controller on Linux, macOS, and Windows
operating systems.
menu:
telegraf_controller:
name: Install Telegraf Controller
weight: 2
---
Telegraf Controller is a web-based configuration management system for Telegraf
agents. It provides a user-friendly interface for managing Telegraf
configurations, monitoring agents, and organizing plugins.
- [System Requirements](#system-requirements)
- [Download and install {{% product-name %}}](#download-and-install-telegraf-controller)
- [Set up your database](#set-up-your-database)
- [Configure {{% product-name %}}](#configure-telegraf-controller)
- [Access {{% product-name %}}](#access-telegraf-controller)
## System Requirements
- **Operating Systems**: Linux, macOS, Windows
- **Architecture**: x64 (Intel/AMD) or ARM64 (Apple Silicon/ARM)
- **Database**: SQLite (default), PostgreSQL, or PostgreSQL-compatible
- **Ports**: 8888 (web interface), 8000 (heartbeat service)
## Download and install {{% product-name %}}
1. **Download the {{% product-name %}} executable.**
> [!Note]
> #### Contact InfluxData for download
>
> If you are currently participating in the {{% product-name %}} private alpha,
> send your operating system and architecture to InfluxData and we will
> provide you with the appropriate {{% product-name %}} executable.
>
> If you are not currently in the private alpha and would like to be,
> [request early access](https://www.influxdata.com/products/telegraf-enterprise).
2. **Install {{% product-name %}}**.
> [!Important]
> #### {{% product-name %}} executable name
>
> The downloaded {{% product-name %}} executable includes platform-specific
> information in the file name. You can leave the information in the file
> name or you can rename the file to `telegraf_controller`. This
> documentation assumes the executable is named `telegraf_controller`.
{{< tabs-wrapper >}}
{{% tabs %}}
[Linux](#)
[macOS](#)
[Windows](#)
{{% /tabs %}}
{{% tab-content %}}
<!-------------------------------- BEGIN LINUX -------------------------------->
### Linux
You can add the `telegraf_controller` executable to your system path or you can
run it in place. You can also run {{% product-name %}} as a service.
- [Add the executable to your system path](#add-the-executable-to-your-system-path)
- [Run the executable in place](#run-the-executable-in-place)
- [Install the executable as a systemd service](#install-the-executable-as-a-systemd-service)
#### Add the executable to your system path
1. Add the following to your shell profile (for example `~/.bashrc`):
```bash
export PATH="$PATH:$PWD/telegraf_controller"
```
2. Reload the profile or open a new shell.
#### Run the executable in place
```sh
./telegraf_controller
```
#### Install the executable as a systemd service {note="Optional"}
1. Create a {{% product-name %}} service file:
```bash
sudo tee /etc/systemd/system/telegraf-controller.service > /dev/null <<EOF
[Unit]
Description=Telegraf Controller
After=network.target
[Service]
Type=simple
User=$USER
WorkingDirectory=/opt/telegraf-controller
ExecStart=/opt/telegraf-controller/telegraf_controller
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
```
2. Move the executable to `/opt`:
```bash
sudo mkdir -p /opt/telegraf-controller
sudo mv telegraf_controller /opt/telegraf-controller/
sudo chmod +x /opt/telegraf-controller/telegraf_controller
```
3. Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable telegraf-controller
sudo systemctl start telegraf-controller
```
<!--------------------------------- END LINUX --------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!-------------------------------- BEGIN MACOS -------------------------------->
### macOS
You can add the `telegraf_controller` executable to your system path or you can
run it in place. You can also run {{% product-name %}} as a LaunchDaemon service.
- [Prepare the downloaded executable](#prepare-the-downloaded-executable)
- [Add the executable to your system path](#macos-system-path)
- [Run the executable in place](#macos-executable-in-place)
- [Install as a LaunchDaemon](#install-as-a-launchdaemon)
#### Prepare the downloaded executable
1. Give `telegraf_controller` executable permissions:
```bash
chmod +x telegraf_controller
```
2. Remove the macOS quarantine attribute (if downloaded via browser):
```bash
xattr -d com.apple.quarantine telegraf_controller
```
#### Add the executable to your system path {#macos-system-path}
```bash
sudo mv telegraf_controller /usr/local/bin/
export PATH="/usr/local/bin:$PATH"
```
#### Run the executable in place {#macos-executable-in-place}
```bash
./telegraf_controller
```
#### Install as a LaunchDaemon {note="Optional"}
1. Create a plist file:
```bash
sudo tee /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist > /dev/null <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.influxdata.telegraf-controller</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/telegraf_controller</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/var/log/telegraf-controller.log</string>
<key>StandardErrorPath</key>
<string>/var/log/telegraf-controller.error.log</string>
</dict>
</plist>
EOF
```
2. Move the executable to `/usr/local/bin`:
```bash
sudo mv telegraf_controller /usr/local/bin/
```
3. Load the service:
```bash
sudo launchctl load /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
```
<!--------------------------------- END MACOS --------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN WINDOWS ------------------------------->
### Windows
You can run the `telegraf_controller` executable in place or you can run
{{% product-name %}} as a Windows service.
- [Run the application in place](#run-the-application-in-place)
- [Install as a Windows Service](#install-as-a-windows-service)
#### Run the application in place
**Double-click the executable** or open **Command Prompt or PowerShell** and
run:
```powershell
./telegraf_controller.exe
```
#### Install as a Windows Service {note="optional"}
Use NSSM (Non-Sucking Service Manager) to run {{% product-name %}} as a Windows
service.
1. [Download NSSM](https://nssm.cc/download)
2. In **Command Prompt or PowerShell**, install the {{% product-name %}} service:
```powershell
nssm install TelegrafController "C:\Program Files\TelegrafController\telegraf_controller.exe"
nssm set TelegrafController DisplayName "Telegraf Controller"
nssm set TelegrafController Description "Web-based Telegraf configuration manager"
nssm set TelegrafController Start SERVICE_AUTO_START
```
3. Start the service:
```powershell
nssm start TelegrafController
```
<!-------------------------------- END WINDOWS -------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Set up your database
{{% product-name %}} supports **SQLite** (default), **PostgreSQL**, or
**PostgreSQL-compatible** databases as its data backend.
### SQLite {note="(Default)"}
With SQLite installed, no additional setup is required.
{{% product-name %}} creates the database file automatically on first run.
#### Default SQLite data locations
{{% product-name %}} stores its data in platform-specific locations:
| Platform | Default Database Location |
| -------- | ------------------------------------------------------------- |
| Linux | `~/.local/share/telegraf-controller/sqlite.db` |
| macOS | `~/Library/Application Support/telegraf-controller/sqlite.db` |
| Windows | `%LOCALAPPDATA%\telegraf-controller\sqlite.db` |
### PostgreSQL
The following steps assume you have a running PostgreSQL or
PostgreSQL-compatible server running.
1. Create a database named `telegraf_controller`:
```sql
CREATE DATABASE telegraf_controller;
```
2. Run with PostgreSQL URL:
```sh
./telegraf_controller --database="postgresql://user:password@localhost:5432/telegraf_controller"
```
The application will automatically run migrations on first startup.
## Configure {{% product-name %}}
Use the following command line options to configure {{% product-name %}}.
### Configuration options
| Command Flag | Environment Variable | Description | Default |
| :--------------- | :------------------- | :--------------------------- | :------------------- |
| --port | PORT | Web interface and API port | `8888` |
| --heartbeat-port | HEARTBEAT_PORT | Agent heartbeat service port | `8000` |
| --database | DATABASE | Database connection string | Auto-detected SQLite |
| --ssl-cert | SSL_CERT | SSL certificate file path | None |
| --ssl-key | SSL_KEY | SSL private key file path | None |
#### Examples
{{< tabs-wrapper >}}
{{% tabs "medium" %}}
[Use Command Flags](#)
[Use Environment Variables](#)
{{% /tabs %}}
{{% tab-content %}}
<!---------------------------- BEGIN COMMAND FLAGS ---------------------------->
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Linux/macOS](#)
[Windows (Powershell)](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!------------------ BEGIN LINUX/MACOS COMMAND FLAGS ------------------>
```bash
# Use custom ports
telegraf_controller --port=3000 --heartbeat-port=9000
# Use PostgreSQL database
telegraf_controller \
--database="postgresql://user:password@localhost:5432/telegraf_db"
# Use custom SQLite database location
telegraf_controller \
--database="/path/to/custom/database.db"
# Enable HTTPS
telegraf_controller \
--ssl-cert="/path/to/cert.pem" \
--ssl-key="/path/to/key.pem"
```
<!------------------- END LINUX/MACOS COMMAND FLAGS ------------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-------------------- BEGIN WINDOWS COMMAND FLAGS -------------------->
```powershell
# Use custom ports
./telegraf_controller.exe --port=3000 --heartbeat-port=9000
# Use PostgreSQL database
./telegraf_controller.exe `
--database="postgresql://user:password@localhost:5432/telegraf_db"
# Use custom SQLite database location
./telegraf_controller.exe `
--database="C:\path\to\custom\database.db"
# Enable HTTPS
./telegraf_controller.exe `
--ssl-cert="C:\path\to\cert.pem" `
--ssl-key="C:\path\to\key.pem"
```
<!--------------------- END WINDOWS COMMAND FLAGS --------------------->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
<!----------------------------- END COMMAND FLAGS ----------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------ BEGIN ENVIRONMENT VARIABLES ------------------------>
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Linux/macOS](#)
[Windows (Powershell)](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-------------- BEGIN LINUX/MACOS ENVIRONMENT VARIABLES -------------->
```bash
# Use custom ports
PORT=3000
HEARTBEAT_PORT=9000
# Use PostgreSQL database
DATABASE=postgresql://user:password@localhost:5432/telegraf_db
# Use custom SQLite database location
DATABASE=/path/to/custom/database.db
# Enable HTTPS
SSL_CERT=/path/to/cert.pem
SSL_KEY=/path/to/key.pem
telegraf_controller
```
<!--------------- END LINUX/MACOS ENVIRONMENT VARIABLES --------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!---------------- BEGIN WINDOWS ENVIRONMENT VARIABLES ---------------->
```powershell
# Use custom ports
$env:PORT=3000
$env:HEARTBEAT_PORT=9000
# Use PostgreSQL database
$env:DATABASE=postgresql://user:password@localhost:5432/telegraf_db
# Use custom SQLite database location
$env:DATABASE=C:\path\to\custom\database.db
# Enable HTTPS
$env:SSL_CERT=C:\path\to\cert.pem
$env:SSL_KEY=C:\path\to\key.pem
./telegraf_controller.exe
```
<!----------------- END WINDOWS ENVIRONMENT VARIABLES ----------------->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
<!------------------------- END ENVIRONMENT VARIABLES ------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Access {{% product-name %}}
Once started, access the {{% product-name %}} web interface at
<http://localhost:8888> _(or using your custom port)_.

162
content/telegraf/controller/install/troubleshoot.md Normal file
View File

@ -0,0 +1,162 @@
---
title: Troubleshoot Telegraf Controller installation
description: >
Resolve common installation and startup issues with {{% product-name %}}.
menu:
telegraf_controller:
name: Troubleshoot installation
parent: Install Telegraf Controller
weight: 101
---
Resolve common installation and startup issues with {{% product-name %}}.
Check the symptoms below and apply the recommended fix before continuing with
configuration.
- [Port Already in Use](#port-already-in-use)
- [Permission Denied (Linux/macOS)](#permission-denied-linux-macos)
- [Database Connection Issues](#database-connection-issues)
- [Firewall Configuration](#firewall-configuration)
- [Security Considerations](#security-considerations)
## Port already in use
If the default ports (8888 and 8000) are already in use, use the following
configuration options to specify alternative ports:
| Description | Environment Variable | Command Flag |
| :-------------------- | -------------------- | ------------------ |
| Web Interface and API | `PORT` | `--port` |
| Heartbeat server | `HEARTBEAT_PORT` | `--heartbeat-port` |
{{< tabs-wrapper >}}
{{% tabs "medium" %}}
[Use Environment Variables](#)
[Use Command Flags](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------ BEGIN ENVIRONMENT VARIABLES ------------------------>
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Linux/macOS](#)
[Windows (Powershell)](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!------------------------- BEGIN LINUX/MACOS ------------------------->
```sh
PORT=3000
HEARTBEAT_PORT=3001
telegraf_controller
```
<!-------------------------- END LINUX/MACOS -------------------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!--------------------- BEGIN WINDOWS POWERSHELL ---------------------->
```powershell
$env:PORT=3000
$env:HEARTBEAT_PORT=3001
./telegraf_controller.exe
```
<!---------------------- END WINDOWS POWERSHELL ----------------------->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
<!------------------------- END ENVIRONMENT VARIABLES ------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!---------------------------- BEGIN COMMAND FLAGS ---------------------------->
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Linux/macOS](#)
[Windows (Powershell)](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!------------------------- BEGIN LINUX/MACOS ------------------------->
```sh
telegraf_controller --port=3000 --heartbeat-port=3001
```
<!-------------------------- END LINUX/MACOS -------------------------->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!--------------------- BEGIN WINDOWS POWERSHELL ---------------------->
```powershell
./telegraf_controller.exe --port=3000 --heartbeat-port=3001
```
<!---------------------- END WINDOWS POWERSHELL ----------------------->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
<!----------------------------- END COMMAND FLAGS ----------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Permission denied (Linux/macOS)
If you do not have permission to run the `telegraf_controller` executable,
ensure the file has executable permissions:
```sh
chmod +x telegraf_controller
```
### macOS: Remove the quarantine attribute
macOS places a quarantine attribute on executable files downloaded from a
browser and restricts file execution. To remove the quarantine attribute, use
**Terminal** or **System Settings**.
#### Remove the quarantine attribute in Terminal
```bash
xattr -d com.apple.quarantine telegraf_controller
```
#### Remove the quarantine attribute in System Settings
1. Attempt to run the `telegraf_controller` executable.
2. In macOS, navigate to **System Settings** > **Privacy & Security**.
3. Scroll to the bottom of the window.
4. Next to the message about {{% product-name %}}, click **Allow**.
## Database connection issues
If there are database connection issues, check the following depending on which
database you're using:
### SQLite
- Check file permissions for SQLite database directory
### PostgreSQL
- Ensure PostgreSQL is running
- Check the format of and credentials in your data source name (DSN or database URL)
- Verify network connectivity
## Firewall configuration
Ensure the following ports are open in your network Firewall configuration:
- **Web Interface and API**: TCP `8888` (or custom port)
- **Heartbeat server**: TCP `8000` (or custom heartbeat port)
## Security considerations
- **SSL/TLS**: Use `--ssl-cert` and `--ssl-key` options for production deployments
- **Firewall**: Restrict access to the web interface and heartbeat ports
- **Database Security**:
- **PostgreSQL**: Use strong passwords
- **SQLite**: Ensure the database file is protected with restricted permissions
(`chmod 600`)

140
content/telegraf/controller/install/uninstall.md Normal file
View File

@ -0,0 +1,140 @@
---
title: Uninstall Telegraf Controller
description: >
Uninstall Telegraf Controller and remove all files associated with the
application.
menu:
telegraf_controller:
name: Uninstall
parent: Install Telegraf Controller
weight: 102
---
Uninstall Telegraf Controller and remove all files associated with the
application. This process depends on your operating system and installation
method.
{{< tabs-wrapper >}}
{{% tabs %}}
[Linux](#)
[macOS](#)
[Windows](#)
{{% /tabs %}}
{{% tab-content %}}
<!-------------------------- BEGIN LINUX -------------------------->
## Linux
To fully uninstall {{% product-name %}} from Linux:
1. **Stop {{% product-name %}}**:
- If running the application in place, stop the `telegraf_controller` process.
- If you installed {{% product-name %}} as a systemd service stop and
disable the service:
```bash
sudo systemctl stop telegraf-controller
sudo systemctl disable telegraf-controller
```
2. **Remove all files associated with {{% product-name %}}**:
```bash
# Remove the telegraf_controller executable
sudo rm -rf /opt/telegraf-controller
# Remove the telegraf_controller shared directory, which includes the
# SQLite database if using SQLite
rm -rf ~/.local/share/telegraf_controller
# Remove the service file if you installed Telegraf Controller as a service
sudo rm /etc/systemd/system/telegraf-controller.service
```
3. If using PostgreSQL, **delete the `telegraf_controller` database** from your
PostgreSQL instance:
```sql
DROP DATABASE telegraf_controller;
```
<!--------------------------- END LINUX --------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!-------------------------- BEGIN MACOS -------------------------->
## macOS
To fully uninstall {{% product-name %}} from macOS:
1. **Stop {{% product-name %}}**:
- If running the application in place, stop the `telegraf_controller` process.
- If you installed {{% product-name %}} as a macOS LaunchDaemon and are
running it as a service, stop the service:
```bash
sudo launchctl unload /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
```
2. **Remove all files associated with {{% product-name %}}**:
```bash
# Remove the telegraf_controller executable
sudo rm /usr/local/bin/telegraf_controller
# Remove the telegraf_controller application directory, which includes the
# SQLite database if using SQLite
rm -rf ~/Library/Application\ Support/telegraf_controller
# Remove the plist file if you installed Telegraf Controller as a LaunchDaemon
sudo rm /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
```
3. If using PostgreSQL, **delete the `telegraf_controller` database** from your
PostgreSQL instance:
```sql
DROP DATABASE telegraf_controller;
```
<!--------------------------- END MACOS --------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!-------------------------- BEGIN WINDOWS -------------------------->
## Windows
To fully uninstall {{% product-name %}} from Windows:
1. **Stop {{% product-name %}}**:
- If running the application in place, stop the `telegraf_controller` process.
- If you installed {{% product-name %}} as a service, stop and remove the
service:
```bash
nssm stop TelegrafController
nssm remove TelegrafController confirm
```
2. **Remove all files associated with {{% product-name %}}**:
```powershell
# Remove the telegraf_controller executable and other related files,
# including the SQLite database if using SQLite
Remove-Item -Path "$env:LOCALAPPDATA\telegraf_controller" -Recurse
Remove-Item -Path "C:\Program Files\TelegrafController" -Recurse
```
3. If using PostgreSQL, **delete the `telegraf_controller` database** from your
PostgreSQL instance:
```sql
DROP DATABASE telegraf_controller;
```
<!--------------------------- END WINDOWS --------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}

12
content/telegraf/controller/labels/_index.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Manage Telegraf Controller labels
description: >
Use labels to customize and organize Telegraf configurations
and agents in Telegraf Controller.
menu:
telegraf_controller:
name: Manage labels
weight: 5
cascade:
draft: true
---

22
content/telegraf/controller/telegraf-enterprise.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Telegraf Enterprise
description: >
Telegraf Enterprise is a premium, enterprise-grade offering that combines the
Telegraf Controller, a web application for managing Telegraf deployments,
with an Enterprise Support Contract for Telegraf. It is designed for
organizations running Telegraf at scale who require centralized configuration
management, operational visibility, governance, and expert support from
InfluxData.
menu:
telegraf_controller:
name: Telegraf Enterprise
weight: 10
draft: true
---
<!-- TODO Add information about Telegraf Enterprise
- Telegraf Enterprise includes both Telegraf Controller and Telegraf Support
- CTA for more information about Telegraf Enterprise.
This will likely be shared content and have a counter part in the main Telegraf docs
-->

14
data/products.yml
View File

@ -252,6 +252,20 @@ telegraf:
- How do I use Telegraf for MQTT?
ai_input_placeholder: "Ask questions about Telegraf and InfluxDB"
telegraf_controller:
name: Telegraf Controller
altname: Controller
namespace: telegraf
menu_category: other
versions: [v1]
latest: 0.0
latest_patch: 0.0.0
# ai_sample_questions:
# - How do I configure Telegraf for InfluxDB 3?
# - How do I write a custom Telegraf plugin?
# - How do I use Telegraf for MQTT?
# ai_input_placeholder: "Ask questions about Telegraf and InfluxDB"
chronograf:
name: Chronograf
namespace: chronograf

34
layouts/partials/article/special-state.html
View File

@ -2,26 +2,34 @@
{{ $productPathData := split .RelPermalink "/" }}
{{ $product := index $productPathData 1 }}
{{ $version := index $productPathData 2 }}
{{ $productKey := cond (eq $product "influxdb3") (print "influxdb3_" (replaceRE "-" "_" $version)) $product }}
{{ $isInfluxDB3 := eq $product "influxdb3" }}
{{ $isTelegrafController := and (eq $product "telegraf") (eq $version "controller") }}
{{ .Store.Set "productKey" $product }}
{{ if $isInfluxDB3 }}
{{ .Store.Set "productKey" (print "influxdb3_" (replaceRE "-" "_" $version)) }}
{{ else if $isTelegrafController }}
{{ .Store.Set "productKey" "telegraf_controller" }}
{{ end }}
{{ $productKey := .Store.Get "productKey" }}
{{ $productData := index $.Site.Data.products $productKey }}
{{ $displayName := $productData.name }}
{{ $earlyAccessList := slice "" }}
{{ $productPathWhitelist := slice "telegraf/controller" }}
{{ if in $earlyAccessList (print $product "/" $version )}}
{{ if in $productPathWhitelist (print $product "/" $version )}}
<div class="block special-state">
<div class="state-content">
<h4 id="influxdb3-explorer-ga">{{ $displayName }} is Generally Available</h4>
<h4 id="telegraf-controller-private-alpha">{{ $displayName }} is in Private Alpha</h4>
<p>
{{ $displayName }} is generally available and is ready for production use.
We welcome and encourage your input about your experience with Explorer and
invite you to <strong>join our public channels</strong> for updates and to
share feedback.
{{ $displayName }} is in private alpha. If you are interested in being a
part of the private alpha program, please sign up:
</p>
<p><a href="https://www.influxdata.com/products/telegraf-enterprise" class="btn">Sign Up for the Alpha</a></p>
<p>
<em>The {{ $displayName}} documentation is a work in progress, and we are actively
While in alpha, {{ $displayName }} is <strong>not meant for production use</strong>.
The {{ $displayName}} documentation is a work in progress, and we are actively
working to improve it. If you have any questions or suggestions, please
<a href="https://github.com/influxdata/docs-v2/issues/new?labels=InfluxDB%203%20Explorer">submit an issue</a>.
We welcome any and all contributions.</em>
<a href="https://github.com/influxdata/docs-v2/issues/new?labels=Telegraf%20Controller">submit an issue</a>.
We welcome any and all contributions.
</p>
<div class="expand-wrapper">
<div class="expand" id="feedback-channels">
@ -30,9 +38,9 @@
</p>
<div class="expand-content" style="display: none;" >
<ul class="feedback-channels">
<li><a href="https://discord.gg/9zaNCW2PRT" target="_blank" class="discord">InfluxDB Discord Server <em style="opacity:.5">(Preferred)</em></a></li>
<!-- <li><a href="https://discord.gg/9zaNCW2PRT" target="_blank" class="discord">InfluxDB Discord Server <em style="opacity:.5">(Preferred)</em></a></li> -->
<li><a href="https://influxdata.com/slack" target="_blank" class="slack">InfluxDB Community Slack <em style="opacity:.5">(Preferred)</em></a></li>
<li><a href="https://community.influxdata.com" target="_blank" class="community">InfluxData Community</a></li>
<li><a href="https://influxdata.com/slack" target="_blank" class="slack">InfluxDB Community Slack</a></li>
<li><a href="https://reddit.com/r/influxdb" target="_blank" class="reddit">InfluxDB Subreddit</a></li>
</ul>
</div>

2
layouts/partials/header/search-attributes.html
View File

@ -7,7 +7,7 @@
{{ $searchTag := print $product "-" $version }}
{{ if not .IsHome }}
{{ if or (eq $version (replaceRE `\.[0-9x]+$` "" (index $.Site.Data.products $product).latest)) (or (eq $product "platform") (eq $product "resources")) (in (slice "cloud" "core" "enterprise" "cloud-serverless" "cloud-dedicated" "clustered") $version ) }}
{{ if or (eq $version (replaceRE `\.[0-9x]+$` "" (index $.Site.Data.products $product).latest)) (or (eq $product "platform") (eq $product "resources")) (in (slice "cloud" "core" "enterprise" "cloud-serverless" "cloud-dedicated" "clustered" "explorer" "controller") $version ) }}
<meta name="docsearch:latest" content="true">
{{ end }}
{{ if and (ne $product "platform") (ne $product "resources") (ne $version "") }}

4
layouts/partials/sidebar.html
View File

@ -94,8 +94,8 @@
{{ end }}
<!-- Platform menu for 1.x docs -->
{{ $platformWhitelist := `telegraf|chronograf|kapacitor|enterprise_influxdb|influxdb_1` }}
{{ if gt (len (findRE $platformWhitelist $menuKey)) 0 }}
{{ $platformWhitelist := (slice "telegraf_v1" "chronograf_v1" "kapacitor_v1" "enterprise_influxdb_v1" "influxdb_v1") }}
{{ if (in $platformWhitelist $menuKey) }}
<h4 class="platform">InfluxData Platform</h4>
{{ partial "sidebar/nested-menu" (dict "page" $currentPage "menu" $platformMenu "siteData" .Site.Data) }}
{{ end }}

11
layouts/partials/topnav/product-selector.html
View File

@ -23,12 +23,13 @@ Identify products by their product path. Dictionary schema:
{{ $influxdb3CloudDedicated := dict "influxdb3/cloud-dedicated" (slice $.Site.Data.products.influxdb3_cloud_dedicated.name "cloud-dedicated") }}
{{ $influxdb3Clustered := dict "influxdb3/clustered" (slice $.Site.Data.products.influxdb3_clustered.name "clustered") }}
{{ $telegraf := dict "telegraf/v1" (slice "Telegraf" "telegraf") }}
{{ $telegrafController := dict "telegraf/controller" (slice "Telegraf Controller" "telegraf_controller") }}
{{ $chronograf := dict "chronograf/v1" (slice "Chronograf" "chronograf") }}
{{ $kapacitor := dict "kapacitor/v1" (slice "Kapacitor" "kapacitor") }}
{{ $flux := dict "flux/v0" (slice "Flux" "flux") }}
{{ $enterpriseInfluxdb := dict "enterprise_influxdb/v1" (slice "InfluxDB Enterprise" "enterprise_v1") }}
{{ $productInfo := merge $influxdbOSSv1 $influxdbOSSv2 $influxdbCloud $influxdb3Core $influxdb3Enterprise $influxdb3CloudServerless $influxdb3CloudDedicated $influxdb3Clustered $telegraf $chronograf $kapacitor $influxdb3Explorer $flux $enterpriseInfluxdb }}
{{ $productInfo := merge $influxdbOSSv1 $influxdbOSSv2 $influxdbCloud $influxdb3Core $influxdb3Enterprise $influxdb3CloudServerless $influxdb3CloudDedicated $influxdb3Clustered $telegraf $telegrafController $chronograf $kapacitor $influxdb3Explorer $flux $enterpriseInfluxdb }}
{{ define "productLink" }}
{{ $defaultAltProductPage := $.context.GetPage ((replaceRE .pageRoot .productPath $.context.Page.RelPermalink) | replaceRE `\/$` "") }}
@ -79,9 +80,15 @@ Identify products by their product path. Dictionary schema:
</ul>
</div>
<div class="product-group">
<div class="group-title"><p>Other products</p></div>
<div class="group-title"><p>Telegraf</p></div>
<ul class="item-list products">
<li>{{ template "productLink" (merge (dict "productPath" "telegraf/v1") $templateDefaults) }}</li>
<li>{{ template "productLink" (merge (dict "productPath" "telegraf/controller" "state" "alpha") $templateDefaults) }}</li>
</ul>
</div>
<div class="product-group">
<div class="group-title"><p>Other products</p></div>
<ul class="item-list products">
<li>{{ template "productLink" (merge (dict "productPath" "chronograf/v1") $templateDefaults) }}</li>
<li>{{ template "productLink" (merge (dict "productPath" "kapacitor/v1") $templateDefaults) }}</li>
</ul>

4
layouts/shortcodes/icon.html
View File

@ -2,7 +2,7 @@
{{- $icon := .Get 0 | default "influx" -}}
{{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}}
{{- $product := index $productPathData 0 -}}
{{- $productVersion := index $productPathData 1 | default "v0.0" -}}
{{- $productVersion := index $productPathData 1 | default "v0" -}}
{{- $defaultClockface := "" -}}
{{- with (index .Site.Data.clockface $product) -}}
@ -81,6 +81,8 @@
<span class="inline ui-toggle blue"><span class="circle"></span></span>
{{- else if eq $icon "toggle-green" -}}
<span class="inline ui-toggle green"><span class="circle"></span></span>
{{- else if (eq $icon "tc-more") -}}
<span class="inline" style="margin: 0 .25rem; vertical-align: middle;">&#8942;</span>
{{- end -}}
{{- else if eq $version "v3" -}}
{{- if or (eq $icon "nav-admin") (eq $icon "influx") (eq $icon "influx-icon") -}}

2
layouts/shortcodes/product-name.html
View File

@ -21,6 +21,8 @@
{{- $scratch.Set "productData" .Site.Data.products.influxdb3_cloud_dedicated -}}
{{- else if eq $currentProduct "clustered" -}}
{{- $scratch.Set "productData" .Site.Data.products.influxdb3_clustered -}}
{{- else if eq $currentProduct "controller" -}}
{{- $scratch.Set "productData" .Site.Data.products.telegraf_controller -}}
{{- end -}}
{{- $productData := $scratch.Get "productData" -}}
{{- if eq $length "long" }}

21
layouts/shortcodes/telegraf/dynamic-values.html Normal file
View File

@ -0,0 +1,21 @@
{{- /* Define more precise regex patterns for each dynamic value type */ -}}
{{- /* Note: markdownify converts & to &amp; so we need to match that */ -}}
{{- $paramsRegex := `&amp;\{[^}]+\}` -}}
{{- $envsRegex := `\$\{[^}]+\}` -}}
{{- $secretsRegex := `@\{[^:]+:[^}]+\}` -}}
{{- /* Get the inner content and markdownify it */ -}}
{{- $code := .Inner | markdownify -}}
{{- /* Apply replacements for each type of dynamic value */ -}}
{{- /* Replace parameters with span class="param" */ -}}
{{- $code = replaceRE $paramsRegex `<span class="tc-dynamic-value param">$0</span>` $code -}}
{{- /* Replace environment variables with span class="env" */ -}}
{{- $code = replaceRE $envsRegex `<span class="tc-dynamic-value env">$0</span>` $code -}}
{{- /* Replace secrets with span class="secret" */ -}}
{{- $code = replaceRE $secretsRegex `<span class="tc-dynamic-value secret">$0</span>` $code -}}
{{- /* Output the processed code */ -}}
{{ $code | safeHTML }}

BIN
static/img/telegraf/controller-agents-list.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 83 KiB

BIN
static/img/telegraf/controller-code-editor.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
static/img/telegraf/controller-command-builder.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
static/img/telegraf/controller-telegraf-builder.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 93 KiB