az deployment sub

Manage Azure Resource Manager deployments scoped to a subscription.

Commands

Name Description Type Status
az deployment sub cancel

Cancel a running subscription deployment.

Core Preview
az deployment sub create

Create a subscription scoped deployment from an ARM or Bicep template.

Core Preview
az deployment sub delete

Delete a subscription deployment from the deployment history.

Core Preview
az deployment sub export

Export the template used for a subscription deployment.

Core Preview
az deployment sub list

List the deployments in a subscription.

Core Preview
az deployment sub show

Show details of a single subscription deployment.

Core Preview
az deployment sub validate

Validate whether a subscription scoped deployment template would be accepted, without deploying it.

Core Preview
az deployment sub what-if

Preview the changes a subscription scoped deployment would make, without applying them.

Core Preview

az deployment sub cancel

Preview

Cancel a running subscription deployment.

Cancel a currently running Azure Resource Manager deployment scoped to a subscription. A deployment can only be cancelled while its provisioning state is Accepted or Running; once cancelled the state becomes Canceled and 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 sub cancel --name
                         [--profile]
                         [--subscription-id]

Examples

Cancel a running deployment

az deployment sub cancel --name myDeployment

Cancel a running deployment in a specific subscription

az deployment sub cancel --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000

Required Parameters

--name

The name of the deployment to cancel.

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 sub create

Preview

Create a subscription scoped deployment from an ARM or Bicep template.

