Manage configuration versions

Telegraf Controller keeps a version history for every Telegraf configuration. Use the version history to review past changes, compare two versions, roll a configuration back to a previous version, and prune versions you no longer need.

How versions are created

Telegraf Controller creates configuration versions automatically:

• When you create a configuration, Telegraf Controller records it as the first version with the change note “Initial version”.
• When you save a configuration whose TOML content has changed, Telegraf Controller records a new version.
• Changes to configuration metadata, such as the configuration name or description, do not create a new version.

When saving changes, use the optional Change note field to attach a description of your changes up to 1,000 characters. Change notes make versions easier to identify in the version history.

Versions are kept until you prune them; there is no automatic retention limit.

View version history

1. In the Telegraf Controller web interface, select Configurations in the navigation bar.
2. Click the name of the configuration.
3. Select the Versions tab.

The version history table includes the following for each version:

• Version: the version number. Telegraf Controller numbers versions sequentially, starting at 1. The version that matches the current configuration content is marked Current.
• Time: when the version was created.
• Author: the user who saved the version.
• Change Note: the description provided when the version was saved.

To view the full TOML content stored in a version, click the More button () in the version’s row and select View/Edit.

Update a change note

1. In the version’s row, click the More button () and select View/Edit.
2. Update the change note and confirm your changes.

Compare versions

1. In the version history table, select exactly two versions.
2. Click Compare.

The Compare Versions dialog displays a diff of the TOML content of the two versions, using the lower-numbered version as the base.

Roll back to a previous version

Rolling back restores the TOML content and editor mode of a previous version. A rollback does not rewrite history: Telegraf Controller creates a new version containing the restored content, with a change note that records which version it was restored from.

1. In the version’s row, click the More button () and select Rollback.
2. Review the confirmation and click Confirm & Rollback.

You can roll back to any version except the version marked Current.

After a rollback, agents configured with --config-url-watch-interval load the restored configuration on their next watch interval. For details, see Auto-update agents.

Prune versions

Prune versions to remove them from the version history, for example, to clean up old versions you no longer need. Pruning is permanent.

Prune a single version

1. In the version’s row, click the More button () and select Prune.
2. Review the confirmation and click Confirm & Prune.

Prune selected versions

1. In the version history table, select the versions to prune.
2. Click Prune.
3. Review the confirmation and click Confirm & Prune.

If your selection includes the current version, Telegraf Controller keeps the current version and prunes the other selected versions.

Prune versions by criteria

With no versions selected:

1. Click Prune.
2. Select a pruning criterion:
   • Before version: prune all versions before the version you select.
   • Before date & time: prune all versions created before the date and time you select.
3. Review the confirmation and click Confirm & Prune.

Permissions

Version operations require permissions on the Configs resource:

• Read: view and compare versions.
• Write: roll back to a version.
• Delete: prune versions.

For how permissions map to user roles and API tokens, see Authentication and authorization.

If audit logging is enabled, Telegraf Controller records version operations (rollbacks, change note updates, and pruning) in the audit log.

Version API

Manage versions programmatically using the Telegraf Controller API. Version endpoints are available under /api/configs/{configId}/versions. For the full API reference, see Telegraf Controller API.