--- title: Upgrade hosts description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Fleet Automation --- # Upgrade hosts{% #upgrade-hosts %} Copy pageCopied {% tab title="v2" %} This endpoint is in Preview and may introduce breaking changes. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/). | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------------------- | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/unstable/fleet/deployments/upgrade | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/unstable/fleet/deployments/upgrade | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/unstable/fleet/deployments/upgrade | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/unstable/fleet/deployments/upgrade | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/unstable/fleet/deployments/upgrade | | app.datadoghq.com | POST https://api.datadoghq.com/api/unstable/fleet/deployments/upgrade | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/unstable/fleet/deployments/upgrade | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/unstable/fleet/deployments/upgrade | ### Overview 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 will: 1. Identify all hosts matching the filter query 1. Validate that the specified version is available 1. Begin rolling out the package upgrade to the 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. {% tab title="Model" %} | Parent field | Field | Type | Description | | --------------- | --------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | | data [*required*] | object | Data for creating a new package upgrade deployment. | | data | attributes [*required*] | object | Attributes for creating a new package upgrade deployment. | | attributes | filter_query | string | Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax. | | attributes | target_packages [*required*] | [object] | List of packages and their target versions to deploy to the selected hosts. | | target_packages | name [*required*] | string | The name of the package to deploy. | | target_packages | version [*required*] | string | The target version of the package to deploy. | | data | type [*required*] | enum | The type of deployment resource. Allowed enum values: `deployment` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "filter_query": "env:prod AND service:web", "target_packages": [ { "name": "datadog-agent", "version": "7.52.0" } ] }, "type": "deployment" } } ``` {% /tab %} ### Response {% tab title="201" %} CREATED {% tab title="Model" %} Response containing a single deployment. | Parent field | Field | Type | Description | | ----------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | data | object | A deployment that defines automated configuration changes for a fleet of hosts. | | data | attributes [*required*] | object | Attributes of a deployment in the response. | | attributes | config_operations | [object] | Ordered list of configuration file operations to perform on the target hosts. | | config_operations | file_op [*required*] | enum | Type of file operation to perform on the target configuration file. | | config_operations | file_path [*required*] | string | Absolute path to the target configuration file on the host. | | config_operations | 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. | | attributes | estimated_end_time_unix | int64 | Estimated completion time of the deployment as a Unix timestamp (seconds since epoch). | | attributes | filter_query | string | Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax. | | attributes | high_level_status | string | Current high-level status of the deployment (for example, "pending", "running", "completed", "failed"). | | attributes | hosts | [object] | Paginated list of hosts in this deployment with their individual statuses. Only included when fetching a single deployment by ID. Use the `limit` and `page` query parameters to navigate through pages. Pagination metadata is included in the response `meta.hosts` field. | | hosts | error | string | Error message if the deployment failed on this host. | | hosts | hostname | string | The hostname of the agent. | | hosts | status | string | Current deployment status for this specific host. | | hosts | versions | [object] | List of packages and their versions currently installed on this host. | | versions | current_version | string | The current version of the package on the host. | | versions | initial_version | string | The initial version of the package on the host before the deployment started. | | versions | package_name | string | The name of the package. | | versions | target_version | string | The target version that the deployment is attempting to install. | | attributes | packages | [object] | List of packages to deploy to target hosts. Present only for package upgrade deployments. | | packages | name [*required*] | string | The name of the package to deploy. | | packages | version [*required*] | string | The target version of the package to deploy. | | attributes | total_hosts | int64 | Total number of hosts targeted by this deployment. | | data | id [*required*] | string | Unique identifier for the deployment. | | data | type [*required*] | enum | The type of deployment resource. Allowed enum values: `deployment` | | | meta | object | Metadata for a single deployment response, including pagination information for hosts. | | meta | hosts | object | Pagination details for the list of hosts in a deployment. | | hosts | current_page | int64 | Current page index (zero-based). | | hosts | page_size | int64 | Number of hosts returned per page. | | hosts | total_hosts | int64 | Total number of hosts in this deployment. | | hosts | total_pages | int64 | Total number of pages available. | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "config_operations": [ { "file_op": "merge-patch", "file_path": "/datadog.yaml", "patch": { "apm_config": { "enabled": true }, "log_level": "debug", "logs_enabled": true } } ], "estimated_end_time_unix": 1699999999, "filter_query": "env:prod AND service:web", "high_level_status": "pending", "hosts": [ { "error": "", "hostname": "web-server-01.example.com", "status": "succeeded", "versions": [ { "current_version": "7.51.0", "initial_version": "7.51.0", "package_name": "datadog-agent", "target_version": "7.52.0" } ] } ], "packages": [ { "name": "datadog-agent", "version": "7.52.0" } ], "total_hosts": 42 }, "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001", "type": "deployment" }, "meta": { "hosts": { "current_page": 0, "page_size": 50, "total_hosts": 150, "total_pages": 3 } } } ``` {% /tab %} {% /tab %} {% tab title="400" %} Bad Request {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="401" %} Unauthorized {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="404" %} Not Found {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Curl command curl -X POST "https://api.datadoghq.com/api/unstable/fleet/deployments/upgrade" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "filter_query": "env:prod AND service:web", "target_packages": [ { "name": "datadog-agent", "version": "7.52.0" } ] }, "type": "deployment" } } EOF \## Upgrade Datadog Agent to version 7.52.0 # \# Curl command curl -X POST "https://api.datadoghq.com/api/unstable/fleet/deployments/upgrade" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "filter_query": "env:prod AND service:web", "target_packages": [ { "name": "datadog-agent", "version": "7.52.0" } ] }, "type": "deployment" } } EOF \## Upgrade multiple packages # \# Curl command curl -X POST "https://api.datadoghq.com/api/unstable/fleet/deployments/upgrade" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "filter_query": "env:staging", "target_packages": [ { "name": "datadog-agent", "version": "7.52.0-1" }, { "name": "datadog-apm-inject", "version": "0.10.0" } ] }, "type": "deployment" } } EOF ##### ```python """ Upgrade hosts returns "CREATED" response """ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.fleet_automation_api import FleetAutomationApi from datadog_api_client.v2.model.fleet_deployment_package import FleetDeploymentPackage from datadog_api_client.v2.model.fleet_deployment_package_upgrade_attributes import ( FleetDeploymentPackageUpgradeAttributes, ) from datadog_api_client.v2.model.fleet_deployment_package_upgrade_create import FleetDeploymentPackageUpgradeCreate from datadog_api_client.v2.model.fleet_deployment_package_upgrade_create_request import ( FleetDeploymentPackageUpgradeCreateRequest, ) from datadog_api_client.v2.model.fleet_deployment_resource_type import FleetDeploymentResourceType body = FleetDeploymentPackageUpgradeCreateRequest( data=FleetDeploymentPackageUpgradeCreate( attributes=FleetDeploymentPackageUpgradeAttributes( filter_query="env:prod AND service:web", target_packages=[ FleetDeploymentPackage( name="datadog-agent", version="7.52.0", ), ], ), type=FleetDeploymentResourceType.DEPLOYMENT, ), ) configuration = Configuration() configuration.unstable_operations["create_fleet_deployment_upgrade"] = True with ApiClient(configuration) as api_client: api_instance = FleetAutomationApi(api_client) response = api_instance.create_fleet_deployment_upgrade(body=body) print(response) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" python3 "example.py" ##### ```ruby # Upgrade hosts returns "CREATED" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.unstable_operations["v2.create_fleet_deployment_upgrade".to_sym] = true end api_instance = DatadogAPIClient::V2::FleetAutomationAPI.new body = DatadogAPIClient::V2::FleetDeploymentPackageUpgradeCreateRequest.new({ data: DatadogAPIClient::V2::FleetDeploymentPackageUpgradeCreate.new({ attributes: DatadogAPIClient::V2::FleetDeploymentPackageUpgradeAttributes.new({ filter_query: "env:prod AND service:web", target_packages: [ DatadogAPIClient::V2::FleetDeploymentPackage.new({ name: "datadog-agent", version: "7.52.0", }), ], }), type: DatadogAPIClient::V2::FleetDeploymentResourceType::DEPLOYMENT, }), }) p api_instance.create_fleet_deployment_upgrade(body) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" rb "example.rb" ##### ```go // Upgrade hosts returns "CREATED" response package main import ( "context" "encoding/json" "fmt" "os" "github.com/DataDog/datadog-api-client-go/v2/api/datadog" "github.com/DataDog/datadog-api-client-go/v2/api/datadogV2" ) func main() { body := datadogV2.FleetDeploymentPackageUpgradeCreateRequest{ Data: datadogV2.FleetDeploymentPackageUpgradeCreate{ Attributes: datadogV2.FleetDeploymentPackageUpgradeAttributes{ FilterQuery: datadog.PtrString("env:prod AND service:web"), TargetPackages: []datadogV2.FleetDeploymentPackage{ { Name: "datadog-agent", Version: "7.52.0", }, }, }, Type: datadogV2.FLEETDEPLOYMENTRESOURCETYPE_DEPLOYMENT, }, } ctx := datadog.NewDefaultContext(context.Background()) configuration := datadog.NewConfiguration() configuration.SetUnstableOperationEnabled("v2.CreateFleetDeploymentUpgrade", true) apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewFleetAutomationApi(apiClient) resp, r, err := api.CreateFleetDeploymentUpgrade(ctx, body) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `FleetAutomationApi.CreateFleetDeploymentUpgrade`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `FleetAutomationApi.CreateFleetDeploymentUpgrade`:\n%s\n", responseContent) } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" go run "main.go" ##### ```java // Upgrade hosts returns "CREATED" response import com.datadog.api.client.ApiClient; import com.datadog.api.client.ApiException; import com.datadog.api.client.v2.api.FleetAutomationApi; import com.datadog.api.client.v2.model.FleetDeploymentPackage; import com.datadog.api.client.v2.model.FleetDeploymentPackageUpgradeAttributes; import com.datadog.api.client.v2.model.FleetDeploymentPackageUpgradeCreate; import com.datadog.api.client.v2.model.FleetDeploymentPackageUpgradeCreateRequest; import com.datadog.api.client.v2.model.FleetDeploymentResourceType; import com.datadog.api.client.v2.model.FleetDeploymentResponse; import java.util.Collections; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setUnstableOperationEnabled("v2.createFleetDeploymentUpgrade", true); FleetAutomationApi apiInstance = new FleetAutomationApi(defaultClient); FleetDeploymentPackageUpgradeCreateRequest body = new FleetDeploymentPackageUpgradeCreateRequest() .data( new FleetDeploymentPackageUpgradeCreate() .attributes( new FleetDeploymentPackageUpgradeAttributes() .filterQuery("env:prod AND service:web") .targetPackages( Collections.singletonList( new FleetDeploymentPackage() .name("datadog-agent") .version("7.52.0")))) .type(FleetDeploymentResourceType.DEPLOYMENT)); try { FleetDeploymentResponse result = apiInstance.createFleetDeploymentUpgrade(body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling FleetAutomationApi#createFleetDeploymentUpgrade"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" java "Example.java" ##### ```rust // Upgrade hosts returns "CREATED" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_fleet_automation::FleetAutomationAPI; use datadog_api_client::datadogV2::model::FleetDeploymentPackage; use datadog_api_client::datadogV2::model::FleetDeploymentPackageUpgradeAttributes; use datadog_api_client::datadogV2::model::FleetDeploymentPackageUpgradeCreate; use datadog_api_client::datadogV2::model::FleetDeploymentPackageUpgradeCreateRequest; use datadog_api_client::datadogV2::model::FleetDeploymentResourceType; #[tokio::main] async fn main() { let body = FleetDeploymentPackageUpgradeCreateRequest::new(FleetDeploymentPackageUpgradeCreate::new( FleetDeploymentPackageUpgradeAttributes::new(vec![FleetDeploymentPackage::new( "datadog-agent".to_string(), "7.52.0".to_string(), )]) .filter_query("env:prod AND service:web".to_string()), FleetDeploymentResourceType::DEPLOYMENT, )); let mut configuration = datadog::Configuration::new(); configuration.set_unstable_operation_enabled("v2.CreateFleetDeploymentUpgrade", true); let api = FleetAutomationAPI::with_config(configuration); let resp = api.create_fleet_deployment_upgrade(body).await; if let Ok(value) = resp { println!("{:#?}", value); } else { println!("{:#?}", resp.unwrap_err()); } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ##### ```typescript /** * Upgrade hosts returns "CREATED" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration(); configuration.unstableOperations["v2.createFleetDeploymentUpgrade"] = true; const apiInstance = new v2.FleetAutomationApi(configuration); const params: v2.FleetAutomationApiCreateFleetDeploymentUpgradeRequest = { body: { data: { attributes: { filterQuery: "env:prod AND service:web", targetPackages: [ { name: "datadog-agent", version: "7.52.0", }, ], }, type: "deployment", }, }, }; apiInstance .createFleetDeploymentUpgrade(params) .then((data: v2.FleetDeploymentResponse) => { console.log( "API called successfully. Returned data: " + JSON.stringify(data) ); }) .catch((error: any) => console.error(error)); ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" tsc "example.ts" {% /tab %}