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

Preview

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

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

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

Preview

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

--location

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.

--name

The name of the deployment. Defaults to a generated GUID when omitted.

--no-wait

Return once the deployment is submitted and output its initial state, instead of waiting for it to finish. Validation still runs first.

--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 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 remote ARM JSON parameters file, including any required SAS token. Cannot be combined with --parameters-file or --parameter.

--profile

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

--query-string

A query string or SAS token for --template-uri only. Requires --template-uri; does not modify --parameters-uri. A leading '?' or '&' is removed.

--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 version. Use instead of another template source.

--template-uri

The URI of a remote ARM JSON template. Supply one template source unless --parameters-file is a .bicepparam file that supplies its own template.

--validation-level

The validation level sent to ARM. When omitted, ARM applies its default.

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

Preview

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

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

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

Preview

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

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

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

Preview

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.

--filter

An OData filter sent to the tenant deployment list API, for example "provisioningState eq 'Succeeded'".

--profile

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

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

Preview

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

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

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 tenant validate

Preview

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

--location

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.

--name

The name of the deployment. Defaults to a generated GUID when omitted.

--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 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 remote ARM JSON parameters file, including any required SAS token. Cannot be combined with --parameters-file or --parameter.

--profile

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

--query-string

A query string or SAS token for --template-uri only. Requires --template-uri; does not modify --parameters-uri. A leading '?' or '&' is removed.

--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 version. Use instead of another template source.

--template-uri

The URI of a remote ARM JSON template. Supply one template source unless --parameters-file is a .bicepparam file that supplies its own template.

--validation-level

The validation level sent to ARM. When omitted, ARM applies its default.

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 tenant wait

Preview

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

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

--created

Wait until the deployment's provisioningState is Succeeded. A missing deployment keeps waiting.

--custom

Wait until this JMESPath condition is true for the deployment's ARM JSON, for example "properties.provisioningState=='Canceled'".

--deleted

Wait until the deployment is deleted.

--exists

Wait until the deployment exists, whatever its provisioningState.

--interval

Polling interval in seconds. Default: 30.

--profile

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

--timeout

Maximum wait in seconds. Default: 3600.

--updated

Wait until the deployment's provisioningState is Succeeded. A missing deployment is an error.

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

Preview

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

--location

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.

--name

The name of the deployment. Defaults to a generated GUID when omitted.

--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 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 remote ARM JSON parameters file, including any required SAS token. Cannot be combined with --parameters-file or --parameter.

--profile

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

--query-string

A query string or SAS token for --template-uri only. Requires --template-uri; does not modify --parameters-uri. A leading '?' or '&' is removed.

--result-format

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

Property Value
Accepted values: FullResourcePayloads, ResourceIdOnly
--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 version. Use instead of another template source.

--template-uri

The URI of a remote ARM JSON template. Supply one template source unless --parameters-file is a .bicepparam file that supplies its own template.

--validation-level

The validation level sent to ARM. When omitted, ARM applies its default.

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.