Create a configuration deployment

POST https://api.ap1.datadoghq.com/api/v2/fleet/deployments/configurehttps://api.ap2.datadoghq.com/api/v2/fleet/deployments/configurehttps://api.datadoghq.eu/api/v2/fleet/deployments/configurehttps://api.ddog-gov.com/api/v2/fleet/deployments/configurehttps://api.us2.ddog-gov.com/api/v2/fleet/deployments/configurehttps://api.uk1.datadoghq.com/api/v2/fleet/deployments/configurehttps://api.datadoghq.com/api/v2/fleet/deployments/configurehttps://api.us3.datadoghq.com/api/v2/fleet/deployments/configurehttps://api.us5.datadoghq.com/api/v2/fleet/deployments/configure

개요

Create a new deployment to apply configuration changes to a fleet of hosts matching the specified filter query.

This endpoint supports two types of configuration operations:

  • merge-patch: Merges the provided patch data with the existing configuration file, creating the file if it doesn’t exist.
  • delete: Removes the specified configuration file from the target hosts.

You can optionally use target_packages to apply the configuration change only to specific package versions.

The deployment is created and started automatically. You can specify multiple configuration operations to execute in order on each target host. Use the filter query to target specific hosts using the Datadog query syntax.

Set dry_run to true to validate the configuration and resolve target hosts and packages without deploying anything. A dry run returns a 200 with the validation result instead of creating and starting a deployment.

Returns a 400 if filter_query or config_operations is missing, a target package is missing a name or version or cannot be resolved, the configuration fails validation, or the filter query does not match any host eligible for the deployment.

