az deployment mg

Manage ARM deployments at management-group scope.

Commands

Name Description Type Status
az deployment mg cancel

Cancel a running management-group deployment.

Core Preview
az deployment mg create

Create a management-group deployment.

Core Preview
az deployment mg delete

Delete a management-group deployment from deployment history.

Core Preview
az deployment mg export

Export the template from a management-group deployment.

Core Preview
az deployment mg list

List management-group deployments.

Core Preview
az deployment mg show

Show a management-group deployment.

Core Preview
az deployment mg validate

Validate a management-group deployment.

Core Preview
az deployment mg what-if

Preview changes from a management-group deployment.

Core Preview

az deployment mg cancel

Preview

Cancel a running management-group deployment.

Cancels a management-group deployment whose provisioning state is Accepted or Running.

az deployment mg cancel --management-group-id
                        --name
                        [--profile]

Examples

Cancel a running deployment

az deployment mg cancel --management-group-id myManagementGroup --name myDeployment

Required Parameters

--management-group-id

The management group id.

--name

The deployment name.

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

Preview

Create a management-group deployment.

Create a management group scoped deployment. The deployment is validated first using Incremental mode, then submitted using the selected deployment mode. 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. --management-group-id (required) is the management group to deploy to, --location (required) is where the deployment metadata is stored, and --name (optional) is the deployment name, derived from the template file or URI name when omitted, or generated if no valid name can be derived. 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; include any required SAS token directly in --parameters-uri. --mode selects the actual deployment mode, Incremental (default) or Complete; ARM determines whether the mode is supported at this scope. Validation before deployment always uses Incremental and does not validate Complete mode. --validation-level accepts Template, Provider, or ProviderNoRbac; when omitted, ARM applies its default. The command waits for the deployment to finish and returns the final deployment result.

az deployment mg create --location
                        --management-group-id
                        [--mode {Incremental, Complete}]
                        [--name]
                        [--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 mg create --management-group-id myManagementGroup --location eastus --name myDeployment --template-file ./main.bicep --parameter environment=prod

Deploy a remote ARM template with a remote parameters file

az deployment mg create --management-group-id myManagementGroup --location eastus --name myDeployment --template-uri https://example.com/azuredeploy.json --parameters-uri https://example.com/azuredeploy.parameters.json

Required Parameters

--location

The location to store the deployment data.

--management-group-id

The management group id.

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 sent to ARM for the actual deployment: Incremental (default) or Complete. Validation before deployment always uses Incremental.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment.

--parameter

Deployment parameter(s) (repeatable): KEY=VALUE, a raw JSON object, or a path to a JSON parameters file (optionally prefixed with '@'). Values are parsed as JSON when possible (count=3 a number, flag=true a bool), else treated as strings; quote to force a string (e.g. zip="01234"). Overlay same-named keys from a parameters file. Cannot be combined with parameters-uri.

--parameters-file

The path to a local 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 mg delete

Preview

Delete a management-group deployment from deployment history.

Deletes a management-group deployment and its operations from deployment history.

az deployment mg delete --management-group-id
                        --name
                        [--profile]

Examples

Delete deployment history

az deployment mg delete --management-group-id myManagementGroup --name myDeployment

Required Parameters

--management-group-id

The management group id.

--name

The deployment name.

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

Preview

Export the template from a management-group deployment.

Exports the ARM template used by a management-group deployment.

az deployment mg export --management-group-id
                        --name
                        [--profile]

Examples

Export a deployment template

az deployment mg export --management-group-id myManagementGroup --name myDeployment

Required Parameters

--management-group-id

The management group id.

--name

The deployment name.

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

Preview

List management-group deployments.

Lists deployments recorded at the specified management-group scope. Use --filter to restrict results by provisioning state.

az deployment mg list --management-group-id
                      [--filter]
                      [--profile]

Examples

List succeeded deployments

az deployment mg list --management-group-id myManagementGroup --filter "provisioningState eq 'Succeeded'"

Required Parameters

--management-group-id

The management group id.

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 management-group 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 mg show

Preview

Show a management-group deployment.

Gets one management-group deployment by management group ID and deployment name.

az deployment mg show --management-group-id
                      --name
                      [--profile]

Examples

Show a deployment

az deployment mg show --management-group-id myManagementGroup --name myDeployment

Required Parameters

--management-group-id

The management group id.

--name

The deployment name.

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

Preview

Validate a management-group deployment.

Validate whether a template would be accepted for a management group scoped deployment, without creating any resources. Takes the same template, parameter, and --validation-level inputs as az deployment mg create. Validation always uses Incremental mode, even if --mode Complete is supplied. --name is optional and defaults to the template file or URI name without its extension, or a generated GUID when no valid name can be derived. Returns the validation result on success; on failure the command reports the validation errors and exits non-zero.

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

Examples

Validate a Bicep template

az deployment mg validate --management-group-id myManagementGroup --location eastus --template-file ./main.bicep

Validate a remote template with a parameters file

az deployment mg validate --management-group-id myManagementGroup --location eastus --name myDeployment --template-uri https://example.com/azuredeploy.json --parameters-file ./azuredeploy.parameters.json --validation-level Template

Required Parameters

--location

The location to store the deployment data.

--management-group-id

The management group id.

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

Accepted for compatibility with create. Does not change validation mode: validation always uses Incremental, even when Complete is supplied.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment. Defaults to the template file or URI name without its extension, or a generated GUID when no valid name can be derived.

--parameter

Deployment parameter(s) (repeatable): KEY=VALUE, a raw JSON object, or a path to a JSON parameters file (optionally prefixed with '@'). Values are parsed as JSON when possible (count=3 a number, flag=true a bool), else treated as strings; quote to force a string (e.g. zip="01234"). Overlay same-named keys from a parameters file. Cannot be combined with parameters-uri.

--parameters-file

The path to a local 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 mg what-if

Preview

Preview changes from a management-group deployment.

Run a management group 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, and --validation-level inputs as az deployment mg create. What-if always uses Incremental mode, even if --mode Complete is supplied. --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 mg what-if --location
                         --management-group-id
                         [--mode {Incremental, Complete}]
                         [--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 mg what-if --management-group-id myManagementGroup --location eastus --name myDeployment --template-file ./main.bicep --parameter environment=prod

Preview resource IDs only

az deployment mg what-if --management-group-id myManagementGroup --location eastus --name myDeployment --template-file ./main.bicep --result-format ResourceIdOnly

Required Parameters

--location

The location to store the deployment data.

--management-group-id

The management group id.

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

Accepted for compatibility with create. Does not change what-if mode: what-if always uses Incremental, even when Complete is supplied.

Property Value
Accepted values: Incremental, Complete
--name

The name of the deployment.

--parameter

Deployment parameter(s) (repeatable): KEY=VALUE, a raw JSON object, or a path to a JSON parameters file (optionally prefixed with '@'). Values are parsed as JSON when possible (count=3 a number, flag=true a bool), else treated as strings; quote to force a string (e.g. zip="01234"). Overlay same-named keys from a parameters file. Cannot be combined with parameters-uri.

--parameters-file

The path to a local 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.