For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/agent/fleet_automation/upgrade_agents.md. A documentation index is available at /llms.txt.

Upgrade Agents

This product is not supported for your selected Datadog site. ().

Fleet Automation allows you to remotely upgrade Datadog Agents across your fleet without direct access to individual hosts. You can trigger upgrades immediately, schedule them during maintenance windows, or automate them through the API.

Prerequisites

  • Remote Configuration enabled for your organization
  • Agent version 7.66 or later
  • Linux VMs or Windows VMs
  • At least 2 GB disk space for the initial Agent install, plus an additional 2 GB for upgrades. (The upgrade requires 1.3 GB in /opt/datadog-packages on Linux, or C:\ProgramData\Datadog\Installer\packages on Windows. The additional space maintains two Agent installs temporarily during the upgrade in case a rollback is needed.)
Remote upgrading of Agents in containerized workloads is not supported.

Upgrade Agents immediately

  1. From the Upgrades tab, click Upgrade Now.

    The Upgrades tab with the Upgrade Now button.

  2. Select the Agents to upgrade. Filter by host information or tags to target a specific group.

    Agent selection screen with filtering options to narrow the list of Agents to upgrade.

  3. Review the deployment plan and click Upgrade Agents to start the upgrade.

    Deployment plan view showing the list of Agents staged for upgrade.

  4. Track progress on the Deployments dashboard. Click an Agent in the deployments table to view duration, progress, and the user who initiated the upgrade.

    Deployments dashboard showing upgrade progress and details for each Agent.

Schedule Agent upgrades

  1. From the Upgrades tab, click + Create Schedule.

  2. On the Upgrade Schedule page, add a Schedule name.

  3. Select the Agent version. You can upgrade to the latest version, one version behind, or two versions behind.

    See a list of scheduled Agent upgrades.

  4. Specify the Agents to upgrade. Filter by host information or tags to target a specific group.

    See a list of Agents to be upgraded.

  5. Set the deployment window for these upgrades. You can select the days, time frame, and timezone for the upgrade.

    Select the time frame for your Agent upgrades.

  6. Set up notifications for deployment status updates. Notify your team through services connected to Datadog, such as Slack, Teams, or PagerDuty.

    Select people or channels to be notified about the progress of the upgrade.

  7. Click Create Schedule to save the schedule.

  8. See a list of your scheduled upgrades under the Upgrades tab, in the Upgrade Schedules section.

    See a list of upgrades scheduled for your Agents.

Upgrade Agents with the API

Fleet Automation provides an API to trigger Agent upgrades programmatically or on a recurring schedule. Start upgrades for any set of hosts with filter queries, or create schedules that run during defined maintenance windows with a specified Agent version. For full details, see the Fleet Automation API.

Upgrade process

Similar to a manual upgrade, expect 5-30 seconds of downtime while the Agent restarts. The full upgrade process takes approximately 5 minutes: around 2 minutes for the upgrade itself, with the remaining time spent monitoring stability. If the upgrade fails, the Agent automatically reverts to the previous version.

The upgrade process primarily adds files to the following directories:

Linux:

  • /opt/datadog-packages
  • /etc/datadog-agent
  • /etc/systemd/system

Windows:

  • C:\ProgramData\Datadog\Installer\packages
  • C:\Program Files\Datadog\Datadog Agent

The Agent sets the appropriate permissions for these files. No configuration files are altered during the upgrade.

Upgrade precedence

Datadog recommends managing upgrades from one source at a time. Use either Fleet Automation or a configuration management tool, not both. If you run a configuration management tool on an Agent that was upgraded through Fleet Automation, the tool reverts the Agent to the DD_AGENT_MINOR_VERSION in your configuration. If no DD_AGENT_MINOR_VERSION is set, the Agent upgrades to the latest available version.

Troubleshooting

Newly released Agent version is not yet available for upgrade

After a new Agent version is released, it can take up to 24 hours before it appears as an upgrade target in Fleet Automation. If a recently released version is missing from the upgrade picker, wait up to 24 hours and retry.

Datadog Installer incompatible with Agent (pre-7.66)

If you were a Preview customer and set up remote Agent Management before Agent version 7.66, your Datadog Installer might be incompatible with the Agent.

Starting in version 7.66, the installer component is bundled with the Agent. This keeps both components in-sync and prevents version mismatches that can block remote management. Earlier Agent versions did not bundle the installer, which can cause compatibility issues.

To diagnose and fix the issue:

  1. Use the following query in Fleet Automation to identify affected hosts:
    support_remote_upgrade:datadog-installer
  2. If your setup is impacted, re-run the install script on each affected Agent to upgrade to Agent 7.66 or later.

After updating to 7.66 or later, future upgrades are handled automatically. If you do not upgrade, the existing Agent continues to function, but remote upgrades remain unavailable.

Further Reading

Additional helpful documentation, links, and articles:

Fleet AutomationDOCUMENTATION more more Fleet Automation APIDOCUMENTATION more more