--- title: Upgrade Agents description: Remotely upgrade Datadog Agents using Fleet Automation. breadcrumbs: Docs > Agent > Fleet Automation > Upgrade Agents --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Upgrade Agents 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 Terraform or the API. ## Prerequisites{% #prerequisites %} {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="info" %} On US1-FED and US2-FED, remote upgrades require Agent 7.85.0 or later on both Linux and Windows. If you run an older version, use the [Agent installation instructions](https://app.datadoghq.com/fleet/install-agent/latest?platform=overview) to update it before upgrading through Fleet Automation. {% /alert %} {% /callout %} - [Remote Configuration](https://docs.datadoghq.com/agent/guide/setup_remote_config.md) enabled for your organization and the Agent's API key - [Remote updates](https://docs.datadoghq.com/agent/guide/setup_remote_config.md#enable-remote-agent-management) enabled on each target VM Agent (`remote_updates: true`) - Agent version 7.71.1 or later for Windows and 7.69.0 or later for Linux - 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.) {% alert level="info" %} Remote upgrading of Agents in containerized workloads is not supported. {% /alert %} ## Upgrade Agents immediately{% #upgrade-agents-immediately %} 1. From the [Upgrades](https://app.datadoghq.com/fleet/agent-upgrades) tab, click Upgrade Now. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/upgrade-screen2.6ae4c20285dcf62bf47d7aa48d5990fc.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/upgrade-screen2.6ae4c20285dcf62bf47d7aa48d5990fc.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The Upgrades tab with the Upgrade Now button." /%} 1. Select the Agents to upgrade. Filter by host information or tags to target a specific group. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/start-agent-upgrade.951ffb8a482f1d30b6bca14665599896.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/start-agent-upgrade.951ffb8a482f1d30b6bca14665599896.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Agent selection screen with filtering options to narrow the list of Agents to upgrade." /%} 1. Review the deployment plan and click Upgrade Agents to start the upgrade. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/agent-upgrades-staged.6c0e26083bd11aaf370603e9e5954afc.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/agent-upgrades-staged.6c0e26083bd11aaf370603e9e5954afc.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Deployment plan view showing the list of Agents staged for upgrade." /%} 1. Track progress on the [Deployments](https://app.datadoghq.com/fleet/deployments) dashboard. Click an Agent in the deployments table to view duration, progress, and the user who initiated the upgrade. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/deployments.09f83298855bfed95752a07b4a0b8fa9.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/deployments.09f83298855bfed95752a07b4a0b8fa9.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Deployments dashboard showing upgrade progress and details for each Agent." /%} ## Schedule Agent upgrades{% #schedule-agent-upgrades %} 1. From the [Upgrades tab](https://app.datadoghq.com/fleet/agent-upgrades), click + Create Schedule. 1. On the Upgrade Schedule page, add a Schedule name. 1. Select the Agent version. You can upgrade to the latest version, one version behind, or two versions behind. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_select_version1.fd30cc8d8c0eab3112cec7481f09cc97.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_select_version1.fd30cc8d8c0eab3112cec7481f09cc97.png?auto=format&fit=max&w=850&dpr=2 2x" alt="See a list of scheduled Agent upgrades." /%} 1. Specify the Agents to upgrade. Filter by host information or tags to target a specific group. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_select_agents.3367dde143dbaaebff71f319ec945554.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_select_agents.3367dde143dbaaebff71f319ec945554.png?auto=format&fit=max&w=850&dpr=2 2x" alt="See a list of Agents to be upgraded." /%} 1. Set the deployment window for these upgrades. You can select the days, time frame, and timezone for the upgrade. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_set_window.78091ae7b77f6fc121a320d4332295fd.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_set_window.78091ae7b77f6fc121a320d4332295fd.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Select the time frame for your Agent upgrades." /%} 1. Set up notifications for deployment status updates. Notify your team through services connected to Datadog, such as Slack, Teams, or PagerDuty. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_set_notification.1bc802f564519756331c4a0540bbd0e1.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_set_notification.1bc802f564519756331c4a0540bbd0e1.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Select people or channels to be notified about the progress of the upgrade." /%} 1. Click Create Schedule to save the schedule. 1. See a list of your scheduled upgrades under the [Upgrades tab](https://app.datadoghq.com/fleet/agent-upgrades), in the Upgrade Schedules section. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_schedule_list3.09883c2cadcc374a42bc3cc25199e210.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/agent_upgrade_schedule_list3.09883c2cadcc374a42bc3cc25199e210.png?auto=format&fit=max&w=850&dpr=2 2x" alt="See a list of upgrades scheduled for your Agents." /%} ## Upgrade Agents with the API{% #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](https://docs.datadoghq.com/api/latest/fleet-automation.md). ## Schedule Agent upgrades with Terraform{% #schedule-agent-upgrades-with-terraform %} Use the Datadog Terraform provider to create and manage Agent upgrade schedules as code. The `datadog_fleet_schedule` resource defines the target hosts, Agent version, and recurring maintenance window. Fleet Automation performs the upgrades according to the schedule. Before you begin: - Verify that the Agents meet the upgrade prerequisites. - [Set up the Datadog Terraform provider](https://docs.datadoghq.com/getting_started/integrations/terraform.md) (version 4.22.0 or later). - Use an application key with the `agent_upgrade_write` and `hosts_read` permissions. The following example defines an inactive schedule for hosts matching `env:staging service:example`. The schedule targets the latest Agent version (`version_to_latest = 0`). It specifies a two-hour maintenance window (`maintenance_window_duration = 120`, in minutes), starting at 03:00 on Tuesdays and Thursdays in the `America/New_York` time zone. ```hcl resource "datadog_fleet_schedule" "staging" { name = "Staging Agent upgrades" query = "env:staging service:example" status = "inactive" version_to_latest = 0 rule = { days_of_week = ["Tue", "Thu"] maintenance_window_duration = 120 start_maintenance_window = "03:00" timezone = "America/New_York" } } ``` Replace the host query and maintenance window with values for your environment. Run `terraform plan` to review the changes, then `terraform apply` to create the schedule. When you are ready to enable scheduled upgrades, set `status` to `active` and apply the change. For all supported options and instructions for importing an existing schedule, see the [`datadog_fleet_schedule` resource documentation](https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/fleet_schedule). ## Upgrade process{% #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{% #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`](https://github.com/DataDog/agent-linux-install-script?tab=readme-ov-file#install-script-configuration-options) in your configuration. If no `DD_AGENT_MINOR_VERSION` is set, the Agent upgrades to the latest available version. ## Troubleshooting{% #troubleshooting %} ### Remote Agent Management is not enabled{% #remote-agent-management-is-not-enabled %} If the Agent's side panel shows **Remote Agent Management: NOT ENABLED**, follow [Enable remote Agent management](https://docs.datadoghq.com/agent/guide/setup_remote_config.md#enable-remote-agent-management) to enable `remote_updates` on the host and restart the Agent. Remote Configuration can be connected while remote updates are disabled. If the Agent is still unavailable for upgrades, verify the prerequisites, Remote Configuration connectivity, and whether the Datadog Installer is running. ### Newly released Agent version is not yet available for upgrade{% #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){% #datadog-installer-incompatible-with-agent-pre-766 %} 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](https://app.datadoghq.com/fleet?query=support_remote_upgrade%3Adatadog-installer) to identify affected hosts: ```txt support_remote_upgrade:datadog-installer ``` 1. If your setup is impacted, [re-run the install script](https://app.datadoghq.com/fleet/install-agent/latest?platform=overview) on each affected Agent to upgrade to an Agent version that meets the prerequisites. After updating, [enable remote Agent management](https://docs.datadoghq.com/agent/guide/setup_remote_config.md#enable-remote-agent-management) to use Fleet Automation for future upgrades. If you do not upgrade, the existing Agent continues to function, but remote upgrades remain unavailable. ## Further Reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Fleet Automation](https://docs.datadoghq.com/agent/fleet_automation.md) - [Fleet Automation API](https://docs.datadoghq.com/api/latest/fleet-automation.md)