az deployment sub create: Subscription Deploys

az deployment sub create deploys a template at subscription scope, where resource groups themselves can be created.

Some templates provision resource groups or subscription-level policy. Those run at sub scope, which requires a --location for the deployment metadata.

What it does

az deployment sub create deploys a template scoped to the whole subscription rather than one resource group. Because there is no group to anchor it, you must pass --location for the deployment record. It is the scope used to create resource groups from Bicep.

Common usage

Terminal

az deployment sub create \
  --location eastus \
  --template-file subscription.bicep \
  --parameters @groups.parameters.json
# preview a subscription-scope change
az deployment sub what-if \
  --location eastus --template-file subscription.bicep

Subcommands and flags

Flag	What it does
--location, -l	Region for the deployment metadata (required)
--template-file	Subscription-scope Bicep or ARM template
--parameters	Inline or @file parameters
--what-if	Preview without applying
--name, -n	Name the deployment for later lookup

In CI

Use sub scope to bootstrap an environment: create the resource group and shared resources in one template, then deploy app resources with az deployment group create. The federated identity needs Contributor at subscription scope, which is broader than group scope, so scope the role assignment carefully.

Common errors in CI

"the following arguments are required: --location/-l" means you omitted the mandatory location at sub scope. "AuthorizationFailed" at subscription scope means the identity has group Contributor but not subscription Contributor. "InvalidDeploymentLocation" means a deployment of that name already exists in a different region.