az deployment group
Manage Azure Resource Manager deployments scoped to a resource group.
Commands
| Name | Description | Type | Status |
|---|---|---|---|
| az deployment group cancel |
Cancel a running resource group deployment. |
Core | Preview |
| az deployment group create |
Create a resource group scoped deployment from an ARM or Bicep template. |
Core | Preview |
| az deployment group delete |
Delete a resource group deployment from the deployment history. |
Core | Preview |
| az deployment group export |
Export the template used for a resource group deployment. |
Core | Preview |
| az deployment group list |
List the deployments in a resource group. |
Core | Preview |
| az deployment group show |
Show details of a single resource group deployment. |
Core | Preview |
| az deployment group validate |
Validate whether a resource group scoped deployment template would be accepted, without deploying it. |
Core | Preview |
| az deployment group what-if |
Preview the changes a resource group scoped deployment would make, without applying them. |
Core | Preview |
az deployment group cancel
Cancel a running resource group deployment.
Cancel a currently running Azure Resource Manager deployment scoped to a resource group. A deployment can only be cancelled while its provisioning state is Accepted or Running; once cancelled the state becomes Canceled and the resource group is left partially deployed, so any resources the deployment already created remain and must be cleaned up separately. Cancelling a deployment that has already reached a terminal state fails with DeploymentCannotBeCancelled. The command prints nothing on success; the subscription defaults to the active profile's subscription unless --subscription-id is given.
az deployment group cancel --name
--resource-group
[--profile]
[--subscription-id]
Examples
Cancel a running deployment
az deployment group cancel --resource-group myResourceGroup --name myDeployment
Cancel a running deployment in a specific subscription
az deployment group cancel --resource-group myResourceGroup --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000
Required Parameters
The name of the deployment to cancel.
The name of the resource group that contains the deployment.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Use the named profile for this command (overrides the active profile).
Azure Subscription Id. Defaults to the active profile's subscription.
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.
az deployment group create
Create a resource group scoped deployment from an ARM or Bicep template.
Create (start) a resource group scoped deployment, mirroring az deployment group create. The template is supplied with exactly one of --template-file (a local ARM or Bicep template deployed inline), --template-uri (a remote template URL), or --template-spec-id (the resource id of a Template Spec). --resource-group (required) is the resource group to deploy into and --name (optional) is the deployment name, derived from the template file or URI name when omitted, or generated if no valid name can be derived; --subscription-id (optional) selects the subscription. Parameters can be supplied with --parameters-file (a local parameters file), --parameters-uri (a remote parameters file URL), and/or one or more repeatable inline --parameter KEY=VALUE pairs; inline parameter values are parsed as JSON when possible (for example count=3 becomes a number and flag=true becomes a bool) and otherwise treated as strings, quote a value to force a string (for example zip="01234"). Inline parameters overlay same-named keys from a parameters file and cannot be combined with --parameters-uri. --query-string carries a SAS token or other query string to use with the template URI and/or the parameters URI. --mode selects the deployment mode, Incremental (default) or Complete. --validation-level sets the validation level, one of Template, Provider, or ProviderNoRbac. On failure the deployment can roll back with either --rollback-on-error (roll the resource group back to the last successful deployment) or --rollback-to-deployment-name <name> (roll back to a specific named deployment); the two rollback options are mutually exclusive. The command waits for the deployment long-running operation to finish and returns the final deployment result.
az deployment group create --resource-group
[--mode {Incremental, Complete}]
[--name]
[--parameter]
[--parameters-file]
[--parameters-uri]
[--profile]
[--query-string]
[--rollback-on-error]
[--rollback-to-deployment-name]
[--subscription-id]
[--template-file]
[--template-spec-id]
[--template-uri]
[--validation-level {Template, Provider, ProviderNoRbac}]
Examples
Deploy a local Bicep template with inline parameters
az deployment group create --resource-group myResourceGroup --name myDeployment --template-file ./main.bicep --parameter location=eastus --parameter instanceCount=3
Deploy a remote ARM template with a remote parameters file
az deployment group create --resource-group myResourceGroup --name myDeployment --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json --mode Incremental --subscription-id 00000000-0000-0000-0000-000000000000
Deploy a Template Spec in Complete mode with rollback on error
az deployment group create --resource-group myResourceGroup --name myDeployment --template-spec-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0 --mode Complete --validation-level Template --rollback-on-error
Required Parameters
The name of the resource group to deploy into.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
The deployment mode. Incremental (default) or Complete.
| Property | Value |
|---|---|
| Accepted values: | Incremental, Complete |
The name of the deployment.
Deployment parameter(s) (repeatable): KEY=VALUE, a raw JSON object, or a path to a JSON parameters file (optionally prefixed with '@'). Values are parsed as JSON when possible (count=3 a number, flag=true a bool), else treated as strings; quote to force a string (e.g. zip="01234"). Overlay same-named keys from a parameters file. Cannot be combined with parameters-uri.
The path to a local parameters file to deploy inline.
The URI of a parameters file.
Use the named profile for this command (overrides the active profile).
The query string (such as a SAS token) to use with the template URI. Only valid together with a template URI.
Roll the resource group back to the last successful deployment on error.
Roll the resource group back to a specific named deployment on error. Mutually exclusive with rollback-on-error.
Azure Subscription Id. Defaults to the active profile's subscription.
The path to a local ARM template file to deploy inline.
The resource id of a Template Spec to deploy.
The URI of the ARM template to deploy.
The validation level of the deployment.
| Property | Value |
|---|---|
| Accepted values: | Template, Provider, ProviderNoRbac |
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.
az deployment group delete
Delete a resource group deployment from the deployment history.
Delete an Azure Resource Manager deployment scoped to a resource group. This removes the deployment record and its associated deployment operations from the deployment history; it does not delete the resources the deployment created, and it leaves the resource group itself untouched. A deployment that is currently running cannot be deleted -- cancel it with az deployment group cancel first, or wait for it to reach a terminal state. The delete is a long-running operation and the command waits for it to finish. Deleting a deployment name that does not exist succeeds silently, because ARM answers the same 204 No Content in both cases. The command prints nothing on success; the subscription defaults to the active profile's subscription unless --subscription-id is given.
az deployment group delete --name
--resource-group
[--profile]
[--subscription-id]
Examples
Delete a deployment from the history
az deployment group delete --resource-group myResourceGroup --name myDeployment
Delete a deployment in a specific subscription
az deployment group delete --resource-group myResourceGroup --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000
Required Parameters
The name of the deployment to delete.
The name of the resource group that contains the deployment.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Use the named profile for this command (overrides the active profile).
Azure Subscription Id. Defaults to the active profile's subscription.
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.
az deployment group export
Export the template used for a resource group deployment.
Export the Azure Resource Manager template that a resource-group-scoped deployment was created from, and print it to stdout as JSON. The command is read-only: it never creates or modifies resources. Azure Resource Manager returns the template exactly as it was submitted, with parameters and variables left unresolved, so the output can be fed straight back into az deployment group create --template-file. Exporting a deployment that does not exist fails with DeploymentNotFound. The subscription defaults to the active profile's subscription unless --subscription-id is given.
az deployment group export --name
--resource-group
[--profile]
[--subscription-id]
Examples
Export a deployment's template
az deployment group export --resource-group myResourceGroup --name myDeployment
Save the exported template to a file
az deployment group export --resource-group myResourceGroup --name myDeployment > myDeployment.json
Export a deployment's template from a specific subscription
az deployment group export --resource-group myResourceGroup --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000
Required Parameters
The name of the deployment whose template to export.
The name of the resource group that contains the deployment.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Use the named profile for this command (overrides the active profile).
Azure Subscription Id. Defaults to the active profile's subscription.
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.
az deployment group list
List the deployments in a resource group.
List every Azure Resource Manager deployment scoped to a resource group. Results are returned as a flat array of deployments with their provisioning state, mode, timestamp, and outputs; paged results are followed automatically. The subscription defaults to the active profile's subscription unless --subscription-id is given.
az deployment group list --resource-group
[--filter]
[--profile]
[--subscription-id]
Examples
List the deployments in a resource group
az deployment group list --resource-group myResourceGroup
List deployments in a specific subscription
az deployment group list --resource-group myResourceGroup --subscription-id 00000000-0000-0000-0000-000000000000
Required Parameters
The name of the resource group whose deployments to list.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Filter expression using OData notation, e.g. "provisioningState eq 'Failed'".
Use the named profile for this command (overrides the active profile).
Azure Subscription Id. Defaults to the active profile's subscription.
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.
az deployment group show
Show details of a single resource group deployment.
Display a single Azure Resource Manager deployment scoped to a resource group, including its provisioning state, mode, timestamp, duration, template hash, outputs, and the resources it provisioned. Specify the resource group and the deployment name; the subscription defaults to the active profile's subscription unless --subscription-id is given.
az deployment group show --name
--resource-group
[--profile]
[--subscription-id]
Examples
Show a deployment
az deployment group show --resource-group myResourceGroup --name myDeployment
Show a deployment in a specific subscription
az deployment group show --resource-group myResourceGroup --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000
Required Parameters
The name of the deployment.
The name of the resource group that contains the deployment.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Use the named profile for this command (overrides the active profile).
Azure Subscription Id. Defaults to the active profile's subscription.
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.
az deployment group validate
Validate whether a resource group scoped deployment template would be accepted, without deploying it.
Validate a resource group scoped deployment, mirroring az deployment group validate. Validate is read-only: it asks Azure Resource Manager whether a template is syntactically correct and would be accepted, without creating or modifying any resources. Unlike az deployment group what-if, it reports whether the template is valid rather than predicting the individual resource changes. The template is supplied with exactly one of --template-file (a local ARM or Bicep template evaluated inline), --template-uri (a remote template URL), or --template-spec-id (the resource id of a Template Spec). --resource-group (required) is the resource group to validate against and --name (optional) is the deployment name and defaults to the template file or URI name without its extension, or a generated GUID when no valid name can be derived; --subscription-id (optional) selects the subscription. Parameters can be supplied with --parameters-file (a local parameters file), --parameters-uri (a remote parameters file URL), and/or one or more repeatable inline --parameter KEY=VALUE pairs; inline parameter values are parsed as JSON when possible (for example count=3 becomes a number and flag=true becomes a bool) and otherwise treated as strings, quote a value to force a string (for example zip="01234"). Inline parameters overlay same-named keys from a parameters file and cannot be combined with --parameters-uri. --query-string carries a SAS token or other query string to use with the template URI and/or the parameters URI. --mode selects the deployment mode, Incremental (default) or Complete. --validation-level sets the validation level, one of Template, Provider, or ProviderNoRbac. --rollback-on-error records that the resource group should roll back to the last successful deployment on error, and --rollback-to-deployment-name rolls back to a specific named deployment instead; the two are mutually exclusive. When the template is valid the command returns the validation result; when it is not, the command reports the validation errors and exits with a non-zero status.
az deployment group validate --resource-group
[--mode {Incremental, Complete}]
[--name]
[--parameter]
[--parameters-file]
[--parameters-uri]
[--profile]
[--query-string]
[--rollback-on-error]
[--rollback-to-deployment-name]
[--subscription-id]
[--template-file]
[--template-spec-id]
[--template-uri]
[--validation-level {Template, Provider, ProviderNoRbac}]
Examples
Validate a local Bicep template with inline parameters
az deployment group validate --resource-group myResourceGroup --name myDeployment --template-file ./main.bicep --parameter location=eastus --parameter instanceCount=3
Validate a remote ARM template with a remote parameters file
az deployment group validate --resource-group myResourceGroup --name myDeployment --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json --mode Incremental --subscription-id 00000000-0000-0000-0000-000000000000
Validate a Template Spec in Complete mode at the Template validation level
az deployment group validate --resource-group myResourceGroup --name myDeployment --template-spec-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0 --mode Complete --validation-level Template
Required Parameters
The name of the resource group to validate the deployment against.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
The deployment mode. Incremental (default) or Complete.
| Property | Value |
|---|---|
| Accepted values: | Incremental, Complete |
The name of the deployment. Defaults to the template file or URI name without its extension, or a generated GUID when no valid name can be derived.
Deployment parameter(s) (repeatable): KEY=VALUE, a raw JSON object, or a path to a JSON parameters file (optionally prefixed with '@'). Values are parsed as JSON when possible (count=3 a number, flag=true a bool), else treated as strings; quote to force a string (e.g. zip="01234"). Overlay same-named keys from a parameters file. Cannot be combined with parameters-uri.
The path to a local parameters file to evaluate inline.
The URI of a parameters file.
Use the named profile for this command (overrides the active profile).
The query string (such as a SAS token) to use with the template URI. Only valid together with a template URI.
Roll the resource group back to the last successful deployment on error.
Roll the resource group back to a specific named deployment on error. Mutually exclusive with rollback-on-error.
Azure Subscription Id. Defaults to the active profile's subscription.
The path to a local ARM template file to validate inline.
The resource id of a Template Spec to validate.
The URI of the ARM template to validate.
The validation level of the deployment.
| Property | Value |
|---|---|
| Accepted values: | Template, Provider, ProviderNoRbac |
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.
az deployment group what-if
Preview the changes a resource group scoped deployment would make, without applying them.
Run a resource group scoped what-if operation, mirroring az deployment group what-if. What-if is read-only: it predicts the set of changes (Create, Modify, Delete, Deploy, NoChange, Ignore) an ARM or Bicep template would make without creating or modifying any resources. The template is supplied with exactly one of --template-file (a local ARM or Bicep template evaluated inline), --template-uri (a remote template URL), or --template-spec-id (the resource id of a Template Spec). --resource-group (required) is the resource group to evaluate against and --name (optional) is the deployment name, derived from the template file or URI name when omitted, or generated if no valid name can be derived; --subscription-id (optional) selects the subscription. Parameters can be supplied with --parameters-file (a local parameters file), --parameters-uri (a remote parameters file URL), and/or one or more repeatable inline --parameter KEY=VALUE pairs; inline parameter values are parsed as JSON when possible (for example count=3 becomes a number and flag=true becomes a bool) and otherwise treated as strings, quote a value to force a string (for example zip="01234"). Inline parameters overlay same-named keys from a parameters file and cannot be combined with --parameters-uri. --query-string carries a SAS token or other query string to use with the template URI and/or the parameters URI. --mode selects the deployment mode, Incremental (default) or Complete. --validation-level sets the validation level, one of Template, Provider, or ProviderNoRbac. --result-format selects how much detail the predicted changes carry, FullResourcePayloads (default, full before/after resource snapshots) or ResourceIdOnly (resource ids only). The command waits for the what-if long-running operation to finish and returns the predicted change list.
az deployment group what-if --resource-group
[--mode {Incremental, Complete}]
[--name]
[--parameter]
[--parameters-file]
[--parameters-uri]
[--profile]
[--query-string]
[--result-format {FullResourcePayloads, ResourceIdOnly}]
[--subscription-id]
[--template-file]
[--template-spec-id]
[--template-uri]
[--validation-level {Template, Provider, ProviderNoRbac}]
Examples
Preview a local Bicep template with inline parameters
az deployment group what-if --resource-group myResourceGroup --name myDeployment --template-file ./main.bicep --parameter location=eastus --parameter instanceCount=3
Preview a remote ARM template with a remote parameters file
az deployment group what-if --resource-group myResourceGroup --name myDeployment --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json --mode Incremental --subscription-id 00000000-0000-0000-0000-000000000000
Preview a Template Spec in Complete mode returning resource ids only
az deployment group what-if --resource-group myResourceGroup --name myDeployment --template-spec-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0 --mode Complete --validation-level Template --result-format ResourceIdOnly
Required Parameters
The name of the resource group to run the what-if against.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
The deployment mode. Incremental (default) or Complete.
| Property | Value |
|---|---|
| Accepted values: | Incremental, Complete |
The name of the deployment.
Deployment parameter(s) (repeatable): KEY=VALUE, a raw JSON object, or a path to a JSON parameters file (optionally prefixed with '@'). Values are parsed as JSON when possible (count=3 a number, flag=true a bool), else treated as strings; quote to force a string (e.g. zip="01234"). Overlay same-named keys from a parameters file. Cannot be combined with parameters-uri.
The path to a local parameters file to evaluate inline.
The URI of a parameters file.
Use the named profile for this command (overrides the active profile).
The query string (such as a SAS token) to use with the template URI. Only valid together with a template URI.
The format of the what-if results. FullResourcePayloads (default) or ResourceIdOnly.
| Property | Value |
|---|---|
| Accepted values: | FullResourcePayloads, ResourceIdOnly |
Azure Subscription Id. Defaults to the active profile's subscription.
The path to a local ARM template file to evaluate inline.
The resource id of a Template Spec to evaluate.
The URI of the ARM template to evaluate.
The validation level of the what-if operation.
| Property | Value |
|---|---|
| Accepted values: | Template, Provider, ProviderNoRbac |
Global Parameters
Increase logging verbosity to show all debug logs.
Show help for the command or group and exit.
Bypass the extension discovery cache and reload extensions from disk.
Output format.
| Property | Value |
|---|---|
| Default value: | json |
| Accepted values: | json, jsonc, table, tsv, yaml, yamlc |
JMESPath query string to filter/project the command result before rendering.