Create (start) a subscription scoped deployment, mirroring az deployment sub create. The template is supplied with exactly one of --template-file (a local ARM or Bicep template deployed inline), --template-uri (a remote ARM template URL), or --template-spec-id (the resource id of a Template Spec version). A .bicepparam file given to --parameters-file can supply the template on its own. Bicep files are compiled with the Bicep CLI, which must be installed. --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; --location (required) is the region where the deployment metadata is stored; --mode (optional) is the deployment mode, Incremental (default) or Complete; --subscription-id (optional) selects the subscription. Template parameters can be supplied with --parameters-file (a local JSON or .bicepparam 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 is a SAS token or other query string sent on the template link; it requires --template-uri, a leading ? or & is removed, and it is not added to --parameters-uri. --validation-level sets the validation level, one of Template, Provider, or ProviderNoRbac. The command waits for the deployment long-running operation to finish and returns the final deployment result.

az deployment sub create --location
                         [--mode {Incremental, Complete}]
                         [--name]
                         [--parameter]
                         [--parameters-file]
                         [--parameters-uri]
                         [--profile]
                         [--query-string]
                         [--subscription-id]
                         [--template-file]
                         [--template-spec-id]
                         [--template-uri]
                         [--validation-level {Template, Provider, ProviderNoRbac}]

Examples

Deploy a local Bicep template that creates a resource group

az deployment sub create --location eastus --name myDeployment --mode Incremental --template-file ./main.bicep --parameter resourceGroupName=myResourceGroup

Deploy a local ARM template with a local parameters file

az deployment sub create --location eastus --name myDeployment --mode Incremental --template-file ./azuredeploy.json --parameters-file ./azuredeploy.parameters.json

Deploy a remote ARM template with a remote parameters file

az deployment sub create --location eastus --name myDeployment --mode Incremental --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json --subscription-id 00000000-0000-0000-0000-000000000000

Deploy a Template Spec at the Template validation level

az deployment sub create --location eastus --name myDeployment --mode Incremental --template-spec-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0 --validation-level Template

Required Parameters

--location -l

The location to store the deployment metadata.

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 mode that is used to deploy resources.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment.

--parameter -p

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 ARM JSON or .bicepparam parameters file. A .bicepparam file can supply its own template and requires the Bicep CLI. Cannot be combined with --parameters-uri.

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

--subscription-id

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

--template-file

The path to a local ARM JSON or Bicep template. Bicep files require the Bicep CLI for local compilation.

--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 sub delete

Preview

Delete a subscription deployment from the deployment history.

Delete an Azure Resource Manager deployment scoped to a subscription. This removes the deployment record and its associated deployment operations from the deployment history; it does not delete the resources the deployment created, such as resource groups. A deployment that is currently running cannot be deleted -- cancel it with az deployment sub 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 sub delete --name
                         [--profile]
                         [--subscription-id]

Examples

Delete a deployment from the history

az deployment sub delete --name myDeployment

Delete a deployment in a specific subscription

az deployment sub delete --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000

Required Parameters

--name

The name of the deployment to delete.

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 sub export

Preview

Export the template used for a subscription deployment.

Export the Azure Resource Manager template that a subscription 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 sub 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 sub export --name
                         [--profile]
                         [--subscription-id]

Examples

Export a deployment's template

az deployment sub export --name myDeployment

Save the exported template to a file

az deployment sub export --name myDeployment > myDeployment.json

Export a deployment's template from a specific subscription

az deployment sub export --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000

Required Parameters

--name

The name of the deployment whose template to export.

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 sub list

Preview

List the deployments in a subscription.

List every Azure Resource Manager deployment scoped to a subscription. 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 sub list [--filter]
                       [--profile]
                       [--subscription-id]

Examples

List the deployments in the current subscription

az deployment sub list

List deployments in a specific subscription

az deployment sub list --subscription-id 00000000-0000-0000-0000-000000000000

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 sub show

Preview

Show details of a single subscription deployment.

Display a single Azure Resource Manager deployment scoped to a subscription, including its provisioning state, mode, timestamp, duration, template hash, outputs, and the resources it provisioned. Specify the deployment name; the subscription defaults to the active profile's subscription unless --subscription-id is given.

az deployment sub show --name
                       [--profile]
                       [--subscription-id]

Examples

Show a deployment

az deployment sub show --name myDeployment

Show a deployment in a specific subscription

az deployment sub show --name myDeployment --subscription-id 00000000-0000-0000-0000-000000000000

Required Parameters

--name

The name of 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 sub validate

Preview

Validate whether a subscription scoped deployment template would be accepted, without deploying it.

Validate a subscription scoped deployment, mirroring az deployment sub 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 sub 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 ARM template URL), or --template-spec-id (the resource id of a Template Spec version). A .bicepparam file given to --parameters-file can supply the template on its own. Bicep files are compiled with the Bicep CLI, which must be installed. --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; --location (required) is the region where the deployment metadata is stored; --mode (optional) is the deployment mode, Incremental (default) or Complete; --subscription-id (optional) selects the subscription. Template parameters can be supplied with --parameters-file (a local JSON or .bicepparam 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 is a SAS token or other query string sent on the template link; it requires --template-uri, a leading ? or & is removed, and it is not added to --parameters-uri. --validation-level sets the validation level, one of Template, Provider, or ProviderNoRbac. When the template is valid the command returns the validation result; when it is not, the command fails with the Azure Resource Manager error.

az deployment sub validate --location
                           [--mode {Incremental, Complete}]
                           [--name]
                           [--parameter]
                           [--parameters-file]
                           [--parameters-uri]
                           [--profile]
                           [--query-string]
                           [--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 sub validate --location eastus --name myDeployment --mode Incremental --template-file ./main.bicep --parameter resourceGroupName=myResourceGroup

Validate a remote ARM template with a remote parameters file

az deployment sub validate --location eastus --name myDeployment --mode Incremental --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json --subscription-id 00000000-0000-0000-0000-000000000000

Validate a Template Spec at the Template validation level

az deployment sub validate --location eastus --name myDeployment --mode Incremental --template-spec-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0 --validation-level Template

Required Parameters

--location -l

The location to store the deployment metadata.

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 mode that is used to deploy resources.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment.

--parameter -p

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 ARM JSON or .bicepparam parameters file. A .bicepparam file can supply its own template and requires the Bicep CLI. Cannot be combined with --parameters-uri.

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

--subscription-id

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

--template-file

The path to a local ARM JSON or Bicep template. Bicep files require the Bicep CLI for local compilation.

--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 sub what-if

Preview

Preview the changes a subscription scoped deployment would make, without applying them.

Run a subscription scoped what-if operation, mirroring az deployment sub 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 ARM template URL), or --template-spec-id (the resource id of a Template Spec version). A .bicepparam file given to --parameters-file can supply the template on its own. Bicep files are compiled with the Bicep CLI, which must be installed. --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; --location (required) is the region where the deployment metadata is stored; --mode (optional) is the deployment mode, Incremental (default) or Complete; --subscription-id (optional) selects the subscription. Template parameters can be supplied with --parameters-file (a local JSON or .bicepparam 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 is a SAS token or other query string sent on the template link; it requires --template-uri, a leading ? or & is removed, and it is not added to --parameters-uri. --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 sub what-if --location
                          [--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 sub what-if --location eastus --name myDeployment --mode Incremental --template-file ./main.bicep --parameter resourceGroupName=myResourceGroup

Preview a remote ARM template with a remote parameters file

az deployment sub what-if --location eastus --name myDeployment --mode Incremental --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json --subscription-id 00000000-0000-0000-0000-000000000000

Preview a Template Spec returning resource ids only

az deployment sub what-if --location eastus --name myDeployment --mode Incremental --template-spec-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0 --result-format ResourceIdOnly

Required Parameters

--location -l

The location to store the deployment what-if operation metadata.

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 mode that is used to deploy resources.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment.

--parameter -p

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 ARM JSON or .bicepparam parameters file. A .bicepparam file can supply its own template and requires the Bicep CLI. Cannot be combined with --parameters-uri.

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

--result-format -r

The format of the what-if results.

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 JSON or Bicep template. Bicep files require the Bicep CLI for local compilation.

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