Edit

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

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

-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

Type:SwitchParameter
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

-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

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

The target resource group must already exist. Use New-AzResourceGroup to create it first when bootstrapping a new environment.