How to Upgrade From `auth.json` to Token-Based Authentication?

Question

How do I upgrade from using auth.json to token-based authentication?

Environment

Container platform: Docker and Podman

Answer

If you configured your Hybrid Deployment Agent before September 18, 2024, using the auth.json and config.json files, you must reconfigure it to use token-based authentication. This new method improves security and simplifies agent management.

You can update your existing agent using one of the following methods:

Automated update (recommended)
Manual update

After completing the upgrade, your directory structure should look like this:

$HOME/fivetran
├── conf
│   ├── config.json
├── data
├── hdagent.sh
├── hd-debug.sh
├── stats
└── tmp

Automated update

If your Hybrid Deployment Agent is in the default $HOME/fivetran directory, use the automated method. If you use a custom directory, follow the Manual update steps instead.

Pause all connections using the agent.
Stop the agent container.
In the Fivetran dashboard, go to Account Settings > General > Hybrid Deployment Agents.
Regenerate the token for your agent.
Run the automated installation command using the new token. The installation script automatically detects your existing config.json, updates it, and moves it to $HOME/fivetran/conf. The auth.json and docker-compose.yaml files remain in place. You can safely delete them after confirming a successful update.
Install and start the updated agent.
Manage the agent container using the hdagent.sh script.
Resume your connections and confirm they reconnect successfully.

Manual update

If your agent installation is not in the default $HOME/fivetran directory, use the manual method.