Upgrade hosts

This endpoint is in Preview and may introduce breaking changes. If you have any feedback, contact Datadog support.

POST https://api.ap1.datadoghq.com/api/unstable/fleet/deployments/upgradehttps://api.ap2.datadoghq.com/api/unstable/fleet/deployments/upgradehttps://api.datadoghq.eu/api/unstable/fleet/deployments/upgradehttps://api.ddog-gov.com/api/unstable/fleet/deployments/upgradehttps://api.us2.ddog-gov.com/api/unstable/fleet/deployments/upgradehttps://api.datadoghq.com/api/unstable/fleet/deployments/upgradehttps://api.us3.datadoghq.com/api/unstable/fleet/deployments/upgradehttps://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
  2. Validate that the specified version is available
  3. 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.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    Data for creating a new package upgrade deployment.

    attributes [required]

    object

    Attributes for creating a new package upgrade deployment.

    filter_query

    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"
      }
    }

    Response

    CREATED

    Response containing a single deployment.

    Expand All

    Field

    Type

    Description

    data

    object

    A deployment that defines automated configuration changes for a fleet of hosts.

    attributes [required]

    object

    Attributes of a deployment in the response.

    config_operations

    [object]

    Ordered list of configuration file operations to perform on the target hosts.

    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.

    estimated_end_time_unix

    int64

    Estimated completion time of the deployment as a Unix timestamp (seconds since epoch).

    filter_query

    string

    Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax.

    high_level_status

    string

    Current high-level status of the deployment (for example, "pending", "running", "completed", "failed").

    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.

    error

    string

    Error message if the deployment failed on this host.

    hostname

    string

    The hostname of the agent.

    status

    string

    Current deployment status for this specific host.

    versions

    [object]

    List of packages and their versions currently installed on this host.

    current_version

    string

    The current version of the package on the host.

    initial_version

    string

    The initial version of the package on the host before the deployment started.

    package_name

    string

    The name of the package.

    target_version

    string

    The target version that the deployment is attempting to install.

    packages

    [object]

    List of packages to deploy to target hosts. Present only for package upgrade deployments.

    name [required]

    string

    The name of the package to deploy.

    version [required]

    string

    The target version of the package to deploy.

    total_hosts

    int64

    Total number of hosts targeted by this deployment.

    id [required]

    string

    Unique identifier for the deployment.

    type [required]

    enum

    The type of deployment resource. Allowed enum values: deployment

    default: deployment

    meta

    object

    Metadata for a single deployment response, including pagination information for hosts.

    hosts

    object

    Pagination details for the list of hosts in a deployment.

    current_page

    int64

    Current page index (zero-based).

    page_size

    int64

    Number of hosts returned per page.

    total_hosts

    int64

    Total number of hosts in this deployment.

    total_pages

    int64

    Total number of pages available.

    {
      "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
        }
      }
    }

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Unauthorized

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Code Example

                      ## default
    # 
    
    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.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.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.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.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.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
    """
    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 and then save the example to example.py and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
    # 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 and then save the example to example.rb and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
    // 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 and then save the example to main.go and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
    // 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 and then save the example to Example.java and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
    // 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 and then save the example to src/main.rs and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.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";
    
    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 and then save the example to example.ts and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"