Upgrade Telegraf Controller

Upgrade Telegraf Controller by replacing the telegraf_controller executable with a newer version and restarting the service. On startup, Telegraf Controller applies any pending database migrations automatically; there is no separate migration step.

Before you upgrade, review the release notes for each version between your current version and the target version.

• Back up your database
• Upgrade Telegraf Controller
• Verify the upgrade
• Upgrade a high-availability cluster

Back up your database

Back up your database before upgrading so you can restore it if the upgrade fails:

• SQLite (default): stop Telegraf Controller, then copy the database file and, if present, its -wal and -shm companion files. For the default file locations, see Default SQLite data locations.
• PostgreSQL: use your database or provider backup tooling, for example pg_dump.

Upgrade Telegraf Controller

1. Download the new Telegraf Controller executable.

   Download Telegraf Controller

   Telegraf Controller executable name

   The downloaded Telegraf Controller executable includes platform-specific information in the file name. This documentation assumes you rename the file to telegraf_controller, matching the install instructions.

2. Replace the installed executable and restart Telegraf Controller.

   Linux macOS Windows

   Linux

   Upgrade a systemd service installation

   sudo systemctl stop telegraf-controller
   sudo mv telegraf_controller /opt/telegraf-controller/telegraf_controller
   sudo chmod +x /opt/telegraf-controller/telegraf_controller
   sudo systemctl start telegraf-controller

   If your service file uses a different working directory or executable path, replace the executable at that location instead.

   Upgrade an in-place installation

   1. Stop the running telegraf_controller process.

   2. Replace the existing executable with the new version and give it executable permissions:

      chmod +x telegraf_controller

   3. Restart Telegraf Controller:

      ./telegraf_controller

   macOS

   Prepare the downloaded executable

   1. Give telegraf_controller executable permissions:

      chmod +x telegraf_controller

   2. Remove the macOS quarantine attribute (if downloaded via browser):

      xattr -d com.apple.quarantine telegraf_controller

   Upgrade a LaunchDaemon installation

   sudo launchctl unload /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
   sudo mv telegraf_controller /usr/local/bin/
   sudo launchctl load /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist

   Upgrade an in-place installation

   1. Stop the running telegraf_controller process.

   2. Replace the existing executable with the new, prepared executable.

   3. Restart Telegraf Controller:

      ./telegraf_controller

   Windows

   Upgrade a Windows service installation

   In Command Prompt or PowerShell:

   nssm stop TelegrafController
   Move-Item -Force telegraf_controller.exe "C:\Program Files\TelegrafController\telegraf_controller.exe"
   nssm start TelegrafController

   Upgrade an in-place installation

   1. Close the running Telegraf Controller application.

   2. Replace the existing telegraf_controller.exe with the new version.

   3. Restart Telegraf Controller:

      ./telegraf_controller.exe

Verify the upgrade

1. Confirm the installed executable reports the new version:

   Linux/macOS Windows (PowerShell)

   telegraf_controller --version

   ./telegraf_controller.exe --version

   The running version is also displayed in the Telegraf Controller web interface, at the bottom of the navigation menu.

2. Confirm the service is running, the web interface loads, and agents continue to report.

If Telegraf Controller fails to start after an upgrade, check the service logs for migration errors and see Troubleshoot installation.

Upgrade a high-availability cluster

Upgrade a high-availability cluster by upgrading one node at a time. The cluster keeps serving throughout: when you stop a node, any leadership it holds transfers to a standby within a few seconds, and the remaining nodes continue to accept agent heartbeats and serve the web interface and API.

1. On one node, stop Telegraf Controller, replace the executable, and restart it, following the steps above.
2. Wait for the node to report healthy through your load balancer’s health checks, and confirm the new version with telegraf_controller --version.
3. Repeat for each remaining node.

During a rolling upgrade:

• The first upgraded node applies any pending database migrations at startup. Migrations run under a cluster-wide lock, so nodes never run migrations concurrently; a node that starts while another is migrating waits for it to finish.
• Until every node is upgraded, the cluster runs mixed versions. Complete the roll promptly rather than leaving nodes on different versions.