Create and immediately start a new package upgrade
on hosts matching the specified filter query.
This endpoint allows you to upgrade the Datadog Agent to a specific version
on hosts matching the specified filter query.
The deployment is created and started automatically. The system:
Identifies all hosts matching the filter query.
Validates that the specified version is available.
Begins rolling out the package upgrade to the target hosts.
Returns a 400 if filter_query or target_packages is missing, a target package is missing a name or version, or the filter query does not match any host eligible for the upgrade. Returns a 409 if a conflicting upgrade is already running on one or more target hosts.
This endpoint requires
all
of the following permissions:
agent_upgrade_write
fleet_policies_write
Request
Body Data (required)
Request payload containing the package upgrade details.
Data for creating a new v2 package upgrade deployment.
attributes [required]
object
Attributes for creating a new v2 package upgrade deployment.
filter_query [required]
string
Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax.
target_packages [required]
[object]
List of packages and their target versions to deploy to the selected hosts.
name [required]
string
The name of the package to deploy.
version [required]
string
The target version of the package to deploy.
type [required]
enum
The type of deployment resource.
Allowed enum values: deployment
default: deployment
{"data":{"attributes":{"filter_query":"env:prod AND service:web","target_packages":[{"name":"datadog-agent","version":"7.52.0"}]},"type":"deployment"}}
Attributes of a deployment in the v2 API response.
author
string
Handle of the user who triggered the deployment.
config_operations
[object]
Ordered list of configuration file operations applied by this deployment.
Absent for package deployments, which have no configuration file operations.
file_op [required]
enum
Type of file operation to perform on the target configuration file.
merge-patch: Merges the provided patch data with the existing configuration file.
Creates the file if it doesn't exist.
delete: Removes the specified configuration file from the target hosts.
Allowed enum values: merge-patch,delete
file_path [required]
string
Absolute path to the target configuration file on the host.
patch
object
Patch data in JSON format to apply to the configuration file.
When using merge-patch, this object is merged with the existing configuration,
allowing you to add, update, or override specific fields without replacing the entire file.
The structure must match the target configuration file format (for example, YAML structure
for Datadog Agent config). Not applicable when using the delete operation.
duration_seconds
int64
Duration of the deployment in seconds, computed as finished_at - started_at.
Zero if the deployment has not finished.
error_summary
string
Top-level error message for the deployment. Populated only when the deployment has failed.
estimated_finished_at
int64
Estimated completion time of the deployment as a Unix timestamp. Zero if not available.
finished_at
int64
Time the deployment finished as a Unix timestamp. Zero if not yet finished.
is_scheduled
boolean
Whether this deployment was triggered by a schedule (schedule_id is non-empty).
query
string
Query used to filter and select target hosts for the deployment.
schedule_id
string
Identifier of the schedule that triggered this deployment. Empty if triggered manually.
started_at
int64
Time the deployment started as a Unix timestamp. Zero if not yet started.
status
string
Current high-level status of the deployment (for example, "pending", "running",
"completed", "failed").
target_versions
[string]
Package versions targeted by this deployment.
total_hosts
int64
Total number of hosts targeted by this deployment.
update_type
string
Type of update operation performed by this deployment
(for example, "update_config_operations", "update_package").
id [required]
string
Unique identifier for the deployment.
type [required]
enum
The type of deployment resource.
Allowed enum values: deployment
default: deployment
{"data":{"attributes":{"author":"alice@datadoghq.com","config_operations":[{"file_op":"merge-patch","file_path":"/datadog.yaml","patch":{"apm_config":{"enabled":true},"log_level":"debug","logs_enabled":true}}],"duration_seconds":1000,"error_summary":"A host failed to update","estimated_finished_at":1699999999,"finished_at":0,"is_scheduled":true,"query":"env:prod AND service:web","schedule_id":"sched-123","started_at":1699990000,"status":"pending","target_versions":["7.52.0"],"total_hosts":42,"update_type":"update_config_operations"},"id":"k7Q-3mX-p9Z","type":"deployment"}}
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_API_KEY="<DD_API_KEY>"DD_APP_KEY="<DD_APP_KEY>"cargo run
/**
* Upgrade hosts returns "CREATED" response
*/import{client,v2}from"@datadog/datadog-api-client";constconfiguration=client.createConfiguration();constapiInstance=newv2.FleetAutomationApi(configuration);constparams: v2.FleetAutomationApiCreateFleetDeploymentUpgradeV2Request={body:{data:{attributes:{filterQuery:"env:prod AND service:example-fleet-automation",targetPackages:[{name:"datadog-agent",version:"7.52.0",},],},type:"deployment",},},};apiInstance.createFleetDeploymentUpgradeV2(params).then((data: v2.FleetDeploymentV2CreateResponse)=>{console.log("API called successfully. Returned data: "+JSON.stringify(data));}).catch((error: any)=>console.error(error));