[Feature]: Deprecate `New-AzDeployment` in favor of `New-AzSubscriptionDeployment`

[SetTrend]

trafficstars

Description of the new feature

Currently, there are four different ARM deployment Cmdlets in the Az PowerShell module, all with their individual scopes:

• New-AzTenantDeployment
• New-AzManagementGroupDeployment
• New-AzDeployment
• New-AzResourceGroupDeployment

From this list is becomes quite obvious that there is something wrong with the New-AzDeployment Cmdlet: It lacks the scope's name!

Sure, there is an alias available, providing the Subscription scope name: New-AzSubscriptionDeployment. Yet, all documentation links etc. are pointing to New-AzDeployment though, which isn't satisfying as there is no indication that New-AzDeployment is in fact a deployment on Subscription level.

Hence, I propose to deprecate New-AzDeployment in favor of New-AzSubscriptionDeployment and, perhaps, make New-AzDeployment merely the new alias for New-AzSubscriptionDeployment.

[dingmeng-xue]

Thanks for reporting. We are also thinking a different approach. Those 4 cmdlets are used for the same purpose but various scope. If the parameters are vey close, we can merge them together and only expose New-AzDeployment for 4 types of scopes.

The change requires documentation update. We will raise this question to service team and content developer.

[msftbot[bot]]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @satyavel, @apclouds.

Issue Details

---

Description of the new feature

Currently, there are four different ARM deployment Cmdlets in the Az PowerShell module, all with their individual scopes:

• New-AzTenantDeployment
• New-AzManagementGroupDeployment
• New-AzDeployment
• New-AzResourceGroupDeployment

From this list is becomes quite obvious that there is something wrong with the New-AzDeployment Cmdlet: It lacks the scope's name!

Sure, there is an alias available, providing the Subscription scope name: New-AzSubscriptionDeployment. Yet, all documentation links etc. are pointing to New-AzDeployment though, which isn't satisfying as there is no indication that New-AzDeployment is in fact a deployment on Subscription level.

Hence, I propose to deprecate New-AzDeployment in favor of New-AzSubscriptionDeployment and, perhaps, make New-AzDeployment merely the new alias for New-AzSubscriptionDeployment.

Author:	SetTrend
Assignees:	-
Labels:	feature-request, Service Attention, ARM - Templates, customer-reported
Milestone:	-

[SetTrend]

Excellent suggestion! I'm looking forward to it.

Thank you.

[ArmaanMcleod]

I think including a scope parameter to New-AzDeployment would be great. It would line up nicely with targetScope from Bicep, and only require us to use one cmdlet to do deployments in the future.

[SetTrend]

Great idea!

I'd go one step further and remove the scope restriction completely from Bicep.

A single Bicep file should be able to build a whole resource group from scratch, including resource group itself, policies etc.

See here: #19147.