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

[SetTrend]

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.

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.