deployments
Creates, updates, deletes, gets or lists a deployments resource.
Overview
| Name | deployments |
| Type | Resource |
| Id | datadog.fleet.deployments |
Fields
The following fields are returned by SELECT queries:
- get_fleet_deployment_v2
- list_fleet_deployments_v2
| Name | Datatype | Description |
|---|---|---|
id | string | Unique identifier for the deployment. (example: k7Q-3mX-p9Z) |
attributes | object | Attributes of a deployment detail response. |
type | string | The type of deployment resource. (deployment) (default: deployment, example: deployment) |
| Name | Datatype | Description |
|---|---|---|
id | string | Unique identifier for the deployment. (example: k7Q-3mX-p9Z) |
attributes | object | Attributes of a deployment in the v2 API response. |
type | string | The type of deployment resource. (deployment) (default: deployment, example: deployment) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
get_fleet_deployment_v2 | select | deployment_id | Retrieve detailed information about a specific deployment, including its current status,<br />configuration operations, and per-host execution status.<br /><br />Returns a 404 if no deployment matches the given ID or if you do not have access to it. | |
list_fleet_deployments_v2 | select | page_size, page_number, sort, ascending, filter | Retrieve a paginated list of all deployments for fleet automation. | |
create_fleet_deployment_configure_v2 | exec | data | Create a new deployment to apply configuration changes<br />to a fleet of hosts matching the specified filter query.<br /><br />This endpoint supports two types of configuration operations:<br />- merge-patch: Merges the provided patch data with the existing configuration file,<br /> creating the file if it doesn't exist.<br />- delete: Removes the specified configuration file from the target hosts.<br /><br />You can optionally use target_packages to apply the configuration change only to specific package versions.<br /><br />The deployment is created and started automatically. You can specify multiple configuration<br />operations to execute in order on each target host. Use the filter query to target<br />specific hosts using the Datadog query syntax.<br /><br />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.<br /><br />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. | |
create_fleet_deployment_upgrade_v2 | exec | data | Create and immediately start a new package upgrade<br />on hosts matching the specified filter query.<br /><br />This endpoint allows you to upgrade the Datadog Agent to a specific version<br />on hosts matching the specified filter query.<br /><br />The deployment is created and started automatically. The system:<br />1. Identifies all hosts matching the filter query.<br />2. Validates that the specified version is available.<br />3. Begins rolling out the package upgrade to the target hosts.<br /><br />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. | |
cancel_fleet_deployment_v2 | exec | deployment_id | Cancel an active deployment and stop all pending operations.<br />When you cancel a deployment:<br />- All pending operations on hosts that haven't started yet are stopped.<br />- Operations currently in progress on hosts may complete or be interrupted, depending on their current status.<br />- Configuration changes or package upgrades already applied to hosts are not rolled back.<br /><br />After cancellation, you can view the final state of the deployment using the GET endpoint to see which hosts<br />were successfully updated before the cancellation.<br /><br />Only deployments with a pending or running status can be canceled. Returns a 400 if the deployment is not in a cancelable status. Returns a 404 if no deployment matches the specified ID or if you do not have access to it. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
deployment_id | string | The unique identifier of the deployment to cancel. (example: k7Q-3mX-p9Z) |
site | string | The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both. |
ascending | boolean | Set to true to sort in ascending order. This setting has no effect unless sort is also set. Defaults to descending order. |
filter | string | Query used to filter deployments. Uses the Datadog query syntax. Filtering on an unsupported field returns a 400 error. For example: - status:failed or status:done_with_errors: deployments that need investigation. - status:running: deployments currently in flight. - update_type:update_package or update_type:update_config_operations: deployments of a given type. (example: status:failed) |
page_number | integer (int64) | Page number for pagination, starting at 0. |
page_size | integer (int64) | Number of deployments to return per page. Maximum value is 100. |
sort | string | Field to sort results by (for example, start_date). Must be a supported field name; unsupported values return a 400 error. |
SELECT examples
- get_fleet_deployment_v2
- list_fleet_deployments_v2
Retrieve detailed information about a specific deployment, including its current status,<br />configuration operations, and per-host execution status.<br /><br />Returns a 404 if no deployment matches the given ID or if you do not have access to it.
SELECT
id,
attributes,
type
FROM datadog.fleet.deployments
WHERE deployment_id = '{{ deployment_id }}' -- required
;
Retrieve a paginated list of all deployments for fleet automation.
SELECT
id,
attributes,
type
FROM datadog.fleet.deployments
WHERE page_size = '{{ page_size }}'
AND page_number = '{{ page_number }}'
AND sort = '{{ sort }}'
AND ascending = '{{ ascending }}'
AND filter = '{{ filter }}'
;
Lifecycle Methods
EXEC variables use wire (API) names.
- create_fleet_deployment_configure_v2
- create_fleet_deployment_upgrade_v2
- cancel_fleet_deployment_v2
Create a new deployment to apply configuration changes<br />to a fleet of hosts matching the specified filter query.<br /><br />This endpoint supports two types of configuration operations:<br />- merge-patch: Merges the provided patch data with the existing configuration file,<br /> creating the file if it doesn't exist.<br />- delete: Removes the specified configuration file from the target hosts.<br /><br />You can optionally use target_packages to apply the configuration change only to specific package versions.<br /><br />The deployment is created and started automatically. You can specify multiple configuration<br />operations to execute in order on each target host. Use the filter query to target<br />specific hosts using the Datadog query syntax.<br /><br />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.<br /><br />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.
EXEC datadog.fleet.deployments.create_fleet_deployment_configure_v2
@@json=
'{
"data": "{{ data }}"
}'
;
Create and immediately start a new package upgrade<br />on hosts matching the specified filter query.<br /><br />This endpoint allows you to upgrade the Datadog Agent to a specific version<br />on hosts matching the specified filter query.<br /><br />The deployment is created and started automatically. The system:<br />1. Identifies all hosts matching the filter query.<br />2. Validates that the specified version is available.<br />3. Begins rolling out the package upgrade to the target hosts.<br /><br />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.
EXEC datadog.fleet.deployments.create_fleet_deployment_upgrade_v2
@@json=
'{
"data": "{{ data }}"
}'
;
Cancel an active deployment and stop all pending operations.<br />When you cancel a deployment:<br />- All pending operations on hosts that haven't started yet are stopped.<br />- Operations currently in progress on hosts may complete or be interrupted, depending on their current status.<br />- Configuration changes or package upgrades already applied to hosts are not rolled back.<br /><br />After cancellation, you can view the final state of the deployment using the GET endpoint to see which hosts<br />were successfully updated before the cancellation.<br /><br />Only deployments with a pending or running status can be canceled. Returns a 400 if the deployment is not in a cancelable status. Returns a 404 if no deployment matches the specified ID or if you do not have access to it.
EXEC datadog.fleet.deployments.cancel_fleet_deployment_v2
@deployment_id='{{ deployment_id }}' --required
;