Proxy Agent Upgrade to Docker

Windows prerequisites

Before migrating, confirm the following on the Windows Server host that will run the Proxy Agent.

• The Windows Containers feature is installed. To check, run Get-WindowsFeature -Name Containers in an elevated PowerShell session. If it isn't installed, run Install-WindowsFeature -Name Containers, then restart the host.
• Docker CE is installed. To check, run docker version. If you need to install Docker, follow the instructions in the Microsoft documentation. Docker CE 29.8.2 is tested; the Microsoft installation script installs the current release.
• Docker is running Windows containers. To check, run docker info --format '{{.OSType}}'. The command must return windows.
• You run all migration steps in an elevated PowerShell session as a member of the local Administrators group. By default, only members of the local Administrators group can run Docker commands on Windows Server.
• Docker is enabled to start automatically when the host boots. To check, run (Get-Service docker).StartType. If the command doesn't return Automatic, run Set-Service -Name docker -StartupType Automatic in an elevated PowerShell session.

Migrate from older Proxy Agent on Windows

The migration steps depend on the contents of your existing configuration file. If it contains client_cert and client_private_key, follow Migrate using a current configuration on Windows. If it contains proxy_server_uri, follow Migrate using a legacy configuration on Windows. A version 1.1.0 or later installation with "enable_migration": false uses the legacy configuration format.

Migrate using a current configuration on Windows

Use this procedure if your existing configuration file contains client_cert and client_private_key.

1. Stop the running Proxy Agent.

   • If the Proxy Agent runs as a Windows service (for example, installed with the EXE installer), find the service. Run the following command in an elevated PowerShell session:

     Get-Service | Where-Object { $_.Name -like '*Fivetran*' -or $_.DisplayName -like '*Fivetran*' -or $_.DisplayName -like '*Proxy Agent*' }
     

     If the command returns the Proxy Agent service, stop it and prevent it from starting automatically. Replace <service_name> with the value in the Name column:

     Stop-Service -Name '<service_name>'
     Set-Service -Name '<service_name>' -StartupType Manual
     

     If the command returns no service, or the service name doesn't match your installation, find the service in Services (services.msc) and stop it there, or identify how the Proxy Agent was started and stop it using that method.

   • If the Proxy Agent doesn't run as a Windows service (for example, it was started manually, by a script, or by Task Scheduler), stop it using the same method that started it. These commands don't apply to that installation type.

   • Before you continue, confirm that the previous Proxy Agent is no longer running. Running the previous Proxy Agent and the Docker-based Proxy Agent with the same configuration at the same time can disconnect the Proxy Agent. To check for a remaining Java process, run:

     Get-CimInstance Win32_Process -Filter "Name = 'java.exe'" | Select-Object ProcessId, CommandLine
     

     If a process with proxyagent in its command line is listed, stop it before you continue.

2. Download the installer and run it with the path to your existing configuration file. Replace C:\path\to\config.json with the actual path to your configuration file. If you're not sure where the configuration file is located, check your original installation directory or the startup command you used when installing the Proxy Agent.

   Invoke-WebRequest -Uri https://raw.githubusercontent.com/fivetran/proxy_agent/main/install.ps1 -OutFile install.ps1 -UseBasicParsing
   Unblock-File .\install.ps1
   $env:RUNTIME = 'docker'
   & .\install.ps1 C:\path\to\config.json
   

   The installer copies your configuration to $env:USERPROFILE\fivetran-proxy-agent\config\config.json, selects the Proxy Agent image that matches your Windows Server version, pulls the latest Docker image, and starts the Proxy Agent. The installer does not modify your original configuration file.

3. Verify that the Proxy Agent is running:

   & "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" status
   

   The container should show as (healthy). You can also confirm that the Proxy Agent is online in the Fivetran dashboard. Go to Account Settings > Connection Methods > Proxy Agents.

Migrate using a legacy configuration on Windows

