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
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
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.
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 sub create
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
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.
The mode that is used to deploy resources.
| 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 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.
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.
Azure Subscription Id. Defaults to the active profile's subscription.
The path to a local ARM JSON or Bicep template. Bicep files require the Bicep CLI for local compilation.
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 sub delete
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
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.
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 sub export
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
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.
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 sub list
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 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 sub show
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
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.
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 sub validate
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
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.
The mode that is used to deploy resources.
| 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 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.
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.
Azure Subscription Id. Defaults to the active profile's subscription.
The path to a local ARM JSON or Bicep template. Bicep files require the Bicep CLI for local compilation.
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 sub what-if
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
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.
The mode that is used to deploy resources.
| 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 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.
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.
The format of the what-if results.
| Property | Value |
|---|---|
| Accepted values: | FullResourcePayloads, ResourceIdOnly |
Azure Subscription Id. Defaults to the active profile's subscription.
The path to a local ARM JSON or Bicep template. Bicep files require the Bicep CLI for local compilation.
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.