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

Preview

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

--name

The name of the deployment to cancel.

--resource-group

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.

--profile

Use the named profile for this command (overrides the active profile).

--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.

az deployment group create

Preview

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

--resource-group

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.

--mode

The deployment mode. Incremental (default) or Complete.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment.

--parameter

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.

--parameters-file

The path to a local parameters file to deploy inline.

--parameters-uri

The URI of a parameters file.

--profile

Use the named profile for this command (overrides the active profile).

--query-string

The query string (such as a SAS token) to use with the template URI. Only valid together with a template URI.

--rollback-on-error

Roll the resource group back to the last successful deployment on error.

--rollback-to-deployment-name

Roll the resource group back to a specific named deployment on error. Mutually exclusive with rollback-on-error.

--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

--template-file

The path to a local ARM template file to deploy inline.

--template-spec-id

The resource id of a Template Spec to deploy.

--template-uri

The URI of the ARM template to deploy.

--validation-level

The validation level of the deployment.

Property Value
Accepted values: Template, Provider, ProviderNoRbac
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.

az deployment group delete

Preview

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

--name

The name of the deployment to delete.

--resource-group

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.

--profile

Use the named profile for this command (overrides the active profile).

--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.

az deployment group export

Preview

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

--name

The name of the deployment whose template to export.

--resource-group

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.

--profile

Use the named profile for this command (overrides the active profile).

--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.

az deployment group list

Preview

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

--resource-group

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

Filter expression using OData notation, e.g. "provisioningState eq 'Failed'".

--profile

Use the named profile for this command (overrides the active profile).

--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.

az deployment group show

Preview

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

--name

The name of the deployment.

--resource-group

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.

--profile

Use the named profile for this command (overrides the active profile).

--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.

az deployment group validate

Preview

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

--resource-group

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.

--mode

The deployment mode. Incremental (default) or Complete.

Property Value
Accepted values: Incremental, Complete
--name

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.

--parameter

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.

--parameters-file

The path to a local parameters file to evaluate inline.

--parameters-uri

The URI of a parameters file.

--profile

Use the named profile for this command (overrides the active profile).

--query-string

The query string (such as a SAS token) to use with the template URI. Only valid together with a template URI.

--rollback-on-error

Roll the resource group back to the last successful deployment on error.

--rollback-to-deployment-name

Roll the resource group back to a specific named deployment on error. Mutually exclusive with rollback-on-error.

--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

--template-file

The path to a local ARM template file to validate inline.

--template-spec-id

The resource id of a Template Spec to validate.

--template-uri

The URI of the ARM template to validate.

--validation-level

The validation level of the deployment.

Property Value
Accepted values: Template, Provider, ProviderNoRbac
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.

az deployment group what-if

Preview

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

--resource-group

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.

--mode

The deployment mode. Incremental (default) or Complete.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment.

--parameter

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.

--parameters-file

The path to a local parameters file to evaluate inline.

--parameters-uri

The URI of a parameters file.

--profile

Use the named profile for this command (overrides the active profile).

--query-string

The query string (such as a SAS token) to use with the template URI. Only valid together with a template URI.

--result-format

The format of the what-if results. FullResourcePayloads (default) or ResourceIdOnly.

Property Value
Accepted values: FullResourcePayloads, ResourceIdOnly
--subscription-id

Azure Subscription Id. Defaults to the active profile's subscription.

--template-file

The path to a local ARM template file to evaluate inline.

--template-spec-id

The resource id of a Template Spec to evaluate.

--template-uri

The URI of the ARM template to evaluate.

--validation-level

The validation level of the what-if operation.

Property Value
Accepted values: Template, Provider, ProviderNoRbac
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h -help -? --?

Show help for the command or group and exit.

--no-cache

Bypass the extension discovery cache and reload extensions from disk.

--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, table, tsv, yaml, yamlc
--query

JMESPath query string to filter/project the command result before rendering.