This endpoint requires all of the following permissions:
  • agent_upgrade_write
  • fleet_policies_write

  • 요청

    Body Data (required)

    Request payload containing the deployment details.

    Expand All

    항목

    유형

    설명

    data [required]

    object

    Data for creating a new v2 configuration deployment.

    attributes [required]

    object

    Attributes for creating a new v2 configuration deployment.

    config_operations [required]

    [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.

    dry_run

    boolean

    Set to true to validate the configuration and resolve target hosts and packages without deploying anything. Returns a 200 with the validation result instead of creating and starting a real deployment.

    filter_query [required]

    string

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

    target_packages

    [object]

    List of packages and their target versions to additionally deploy alongside the configuration change.

    apm_instrumentation

    string

    APM auto-instrumentation mode to enable for this package, if applicable.

    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": {
          "config_operations": [
            {
              "file_op": "merge-patch",
              "file_path": "/datadog.yaml",
              "patch": {
                "apm_config": {
                  "enabled": true
                },
                "log_level": "debug",
                "logs_enabled": true
              }
            }
          ],
          "dry_run": false,
          "filter_query": "env:prod AND service:web",
          "target_packages": [
            {
              "apm_instrumentation": "host",
              "name": "datadog-agent",
              "version": "7.52.0"
            }
          ]
        },
        "type": "deployment"
      }
    }

    응답

    OK

    Response containing the result of a configuration deployment dry run.

    Expand All

    항목

    유형

    설명

    data [required]

    object

    The result of a configuration deployment dry run.

    attributes [required]

    object

    Attributes of a configuration deployment dry-run response.

    dry_run

    object

    Validation result of a configuration deployment dry run.

    config_validated

    boolean

    Whether the configuration passed schema validation.

    non_upgradable_by_reason

    object

    Breakdown of ineligible host counts by reason. Only includes reasons with a non-zero count. Absent from the response when no targeted host is ineligible.

    <any-key>

    int64

    non_upgradable_hosts

    int64

    Number of targeted hosts that are not eligible to receive this configuration.

    query

    string

    Query used to filter and select target hosts for the deployment.

    total_hosts

    int64

    Total number of hosts targeted by this deployment.

    id [required]

    string

    Always "dry-run" for a dry-run response. Does not identify a real deployment and cannot be used to fetch a deployment by ID.

    type [required]

    enum

    The type of deployment resource. Allowed enum values: deployment

    default: deployment

    {
      "data": {
        "attributes": {
          "dry_run": {
            "config_validated": true,
            "non_upgradable_by_reason": {
              "<any-key>": "integer"
            },
            "non_upgradable_hosts": 0
          },
          "query": "env:prod AND service:web",
          "total_hosts": 42
        },
        "id": "dry-run",
        "type": "deployment"
      }
    }

    CREATED

    Response containing the newly created deployment.

    Expand All

    항목

    유형

    설명

    data [required]

    object

    A deployment in the v2 API response.

    attributes [required]

    object

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

    Bad Request

    API error response.

    Expand All

    항목

    유형

    설명

    errors [required]

    [string]

    A list of errors.

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

    Unauthorized

    API error response.

    Expand All

    항목

    유형

    설명

    errors [required]

    [string]

    A list of errors.

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

    Forbidden

    API error response.

    Expand All

    항목

    유형

    설명

    errors [required]

    [string]

    A list of errors.

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

    Too many requests

    API error response.

    Expand All

    항목

    유형

    설명

    errors [required]

    [string]

    A list of errors.

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

    코드 사례

                      ## 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.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/fleet/deployments/configure" \ -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": { "config_operations": [ { "file_op": "merge-patch", "file_path": "/datadog.yaml", "patch": { "apm_config": { "enabled": true }, "log_level": "info", "logs_enabled": true } } ], "filter_query": "env:prod AND datacenter:us-east-1" }, "type": "deployment" } } EOF
    ## Dry run #
    # 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.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/fleet/deployments/configure" \ -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": { "config_operations": [ { "file_op": "merge-patch", "file_path": "/datadog.yaml", "patch": { "log_level": "info" } } ], "dry_run": true, "filter_query": "env:prod AND datacenter:us-east-1" }, "type": "deployment" } } EOF
    """
    Create a configuration deployment returns "OK" 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_configure_v2_attributes import FleetDeploymentConfigureV2Attributes
    from datadog_api_client.v2.model.fleet_deployment_configure_v2_create import FleetDeploymentConfigureV2Create
    from datadog_api_client.v2.model.fleet_deployment_configure_v2_create_request import (
        FleetDeploymentConfigureV2CreateRequest,
    )
    from datadog_api_client.v2.model.fleet_deployment_file_op import FleetDeploymentFileOp
    from datadog_api_client.v2.model.fleet_deployment_operation import FleetDeploymentOperation
    from datadog_api_client.v2.model.fleet_deployment_resource_type import FleetDeploymentResourceType
    
    body = FleetDeploymentConfigureV2CreateRequest(
        data=FleetDeploymentConfigureV2Create(
            attributes=FleetDeploymentConfigureV2Attributes(
                config_operations=[
                    FleetDeploymentOperation(
                        file_op=FleetDeploymentFileOp.MERGE_PATCH,
                        file_path="/datadog.yaml",
                        patch=dict([("log_level", "info")]),
                    ),
                ],
                dry_run=True,
                filter_query="env:prod AND service:example-fleet-automation",
            ),
            type=FleetDeploymentResourceType.DEPLOYMENT,
        ),
    )
    
    configuration = Configuration()
    with ApiClient(configuration) as api_client:
        api_instance = FleetAutomationApi(api_client)
        response = api_instance.create_fleet_deployment_configure_v2(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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
    # Create a configuration deployment returns "OK" response
    
    require "datadog_api_client"
    api_instance = DatadogAPIClient::V2::FleetAutomationAPI.new
    
    body = DatadogAPIClient::V2::FleetDeploymentConfigureV2CreateRequest.new({
      data: DatadogAPIClient::V2::FleetDeploymentConfigureV2Create.new({
        attributes: DatadogAPIClient::V2::FleetDeploymentConfigureV2Attributes.new({
          config_operations: [
            DatadogAPIClient::V2::FleetDeploymentOperation.new({
              file_op: DatadogAPIClient::V2::FleetDeploymentFileOp::MERGE_PATCH,
              file_path: "/datadog.yaml",
              patch: {
                "log_level": "info",
              },
            }),
          ],
          dry_run: true,
          filter_query: "env:prod AND service:example-fleet-automation",
        }),
        type: DatadogAPIClient::V2::FleetDeploymentResourceType::DEPLOYMENT,
      }),
    })
    p api_instance.create_fleet_deployment_configure_v2(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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
    // Create a configuration deployment returns "OK" 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.FleetDeploymentConfigureV2CreateRequest{
    		Data: datadogV2.FleetDeploymentConfigureV2Create{
    			Attributes: datadogV2.FleetDeploymentConfigureV2Attributes{
    				ConfigOperations: []datadogV2.FleetDeploymentOperation{
    					{
    						FileOp:   datadogV2.FLEETDEPLOYMENTFILEOP_MERGE_PATCH,
    						FilePath: "/datadog.yaml",
    						Patch: map[string]interface{}{
    							"log_level": "info",
    						},
    					},
    				},
    				DryRun:      datadog.PtrBool(true),
    				FilterQuery: "env:prod AND service:example-fleet-automation",
    			},
    			Type: datadogV2.FLEETDEPLOYMENTRESOURCETYPE_DEPLOYMENT,
    		},
    	}
    	ctx := datadog.NewDefaultContext(context.Background())
    	configuration := datadog.NewConfiguration()
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewFleetAutomationApi(apiClient)
    	resp, r, err := api.CreateFleetDeploymentConfigureV2(ctx, body)
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `FleetAutomationApi.CreateFleetDeploymentConfigureV2`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `FleetAutomationApi.CreateFleetDeploymentConfigureV2`:\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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
    // Create a configuration deployment returns "OK" 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.FleetDeploymentConfigureV2Attributes;
    import com.datadog.api.client.v2.model.FleetDeploymentConfigureV2Create;
    import com.datadog.api.client.v2.model.FleetDeploymentConfigureV2CreateRequest;
    import com.datadog.api.client.v2.model.FleetDeploymentConfigureV2DryRunResponse;
    import com.datadog.api.client.v2.model.FleetDeploymentFileOp;
    import com.datadog.api.client.v2.model.FleetDeploymentOperation;
    import com.datadog.api.client.v2.model.FleetDeploymentResourceType;
    import java.util.Collections;
    import java.util.Map;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        FleetAutomationApi apiInstance = new FleetAutomationApi(defaultClient);
    
        FleetDeploymentConfigureV2CreateRequest body =
            new FleetDeploymentConfigureV2CreateRequest()
                .data(
                    new FleetDeploymentConfigureV2Create()
                        .attributes(
                            new FleetDeploymentConfigureV2Attributes()
                                .configOperations(
                                    Collections.singletonList(
                                        new FleetDeploymentOperation()
                                            .fileOp(FleetDeploymentFileOp.MERGE_PATCH)
                                            .filePath("/datadog.yaml")
                                            .patch(Map.ofEntries(Map.entry("log_level", "info")))))
                                .dryRun(true)
                                .filterQuery("env:prod AND service:example-fleet-automation"))
                        .type(FleetDeploymentResourceType.DEPLOYMENT));
    
        try {
          FleetDeploymentConfigureV2DryRunResponse result =
              apiInstance.createFleetDeploymentConfigureV2(body);
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println(
              "Exception when calling FleetAutomationApi#createFleetDeploymentConfigureV2");
          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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
    // Create a configuration deployment returns "OK" response
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_fleet_automation::FleetAutomationAPI;
    use datadog_api_client::datadogV2::model::FleetDeploymentConfigureV2Attributes;
    use datadog_api_client::datadogV2::model::FleetDeploymentConfigureV2Create;
    use datadog_api_client::datadogV2::model::FleetDeploymentConfigureV2CreateRequest;
    use datadog_api_client::datadogV2::model::FleetDeploymentFileOp;
    use datadog_api_client::datadogV2::model::FleetDeploymentOperation;
    use datadog_api_client::datadogV2::model::FleetDeploymentResourceType;
    use serde_json::Value;
    use std::collections::BTreeMap;
    
    #[tokio::main]
    async fn main() {
        let body = FleetDeploymentConfigureV2CreateRequest::new(FleetDeploymentConfigureV2Create::new(
            FleetDeploymentConfigureV2Attributes::new(
                vec![FleetDeploymentOperation::new(
                    FleetDeploymentFileOp::MERGE_PATCH,
                    "/datadog.yaml".to_string(),
                )
                .patch(BTreeMap::from([(
                    "log_level".to_string(),
                    Value::from("info"),
                )]))],
                "env:prod AND service:example-fleet-automation".to_string(),
            )
            .dry_run(true),
            FleetDeploymentResourceType::DEPLOYMENT,
        ));
        let configuration = datadog::Configuration::new();
        let api = FleetAutomationAPI::with_config(configuration);
        let resp = api.create_fleet_deployment_configure_v2(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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
    /**
     * Create a configuration deployment returns "OK" response
     */
    
    import { client, v2 } from "@datadog/datadog-api-client";
    
    const configuration = client.createConfiguration();
    const apiInstance = new v2.FleetAutomationApi(configuration);
    
    const params: v2.FleetAutomationApiCreateFleetDeploymentConfigureV2Request = {
      body: {
        data: {
          attributes: {
            configOperations: [
              {
                fileOp: "merge-patch",
                filePath: "/datadog.yaml",
                patch: {
                  log_level: "info",
                },
              },
            ],
            dryRun: true,
            filterQuery: "env:prod AND service:example-fleet-automation",
          },
          type: "deployment",
        },
      },
    };
    
    apiInstance
      .createFleetDeploymentConfigureV2(params)
      .then((data: v2.FleetDeploymentConfigureV2DryRunResponse) => {
        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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"