Use this procedure if your existing configuration file contains proxy_server_uri. This format is used by versions earlier than 1.1.0 and by version 1.1.0 or later installations with "enable_migration": false. The Docker installer uses the existing agent_id and auth_token to request a new configuration from Fivetran, so this migration does not depend on the legacy infrastructure.

1. Stop the running Proxy Agent.

   • If the Proxy Agent runs as a Windows service (for example, installed with the EXE installer), find the service. Run the following command in an elevated PowerShell session:

     Get-Service | Where-Object { $_.Name -like '*Fivetran*' -or $_.DisplayName -like '*Fivetran*' -or $_.DisplayName -like '*Proxy Agent*' }
     

     If the command returns the Proxy Agent service, stop it and prevent it from starting automatically. Replace <service_name> with the value in the Name column:

     Stop-Service -Name '<service_name>'
     Set-Service -Name '<service_name>' -StartupType Manual
     

     If the command returns no service, or the service name doesn't match your installation, find the service in Services (services.msc) and stop it there, or identify how the Proxy Agent was started and stop it using that method.

   • If the Proxy Agent doesn't run as a Windows service (for example, it was started manually, by a script, or by Task Scheduler), stop it using the same method that started it. These commands don't apply to that installation type.

   • Before you continue, confirm that the previous Proxy Agent is no longer running. Running the previous Proxy Agent and the Docker-based Proxy Agent with the same configuration at the same time can disconnect the Proxy Agent. To check for a remaining Java process, run:

     Get-CimInstance Win32_Process -Filter "Name = 'java.exe'" | Select-Object ProcessId, CommandLine
     

     If a process with proxyagent in its command line is listed, stop it before you continue.

2. Download the installer and run it with the path to your existing configuration file. Replace C:\path\to\config.json with the actual path to your configuration file. If you're not sure where the configuration file is located, check your original installation directory or the startup command you used when installing the Proxy Agent.

   Invoke-WebRequest -Uri https://raw.githubusercontent.com/fivetran/proxy_agent/main/install.ps1 -OutFile install.ps1 -UseBasicParsing
   Unblock-File .\install.ps1
   $env:RUNTIME = 'docker'
   & .\install.ps1 C:\path\to\config.json
   

   The installer detects the legacy configuration format, uses your existing credentials to request a new configuration from Fivetran, and starts the Docker-based Proxy Agent. No manual changes to your configuration file are required.

3. Verify that the Proxy Agent is running:

   & "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" status
   

   The container should show as (healthy). You can also confirm that the Proxy Agent is online in the Fivetran dashboard. Go to Account Settings > Connection Methods > Proxy Agents.

Upgrade between Docker-based versions on Windows

To upgrade to the latest Docker-based version, run the following command:

& "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" upgrade

The upgrade command checks whether a newer version is available for your Windows Server version. If one is available, the command pulls the new image and restarts the container. If the new version fails to start, the Proxy Agent automatically restarts using the previous version.

To check the currently running version, run:

& "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" status

Roll back on Windows

Use the following procedures depending on whether you need to roll back a Docker version upgrade or return to a JAR-based installation.

Roll back a Docker-based version upgrade on Windows

To return to the version that was running before an upgrade, run the following commands. Replace <previous-image-tag> with the image tag you want to run. Windows image tags include the Windows Server variant. For example, 1.2.9-windows-ltsc2022.

Set-Content -LiteralPath "$env:USERPROFILE\fivetran-proxy-agent\version" -Value '<previous-image-tag>' -Encoding ascii
& "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" start

Roll back to JAR-based Proxy Agent on Windows

1. Stop the Docker container:

   & "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" stop
   

2. Restart the JAR-based Proxy Agent using your original configuration file, which was not modified during migration.

   • If you started the previous Proxy Agent manually, run:

     & 'C:\path\to\java.exe' -jar C:\path\to\proxyagent.jar C:\path\to\config.json
     

   • If the previous Proxy Agent was running as a Windows service, run the following commands in an elevated PowerShell session. Replace <service_name> with the name of the Proxy Agent service.

     Set-Service -Name '<service_name>' -StartupType Automatic
     Start-Service -Name '<service_name>'