New-AzResourceGroupDeployment
Deploy an ARM or Bicep template into an existing resource group.
Syntax
Default (Default)
New-AzResourceGroupDeployment
-ResourceGroupName <string>
-Name <string>
[-TemplateUri <string>]
[-TemplateFile <string>]
[-TemplateSpecId <string>]
[-QueryString <string>]
[-ParametersUri <string>]
[-ParametersFile <string>]
[-Mode <string>]
[-Parameter <string[]>]
[-RollbackOnError]
[-RollbackToDeploymentName <string>]
[-ValidationLevel <string>]
[-SubscriptionId <string>]
[-Profile <string>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
Submits a deployment to the specified resource group using an ARM/Bicep template supplied either inline (-TemplateFile), via URL (-TemplateUri), or by referencing a template spec (-TemplateSpecId). Template parameters can be supplied via file, URI, query string, or as Name=Value pairs through -Parameter.
Use -Mode Complete for full reconciliation, or -Mode Incremental (default) to add and update without removing untracked resources.
Examples
Deploy a Bicep file into an existing resource group
Submit main.bicep along with parameter file main.parameters.json as deployment infra-prod-2026-06-16 into resource group myrg.
New-AzResourceGroupDeployment -ResourceGroupName myrg -Name infra-prod-2026-06-16 -TemplateFile ./main.bicep -ParametersFile ./main.parameters.json -Mode Incremental
Parameters
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
Parameter sets
(All)
Position: Named
Mandatory: False
Value from pipeline: False
Value from pipeline by property name: False
Value from remaining arguments: False
-Mode
Deployment mode. Use Incremental (default) to add and update resources, or Complete to delete resources in the resource group that aren't declared in the template.
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
-Name
The name of the deployment. Used to track and reference the deployment in deployment history.
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
-Parameter
Template parameters supplied as inline Name=Value pairs. Use this when you don't have a parameters file. Repeat the flag or pass an array for multiple values.
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).
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
-ParametersUri
URI of a remote ARM/Bicep parameters file (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
-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 or query string appended to -TemplateUri / -ParametersUri when those URIs require authentication.
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
-ResourceGroupName
The name of the resource group that will receive the deployment. The resource group must already exist.
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
-RollbackOnError
If the deployment fails, automatically roll back to the last successful deployment in this resource group.
Parameter properties
Parameter sets
(All)
Position: Named
Mandatory: False
Value from pipeline: False
Value from pipeline by property name: False
Value from remaining arguments: False
-RollbackToDeploymentName
Name of an explicit prior deployment to roll back to on failure. Implies the rollback behaviour of -RollbackOnError.
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 ID that owns the target resource group. 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
-TemplateSpecId
Resource ID of an existing template spec to deploy (for example, /subscriptions/.../providers/Microsoft.Resources/templateSpecs/<spec>/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/Bicep 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. Common values are Provider (default) and Template. 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
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
The target resource group must already exist. Use New-AzResourceGroup to create it first when bootstrapping a new environment.