Edit

New-AzSubDeployment

Deploy an ARM or Bicep template at the subscription scope.

Syntax

Default (Default)

New-AzSubDeployment
    -Name <string>
    -Location <string>
    -Mode <string>
    [-TemplateUri <string>]
    [-TemplateFile <string>]
    [-TemplateSpecId <string>]
    [-TemplateObject <hashtable>]
    [-QueryString <string>]
    [-ParametersUri <string>]
    [-ParametersFile <string>]
    [-Parameter <string[]>]
    [-ValidationLevel <string>]
    [-SubscriptionId <string>]
    [-Profile <string>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Aliases

This cmdlet has the following aliases, New-AzSubscriptionDeployment

Description

Submits a deployment to the target subscription. Use subscription-scope deployments for resources that live outside a resource group, such as resource groups themselves, policy assignments, and role assignments. The template is supplied as a local ARM JSON or Bicep file (-TemplateFile), a URL (-TemplateUri), a template spec (-TemplateSpecId), or an inline hashtable (-TemplateObject). Bicep files are compiled with the Bicep CLI, which must be installed. Template parameters can be supplied via file (-ParametersFile), URI (-ParametersUri), or as Name=Value pairs through -Parameter. -QueryString supplies a query string for the template URI, not template parameter values. -Mode sets the deployment mode, Incremental or Complete. The cmdlet waits for the deployment to finish and returns the result.

Examples

Deploy a Bicep file at subscription scope

Submit main.bicep with parameter file main.parameters.json as deployment sub-infra-2026-06-16, storing the deployment metadata in eastus.

New-AzSubDeployment -Name sub-infra-2026-06-16 -Location eastus -Mode Incremental -TemplateFile ./main.bicep -ParametersFile ./main.parameters.json

Deploy a local template with inline parameters

Deploy a local ARM JSON template that creates a resource group, and supply its parameters inline.

New-AzSubDeployment -Name create-rg -Location westus2 -Mode Incremental -TemplateFile ./create-rg.json -Parameter rgName=demo-rg, rgLocation=westus2

Deploy a remote template with a remote parameters file

Deploy a template hosted at a URL that creates a resource group as deployment sub-infra-2026-06-16, storing the deployment metadata in eastus.

New-AzSubDeployment -Name sub-infra-2026-06-16 -Location eastus -Mode Incremental -TemplateUri https://contoso.blob.core.windows.net/templates/create-rg.json -ParametersUri https://contoso.blob.core.windows.net/templates/create-rg.parameters.json

Deploy a template spec

Deploy version 1.0 of an existing template spec.

New-AzSubDeployment -Name sub-infra-spec -Location westus2 -Mode Incremental -TemplateSpecId /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0

Parameters

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:SwitchParameter
Supports wildcards:False
DontShow:False
Aliases:cf

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Location

The Azure region that stores the deployment metadata, for example eastus. Subscription-scope deployments have no resource group to inherit a region from, so a location is required.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Mode

The deployment mode, Incremental or Complete.

Parameter properties

Type:String
Accepted values:Incremental, Complete
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Name

The name of the deployment. Used to track and reference the deployment in the subscription's deployment history.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False
Aliases:DeploymentName

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Parameter

Template parameters supplied as inline Name=Value pairs. Use this when you don't have a parameters file. Pass an array for multiple values. Values are parsed as JSON when possible, and otherwise treated as strings. Inline values overlay same-named keys from -ParametersFile and cannot be combined with -ParametersUri.

Parameter properties

Type:

String[]

Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ParametersFile

Path to a local ARM/Bicep parameters file (*.parameters.json or *.bicepparam). A .bicepparam file names its own template through its using declaration, so no template parameter is needed alongside it.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False
Aliases:TemplateParameterFile

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ParametersUri

URI of a remote ARM parameters file (for example, a blob URL). Include any required SAS token in this URI; -QueryString does not modify it.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False
Aliases:TemplateParameterUri

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Profile

Name of a saved profile to use for this call instead of the currently-active one. Manage profiles with Set-AzProfile / Get-AzProfile.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-QueryString

Optional SAS token or query string sent on the template link. Requires -TemplateUri. A leading ? or & is removed. This value is not added to -ParametersUri.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-SubscriptionId

The Azure subscription that owns the deployment. Defaults to the active profile's subscription when omitted.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateFile

Path to a local ARM JSON or Bicep template file.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateObject

An inline ARM template supplied as a hashtable, for example the result of Get-Content ./azuredeploy.json -Raw | ConvertFrom-Json -AsHashtable.

Parameter properties

Type:Hashtable
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateSpecId

Resource ID of an existing template spec version to deploy (for example, /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Resources/templateSpecs/{name}/versions/{version}).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateUri

URI of a remote ARM JSON template (for example, a blob URL).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ValidationLevel

Deployment validation strictness. One of Template, Provider, or ProviderNoRbac. Use a stricter level to catch schema or parameter issues earlier.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-WhatIf

Runs the command in a mode that only reports what would happen without performing the actions.

Parameter properties

Type:SwitchParameter
Supports wildcards:False
DontShow:False
Aliases:wi

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Outputs

Microsoft.Azure.Azclips.Extensions.Resources.Models.DeploymentExtended

The completed DeploymentExtended object containing the deployment name, provisioning state, outputs declared by the template, and correlation ID.

Notes

Subscription-scope templates must use the subscriptionDeploymentTemplate.json schema, or targetScope = 'subscription' in Bicep. Use New-AzResourceGroupDeployment to deploy into a resource group instead.

The legacy Az.Resources name New-AzSubscriptionDeployment and the parameter names -DeploymentName, -TemplateParameterFile, and -TemplateParameterUri are accepted as aliases.