Overview

Remote Agent Management simplifies the process of upgrading your Agent fleet by reducing the need to coordinate with multiple deployment or configuration management tools. Remote Agent Management gives you access to:

• Centralized Management - Upgrade Agents across all environments with a single tool, ensuring consistency with the latest features and security patches.
• Visibility and Monitoring - Track the status of upgrades in real-time, allowing quick verification of deployment success.
• Operational Efficiency - Streamline the upgrade process by eliminating cross-team coordination and unifying deployment across different platforms.

Prerequisites

Supported platforms

• Linux VMs installed using the install script or Ansible Datadog Role
• Windows VMs

Remotely upgrading Agents in containerized environments is not supported.

Permissions

Users must have the Agent Upgrade within Fleet Automation for upgrades, and the Fleet Policies Write permissions to configure Agents remotely. The permission is enabled by default on the Datadog Admin role.

Enable Remote Agent Management

To enable Remote Agent Management:

1. Ensure that Remote Configuration is enabled for your organization.

2. Go to the Datadog Agent install page for your platform or configuration management tool.

3. Enable Remote Agent Management. Enabling Remote Agent Management adds the DD_REMOTE_UPDATES environment variable to the generated Agent installation command.

4. Use the generated Agent installation command to upgrade your Agent to version 7.66+.

Upgrade Agents remotely

Prerequisites

• Disk space: Datadog suggests at least 2GB for the initial Agent install and an additional 2GB for upgrading the Agent from Fleet Automation. Specifically, the upgrade requires 1.3GB in the /opt/datadog-packages directory on Linux, or C:\ProgramData\Datadog\Installer\packages on Windows. The extra space ensures that there is enough room to maintain two Agent installs temporarily during the upgrade process in case a rollback is needed.

How to upgrade Agents remotely

To upgrade your Agents remotely:

1. Enable Remote Agent Management.

2. From the Upgrade Agents tab, click Start Agents Upgrade.

3. Select the Agents you want to upgrade. You can target a group of Agents by filtering on host information or tags.

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

5. Use the Deployments dashboard to track the upgrade process. Clicking on an Agent in the deployments table gives you more information about the upgrade, including the duration time, progress, and the user who started the upgrade.

Upgrade process

Similar to a manual upgrade, expect a downtime of 5-30 seconds while the Agent restarts. The full upgrade process takes approximately 5 minutes. Around 2 minutes of this time is used for the upgrade process. The rest of the time is spent monitoring the upgrade to ensure stability and determining if a rollback is necessary. If the upgrade fails and a rollback is necessary, the Agent automatically reverts to the previously running Agent 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 ensures that the appropriate permissions are set for these files. No configuration files are altered during the installation process.

Upgrade precedence

For the most consistent upgrade experience, Datadog recommends managing upgrades from one source at a time. Use either Fleet Automation or a configuration management tool. If you run a configuration management tool on an Agent that has already been upgraded using Fleet Automation, the upgrade reverts the Agent to the DD_AGENT_MINOR_VERSION specified in your configuration. If no DD_AGENT_MINOR_VERSION is set, the Agent is upgraded to the latest available version.

Configure Agents

1. In Fleet Automation, open the Configure Agents tab and click Create Configuration.

2. Select and configure the products (for example, APM, Logs, NDM) that you want the target Agents to run.

3. Review and name your final configuration and begin scoping deployment to your Agents. Alternatively, you can save the configuration to edit or deploy to your Agents at a later time from the Configure Agents page.

4. Scope Agents to deploy configuration to (for example through tags such as host names, site, or environment).

5. Review the deployment plan to confirm scoped Agents and deployment settings, such as rollout concurrency.

6. Start deployment and track progress from the Deployments page.

Configuration precedence

When a configuration file on the host conflicts with a Fleet Automation configuration, Fleet Automation takes precedence, ensuring a single source of truth. See Configuration Order Precedence.

Edit, deploy or roll back configurations

From your list of configurations in the Configure Agents tab, you can

• Deploy the unused configuration to your Agents
• Edit the configuration, save a new version, and redeploy the updated configuration.
• Rollback the configuration to a previous version and redeploy.

Mirrors and proxies

You can use Remote Agent Management along with a proxy or mirrored repositories.

For instructions on configuring your Agent to use a proxy, see Agent Proxy Configuration. After you’ve configured the proxy, restart the Agent to apply the settings.

For instructions on using mirrored or air-gapped repositories, see:

• Synchronize Datadog’s images with a private container registry
• Installing the Agent on a server with limited internet connectivity

Downgrade Agents

If you need to downgrade an Agent, follow the steps in Upgrade your Agents and specify the version you wish to downgrade to. Datadog recommends using the latest version of the Agent and upgrading your Agents regularly to make sure you have access to the latest features.

Troubleshooting

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.

To support general availability of remote Agent upgrades, the installer component was bundled with the Agent starting in version 7.66. This change ensures that both components stay up to date together, preventing version mismatches and related compatibility issues. Earlier versions of the Agent did not bundle these components, resulting in a possible version mismatch that could prevent automatic updates and remote Agent Management functionality.

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 manually upgrade them to Agent version 7.66 or higher. This ensures full compatibility with Remote Agent Management features.

Manual Agent upgrades are not required after you’ve updated to 7.66 or higher. Future upgrades are handled automatically without requiring manual intervention.

If you don’t upgrade an earlier Agent version to 7.66 or higher, there is no impact on your existing Agent. However, remote upgrades remain unavailable until you update the Agent.

Uninstall Remote Agent Management

Further reading

Documentation, liens et articles supplémentaires utiles:

Fleet AutomationDOCUMENTATION Remote ConfigurationDOCUMENTATION