az deployment tenant
Manage ARM deployments at tenant scope.
Commands
| Name | Description | Type | Status |
|---|---|---|---|
| az deployment tenant cancel |
Cancel a running tenant deployment. |
Core | Preview |
| az deployment tenant create |
Create a tenant deployment. |
Core | Preview |
| az deployment tenant delete |
Delete a tenant deployment from the deployment history. |
Core | Preview |
| az deployment tenant export |
Export the template used by a tenant deployment. |
Core | Preview |
| az deployment tenant list |
List tenant deployments. |
Core | Preview |
| az deployment tenant show |
Show a tenant deployment. |
Core | Preview |
| az deployment tenant validate |
Validate a tenant deployment. |
Core | Preview |
| az deployment tenant wait |
Wait until a tenant deployment reaches a condition. |
Core | Preview |
| az deployment tenant what-if |
Preview changes from a tenant deployment. |
Core | Preview |
az deployment tenant cancel
Cancel a running tenant deployment.
Cancels a tenant deployment whose provisioning state is Accepted or Running. Resources the deployment already created are left in place. Azure Resource Manager rejects the request, and the command fails, when the deployment is no longer running.
az deployment tenant cancel --name
[--profile]
Examples
Cancel a running deployment
az deployment tenant cancel --name myDeployment
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).
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 tenant create
Create a tenant deployment.
Create a tenant scoped deployment. The deployment is validated first, then submitted; both requests use Incremental mode, the only mode at tenant scope. Supply one template source: --template-file (a local ARM JSON or Bicep template), --template-uri (a remote ARM JSON template URL), or --template-spec-id (the resource id of a Template Spec version). A .bicepparam file supplied with --parameters-file can provide its own template reference instead. Bicep templates and .bicepparam files require the Bicep CLI for local compilation. --location (required) is where the deployment metadata is stored, and --name is the deployment name; when omitted, a generated GUID is used. Parameters can be supplied with --parameters-file, --parameters-uri, or repeatable inline --parameter values (KEY=VALUE, a JSON object, or a JSON parameters file path, optionally prefixed with @). Inline values override matching keys from a local parameters file. --parameters-uri cannot be combined with --parameters-file or --parameter. --query-string requires --template-uri and applies only to that template link. --validation-level accepts Template, Provider, or ProviderNoRbac; when omitted, ARM applies its default. A validation error stops the command before anything is deployed. By default the command waits for the deployment to finish and returns the final deployment result. With --no-wait, it returns the deployment's initial state as soon as the deployment is submitted; use az deployment tenant show or az deployment tenant wait to follow it.
az deployment tenant create --location
[--name]
[--no-wait]
[--parameter]
[--parameters-file]
[--parameters-uri]
[--profile]
[--query-string]
[--template-file]
[--template-spec-id]
[--template-uri]
[--validation-level {Template, Provider, ProviderNoRbac}]
Examples
Deploy a local Bicep template with inline parameters
az deployment tenant create --location eastus --name myDeployment --template-file ./main.bicep --parameter environment=prod
Deploy a remote ARM template with a remote parameters file
az deployment tenant create --location eastus --name myDeployment --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json
Submit a deployment without waiting for it to finish
az deployment tenant create --location eastus --name myDeployment --template-file ./main.bicep --no-wait
Required Parameters
The location to store the deployment data.
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 name of the deployment. Defaults to a generated GUID when omitted.
Return once the deployment is submitted and output its initial state, instead of waiting for it to finish. Validation still runs first.
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 remote ARM JSON parameters file, including any required SAS token. Cannot be combined with --parameters-file or --parameter.
Use the named profile for this command (overrides the active profile).
A query string or SAS token for --template-uri only. Requires --template-uri; does not modify --parameters-uri. A leading '?' or '&' is removed.
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 version. Use instead of another template source.
The URI of a remote ARM JSON template. Supply one template source unless --parameters-file is a .bicepparam file that supplies its own template.
The validation level sent to ARM. When omitted, ARM applies its default.
| 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 tenant delete
Delete a tenant deployment from the deployment history.
Deletes a deployment and its deployment operations from the tenant deployment history and waits for the deletion to finish. Resources the deployment created are not deleted. A deployment that is still running cannot be deleted.
az deployment tenant delete --name
[--profile]
Examples
Delete a deployment
az deployment tenant delete --name myDeployment
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).
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 tenant export
Export the template used by a tenant deployment.
Exports the template used by a tenant deployment and returns only the template itself, without the template wrapper. The command fails if the service response contains no template.
az deployment tenant export --name
[--profile]
Examples
Export a deployment template
az deployment tenant export --name myDeployment
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).
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 tenant list
List tenant deployments.
Lists deployments recorded at tenant scope, following every page of results. Use --filter to pass an OData filter to the service, for example to restrict results by provisioning state.
az deployment tenant list [--filter]
[--profile]
Examples
List all tenant deployments
az deployment tenant list
List succeeded deployments
az deployment tenant list --filter "provisioningState eq 'Succeeded'"
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
An OData filter sent to the tenant deployment list API, for example "provisioningState eq 'Succeeded'".
Use the named profile for this command (overrides the active profile).
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 tenant show
Show a tenant deployment.
Gets a deployment at tenant scope by name. The command fails if the deployment does not exist.
az deployment tenant show --name
[--profile]
Examples
Show a tenant deployment
az deployment tenant show --name myDeployment
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).
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 tenant validate
Validate a tenant deployment.
Validate whether a template is syntactically correct and would be accepted by Azure Resource Manager at tenant scope, without deploying it. Takes the same template, parameter, --location, and --validation-level inputs as az deployment tenant create; --name defaults to a generated GUID. Validation uses Incremental mode. If the template fails validation, the command reports each error and exits non-zero; otherwise it returns the validation result.
az deployment tenant validate --location
[--name]
[--parameter]
[--parameters-file]
[--parameters-uri]
[--profile]
[--query-string]
[--template-file]
[--template-spec-id]
[--template-uri]
[--validation-level {Template, Provider, ProviderNoRbac}]
Examples
Validate a local Bicep template
az deployment tenant validate --location eastus --name myDeployment --template-file ./main.bicep --parameter environment=prod
Required Parameters
The location to store the deployment data.
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 name of the deployment. Defaults to a generated GUID when omitted.
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 remote ARM JSON parameters file, including any required SAS token. Cannot be combined with --parameters-file or --parameter.
Use the named profile for this command (overrides the active profile).
A query string or SAS token for --template-uri only. Requires --template-uri; does not modify --parameters-uri. A leading '?' or '&' is removed.
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 version. Use instead of another template source.
The URI of a remote ARM JSON template. Supply one template source unless --parameters-file is a .bicepparam file that supplies its own template.
The validation level sent to ARM. When omitted, ARM applies its default.
| 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 tenant wait
Wait until a tenant deployment reaches a condition.
Gets the tenant deployment every --interval seconds (default 30) until the requested condition holds, then returns without output. Supply at least one condition. --created and --updated wait for the provisioning state Succeeded; a missing deployment keeps --created waiting but fails --updated. --deleted waits until the deployment no longer exists. --exists waits until the deployment can be read, whatever its provisioning state. --custom waits until a JMESPath expression evaluated against the deployment's ARM JSON is true, for example properties.provisioningState=='Canceled'. Except with --exists, the command fails as soon as the deployment's provisioning state is Failed. If the condition does not hold within --timeout seconds (default 3600), the command fails.
az deployment tenant wait --name
[--created]
[--custom]
[--deleted]
[--exists]
[--interval]
[--profile]
[--timeout]
[--updated]
Examples
Wait for a deployment to succeed
az deployment tenant wait --name myDeployment --created
Wait for a canceled deployment, polling every 10 seconds
az deployment tenant wait --name myDeployment --custom "properties.provisioningState=='Canceled'" --interval 10
Wait for a deployment to be deleted
az deployment tenant wait --name myDeployment --deleted --timeout 600
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.
Wait until the deployment's provisioningState is Succeeded. A missing deployment keeps waiting.
Wait until this JMESPath condition is true for the deployment's ARM JSON, for example "properties.provisioningState=='Canceled'".
Wait until the deployment is deleted.
Wait until the deployment exists, whatever its provisioningState.
Polling interval in seconds. Default: 30.
Use the named profile for this command (overrides the active profile).
Maximum wait in seconds. Default: 3600.
Wait until the deployment's provisioningState is Succeeded. A missing deployment is an error.
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 tenant what-if
Preview changes from a tenant deployment.
Run a tenant scoped what-if operation. What-if is read-only: it predicts the set of changes (Create, Modify, Delete, Deploy, NoChange, Ignore) a template would make without creating or modifying any resources. Takes the same template, parameter, --location, and --validation-level inputs as az deployment tenant create, and always uses Incremental mode. --result-format selects how much detail the predicted changes carry, FullResourcePayloads (default) or ResourceIdOnly. The command waits for the what-if operation to finish and returns the what-if result; if the operation fails, the command reports the error and exits non-zero.
az deployment tenant what-if --location
[--name]
[--parameter]
[--parameters-file]
[--parameters-uri]
[--profile]
[--query-string]
[--result-format {FullResourcePayloads, ResourceIdOnly}]
[--template-file]
[--template-spec-id]
[--template-uri]
[--validation-level {Template, Provider, ProviderNoRbac}]
Examples
Preview a local Bicep template
az deployment tenant what-if --location eastus --name myDeployment --template-file ./main.bicep --parameter environment=prod
Preview resource IDs only
az deployment tenant what-if --location eastus --name myDeployment --template-file ./main.bicep --result-format ResourceIdOnly
Required Parameters
The location to store the deployment data.
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 name of the deployment. Defaults to a generated GUID when omitted.
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 remote ARM JSON parameters file, including any required SAS token. Cannot be combined with --parameters-file or --parameter.
Use the named profile for this command (overrides the active profile).
A query string or SAS token for --template-uri only. Requires --template-uri; does not modify --parameters-uri. A leading '?' or '&' is removed.
The format of the what-if results. FullResourcePayloads (default) or ResourceIdOnly.
| Property | Value |
|---|---|
| Accepted values: | FullResourcePayloads, ResourceIdOnly |
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 version. Use instead of another template source.
The URI of a remote ARM JSON template. Supply one template source unless --parameters-file is a .bicepparam file that supplies its own template.
The validation level sent to ARM. When omitted, ARM applies its default.
| 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.