Migrate in a Docker container

Before you begin

• Ensure you have:
  • Docker installed
  • Registry access for agent v3 images.
  • NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key).
• Plan a maintenance window and test this procedure in a non‑production environment first.

Do not run v2 and v3 concurrently

Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host.

Migrate

1. Pull the v3 image:

   Copy

   docker pull <registry>/nginx-plus/agentv3:debian

2. Run the container:

   Copy

   docker run -d \
     --restart=always \
     -e NGINX_LICENSE_JWT="<jwt>" \
     -e NGINX_AGENT_COMMAND_SERVER_HOST=agent.connect.nginx.com \
     -e NGINX_AGENT_COMMAND_SERVER_PORT=443 \
     -e NGINX_AGENT_COMMAND_AUTH_TOKEN="<data-plane-key>" \
     -e NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY=false \
     <registry>/nginx-plus/agentv3:debian

3. (Optional) Convert a mounted v2 config file to v3:

   Copy

   wget https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh
   chmod +x upgrade-agent-config.sh
   ./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=./nginx-agent-v3.conf

   • If you used Config Sync Groups in v2, add to the v3 config:
     • NGINX_AGENT_LABELS=config-sync-group=

Validate

• Check logs for a successful connection message:
  Copy

  docker logs <container>

  • Look for: msg="Agent connected"
• Verify the instance is Online in the NGINX One Console.

Rollback

• Stop/remove the v3 container and run the previous v2 image.

References

• Agent v3 environment variables:
• Docker images:
• Config conversion script: https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh