Scope functions for Bicep
This article describes the Bicep functions for getting scope values.
managementGroup()
Returns an object with properties from the management group in the current deployment.
managementGroup(identifier)
Returns an object used for setting the scope to a management group.
Namespace: az.
managementGroup()
can only be used on a management group deployments. It returns the current management group for the deployment operation. Use when either getting a scope object or getting properties for the current management group.
managementGroup(identifier)
can be used for any deployment scope, but only when getting the scope object. To retrieve the properties for a management group, you can't pass in the management group identifier.
Parameter | Required | Type | Description |
---|---|---|---|
identifier | No | string | The unique identifier for the management group to deploy to. Don't use the display name for the management group. If you don't provide a value, the current management group is returned. |
An object used for setting the scope
property on a module or extension resource type. Or, an object with the properties for the current management group.
The following example sets the scope for a module to a management group.
param managementGroupIdentifier string
module 'mgModule.bicep' = {
name: 'deployToMG'
scope: managementGroup(managementGroupIdentifier)
}
The next example returns properties for the current management group.
targetScope = 'managementGroup'
var mgInfo = managementGroup()
output mgResult object = mgInfo
It returns:
"mgResult": {
"type": "Object",
"value": {
"id": "/providers/Microsoft.Management/managementGroups/examplemg1",
"name": "examplemg1",
"properties": {
"details": {
"parent": {
"displayName": "Tenant Root Group",
"id": "/providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000000",
"name": "00000000-0000-0000-0000-000000000000"
},
"updatedBy": "00000000-0000-0000-0000-000000000000",
"updatedTime": "2020-07-23T21:05:52.661306Z",
"version": "1"
},
"displayName": "Example MG 1",
"tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
},
"type": "/providers/Microsoft.Management/managementGroups"
}
}
The next example creates a new management group and uses this function to set the parent management group.
targetScope = 'managementGroup'
param mgName string = 'mg-${uniqueString(newGuid())}'
resource newMG 'Microsoft.Management/managementGroups@2023-04-01' = {
scope: tenant()
name: mgName
properties: {
details: {
parent: {
id: managementGroup().id
}
}
}
}
output newManagementGroup string = mgName
resourceGroup()
Returns an object that represents the current resource group.
resourceGroup(resourceGroupName)
And
resourceGroup(subscriptionId, resourceGroupName)
Return an object used for setting the scope to a resource group.
Namespace: az.
The resourceGroup function has two distinct uses. One usage is for setting the scope on a module or extension resource type. The other usage is for getting details about the current resource group. The placement of the function determines its usage. When used to set the scope
property, it returns a scope object.
resourceGroup()
can be used for either setting scope or getting details about the resource group.
resourceGroup(resourceGroupName)
and resourceGroup(subscriptionId, resourceGroupName)
can only be used for setting scope.
Parameter | Required | Type | Description |
---|---|---|---|
resourceGroupName | No | string | The name of the resource group to deploy to. If you don't provide a value, the current resource group is returned. |
subscriptionId | No | string | The unique identifier for the subscription to deploy to. If you don't provide a value, the current subscription is returned. |
When used for setting scope, the function returns an object that is valid for the scope
property on a module or extension resource type.
When used for getting details about the resource group, the function returns the following format:
{
"id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
"name": "{resourceGroupName}",
"type":"Microsoft.Resources/resourceGroups",
"location": "{resourceGroupLocation}",
"managedBy": "{identifier-of-managing-resource}",
"tags": {
},
"properties": {
"provisioningState": "{status}"
}
}
The managedBy property is returned only for resource groups that contain resources that are managed by another service. For Managed Applications, Databricks, and AKS, the value of the property is the resource ID of the managing resource.
The following example scopes a module to a resource group.
param resourceGroupName string
module exampleModule 'rgModule.bicep' = {
name: 'exampleModule'
scope: resourceGroup(resourceGroupName)
}
The next example returns the properties of the resource group.
output resourceGroupOutput object = resourceGroup()
It returns an object in the following format:
{
"id": "/subscriptions/{subscription-id}/resourceGroups/examplegroup",
"name": "examplegroup",
"type":"Microsoft.Resources/resourceGroups",
"location": "southcentralus",
"properties": {
"provisioningState": "Succeeded"
}
}
A common use of the resourceGroup function is to create resources in the same location as the resource group. The following example uses the resource group location for a default parameter value.
param location string = resourceGroup().location
You can also use the resourceGroup function to apply tags from the resource group to a resource. For more information, see Apply tags from resource group.
subscription()
Returns details about the subscription for the current deployment.
subscription(subscriptionId)
Returns an object used for setting the scope to a subscription.
Namespace: az.
The subscription function has two distinct uses. One usage is for setting the scope on a module or extension resource type. The other usage is for getting details about the current subscription. The placement of the function determines its usage. When used to set the scope
property, it returns a scope object.
subscription(subscriptionId)
can only be used for setting scope.
subscription()
can be used for setting scope or getting details about the subscription.
Parameter | Required | Type | Description |
---|---|---|---|
subscriptionId | No | string | The unique identifier for the subscription to deploy to. If you don't provide a value, the current subscription is returned. |
When used for setting scope, the function returns an object that is valid for the scope
property on a module or extension resource type.
When used for getting details about the subscription, the function returns the following format:
{
"id": "/subscriptions/{subscription-id}",
"subscriptionId": "{subscription-id}",
"tenantId": "{tenant-id}",
"displayName": "{name-of-subscription}"
}
The following example scopes a module to the subscription.
module exampleModule 'subModule.bicep' = {
name: 'deployToSub'
scope: subscription()
}
The next example returns the details for a subscription.
output subscriptionOutput object = subscription()
tenant()
Returns an object used for setting the scope to the tenant.
Or
Returns the tenant of the user.
Namespace: az.
tenant()
can be used with any deployment scope. It always returns the current tenant. You can use this function to set the scope for a resource, or to get properties for the current tenant.
An object used for setting the scope
property on a module or extension resource type. Or, an object with properties about the current tenant.
The following example shows a module deployed to the tenant.
module exampleModule 'tenantModule.bicep' = {
name: 'deployToTenant'
scope: tenant()
}
The next example returns the properties for a tenant.
var tenantInfo = tenant()
output tenantResult object = tenantInfo
It returns:
"tenantResult": {
"type": "Object",
"value": {
"countryCode": "US",
"displayName": "Contoso",
"id": "/tenants/00000000-0000-0000-0000-000000000000",
"tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
}
Some resources require setting the tenant ID for a property. Rather than passing the tenant ID as a parameter, you can retrieve it with the tenant function.
resource kv 'Microsoft.KeyVault/vaults@2023-07-01' = {
name: 'examplekeyvault'
location: 'westus'
properties: {
tenantId: tenant().tenantId
...
}
}
To learn more about deployment scopes, see: