อ่านในภาษาอังกฤษ แก้ไข

แชร์ผ่าน

Tenant deployments with Bicep file

  • บทความ

As your organization matures, you may need to define and assign policies or Azure role-based access control (Azure RBAC) across your Microsoft Entra tenant. With tenant level templates, you can declaratively apply policies and assign roles at a global level.

Training resources

If you would rather learn about deployment scopes through step-by-step guidance, see Deploy resources to subscriptions, management groups, and tenants by using Bicep.

Supported resources

Not all resource types can be deployed to the tenant level. This section lists which resource types are supported.

For Azure role-based access control (Azure RBAC), use:

For nested templates that deploy to management groups, subscriptions, or resource groups, use:

For creating management groups, use:

For creating subscriptions, use:

For managing costs, use:

For configuring the portal, use:

Built-in policy definitions are tenant-level resources, but you can't deploy custom policy definitions at the tenant. For an example of assigning a built-in policy definition to a resource, see tenantResourceId example.

Set scope

To set the scope to tenant, use:

ไบเซ็ป 
targetScope = 'tenant'

Required access

The principal deploying the template must have permissions to create resources at the tenant scope. The principal must have permission to execute the deployment actions (Microsoft.Resources/deployments/*) and to create the resources defined in the template. For example, to create a management group, the principal must have Contributor permission at the tenant scope. To create role assignments, the principal must have Owner permission.

The Global Administrator for the Microsoft Entra ID doesn't automatically have permission to assign roles. To enable template deployments at the tenant scope, the Global Administrator must do the following steps:

  1. Elevate account access so the Global Administrator can assign roles. For more information, see Elevate access to manage all Azure subscriptions and management groups.

  2. Assign Owner or Contributor to the principal that needs to deploy the templates.

    Azure PowerShell 
    New-AzRoleAssignment -SignInName "[userId]" -Scope "/" -RoleDefinitionName "Owner"
    Azure CLI 
    az role assignment create --assignee "[userId]" --scope "/" --role "Owner"

The principal now has the required permissions to deploy the template.

Deployment commands

The commands for tenant deployments are different than the commands for resource group deployments.

For Azure CLI, use az deployment tenant create:

Azure CLI 
az deployment tenant create \
  --name demoTenantDeployment \
  --location WestUS \
  --template-file main.bicep

For more detailed information about deployment commands and options for deploying ARM templates, see:

Deployment location and name

For tenant level deployments, you must provide a location for the deployment. The location of the deployment is separate from the location of the resources you deploy. The deployment location specifies where to store deployment data. Subscription and management group deployments also require a location. For resource group deployments, the location of the resource group is used to store the deployment data.

You can provide a name for the deployment, or use the default deployment name. The default name is the name of the template file. For example, deploying a file named main.bicep creates a default deployment name of main.

For each deployment name, the location is immutable. You can't create a deployment in one location when there's an existing deployment with the same name in a different location. For example, if you create a tenant deployment with the name deployment1 in centralus, you can't later create another deployment with the name deployment1 but a location of westus. If you get the error code InvalidDeploymentLocation, either use a different name or the same location as the previous deployment for that name.

Deployment scopes

In a Bicep file, all resources declared with the resource keyword must be deployed at the same scope as the deployment. For a tenant deployment, this means all resource declarations in the Bicep file must be deployed to the same tenant or as a child or extension resource of a resource in the same tenant as the deployment.

However, this restriction doesn't apply to existing resources. You can reference existing resources at a different scope than the deployment.

To deploy resources at multiple scopes within a single deployment, use modules. Deploying a module triggers a "nested deployment," allowing you to target different scopes. The user deploying the parent Bicep file must have the necessary permissions to initiate deployments at those scopes.

You can deploy a resource from within a tenant scope Bicep file at the following scopes:

Scope to tenant

Resources defined within the Bicep file are applied to the tenant.

ไบเซ็ป 
targetScope = 'tenant'

// create resource at tenant
resource mgName_resource 'Microsoft.Management/managementGroups@2023-04-01' = {
  ...
}

Scope to management group

To target a management group within the tenant, add a module. Use the managementGroup function to set its scope property. Provide the management group name.

ไบเซ็ป 
targetScope = 'tenant'

param managementGroupName string

// create resources at management group level
module  'module.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

Scope to subscription

To target a subscription within the tenant, add a module. Use the subscription function to set its scope property. Provide the subscription ID.

ไบเซ็ป 
targetScope = 'tenant'

param subscriptionID string

// create resources at subscription level
module  'module.bicep' = {
  name: 'deployToSub'
  scope: subscription(subscriptionID)
}

Scope to resource group

To target a resource group within the tenant, add a module. Use the resourceGroup function to set its scope property. Provide the subscription ID and resource group name.

ไบเซ็ป 
targetScope = 'tenant'

param resourceGroupName string
param subscriptionID string

// create resources at resource group level
module  'module.bicep' = {
  name: 'deployToRG'
  scope: resourceGroup(subscriptionID, resourceGroupName)
}

Create management group

The following template creates a management group.

ไบเซ็ป 
targetScope = 'tenant'
param mgName string = 'mg-${uniqueString(newGuid())}'

resource mgName_resource 'Microsoft.Management/managementGroups@2023-04-01' = {
  name: mgName
  properties: {}
}

If your account doesn't have permission to deploy to the tenant, you can still create management groups by deploying to another scope. For more information, see Management group.

Assign role

The following template assigns a role at the tenant scope.

ไบเซ็ป 
targetScope = 'tenant'

@description('principalId of the user that will be given contributor access to the resourceGroup')
param principalId string

@description('roleDefinition for the assignment - default is owner')
param roleDefinitionId string = '8e3af657-a8ff-443c-a75c-2fe8c4bcb635'

var roleAssignmentName = guid(principalId, roleDefinitionId)

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: tenantResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
  }
}

Next steps

To learn about other scopes, see: