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.
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"}}
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"}}
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"}}
# Create a configuration deployment returns "OK" responserequire"datadog_api_client"api_instance=DatadogAPIClient::V2::FleetAutomationAPI.newbody=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,}),})papi_instance.create_fleet_deployment_configure_v2(body)
// Create a configuration deployment returns "OK" responsepackagemainimport("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")funcmain(){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)iferr!=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)}
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";constconfiguration=client.createConfiguration();constapiInstance=newv2.FleetAutomationApi(configuration);constparams: 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));