Azure-docs: resourceId() does not work when deploying a template against management groups

[carlosnunez-10m]

Summary

Trying to use resourceId() while deploying a template to a management group fails. The deployment cannot locate the resource unless you provide an explicit path to it from the management group scope.

Affected Documentation

https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/azure-resource-manager/templates/deploy-to-management-group.md

Affected Line

The resourceId() function is supported. Use it to get the resource ID for resources that are used at management group level deployments. Don't provide a value for the resource group parameter.

Example Deployment

Consider the deployment below:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "tagName": {
      "type": "string",
      "metadata": {
        "description": "The name of the tag to enforce."
      }
    },
    "deploymentInfoLocation": {
      "type": "string",
      "metadata": {
        "description": "The Azure region to which deployment information about this policy should apply."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policySetDefinitions",
      "name": "example-policy-initiative",
      "apiVersion": "2019-06-01",
      "properties": {
        "description": "An example initiative.",
        "policyType": "Custom",
        "displayName": "Example Policy Initiative",
        "policyDefinitions": [
          {
            "policyDefinitionId": "[resourceId("Microsoft.Authorization/policyDefinitions", "foo")]"
          },
        ]
     }
  ]
}

Furthermore, assume that the "foo" policy definition exists inside of the "foo" management group.

Expected Behavior

Upon running az deployment mg create --template-file ./path/to/this/template --parameters @./path/to/parameters --management-group-id foo, ARM should be able to locate the resource behind the expression [resourceId("Microsoft.Authorization/policyDefinitions", "foo")] and execute the deployment successfully.

Actual Behavior

Instead, one gets something like this:

ERROR: Deployment failed. Correlation ID: 5243d759-3c91-44fc-aea0-3d0dfc60f546. {
  "error": {
    "code": "PolicyDefinitionNotFound",
    "message": "The policy set definition 'tenth-magnitude-example-policy-initiative' request is invalid. The following policy definitions could not be found: '/providers/Microsoft.Authorization/policyDefinitions/foo"

Workaround

One has to provide the full path to the resource they are attempting to locate, i.e. /providers/Microsoft.Management/managementGroups/foo/providers/Microsoft.Authorization/policyDefinitions/foo.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 24ff2a94-83fa-c921-b156-c0e6056d1f7f
• Version Independent ID: bec70adc-7931-e08c-3559-b345601b24ce
• Content: Deploy resources to management group - Azure Resource Manager
• Content Source: articles/azure-resource-manager/templates/deploy-to-management-group.md
• Service: azure-resource-manager
• Sub-service: templates
• GitHub Login: @mumian
• Microsoft Alias: jgao

[KrishnaG-MSFT]

@carlosnunez-10m Thanks for your comment! We will review and provide an update as appropriate.

[SwathiDhanwada-MSFT]

@carlosnunez-10m As per my analysis, the Built-in policy definitions has Resource ID format as /providers/{resourceProviderNamespace}/{resourceType}/{resourceName} where as custom policy definitions has ResourceID format as /providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{ResourceProviderNamespace}/{ResourceType}/{ResourceName}. Seems you are using custom policy definition as reference , so you were prompted with error.I am checking with internal team related to this issue and I will update you soon.

[carlosonunez]

Thanks for looking into this, Swathi. I hope that’s the case, as that isn’t clear by reading the documentation alone.

[tfitzmac]

I believe there is a bug related to resourceId but I am trying to verify it.

[SwathiDhanwada-MSFT]

@tfitzmac I already approached PG regarding this issue. I have looped you in the email.

@carlosonunez We are checking internally with engineering team and we will provide an update soon.

[carlosonunez]

Thank you so much, y’all!

[pmatthews05]

I too am encountering this issue, I have deployed my PolicyDefinitions at the ManagementGroup level, when it comes to reference the Policy Definitions in a policySetDefinitions using [resourceId('Microsoft.Authorization/policyDefinitions', '3aefcff0-e1b7-4fa0-897f-b1d35ca09bb4')], I encounter the error that it cannot find the policy definitions.

Would like to be kept updated too if there is a bug and a fix coming. Happy to help by providing my own information.

[detienne20]

• This is not a bug with the code, but the documentation may need to be updated for greater clarity. In this case, the custom policy definition that resides under the management group is the extension resource. Microsoft.Authorization/policyDefinitions is recognized as an extension resource in these docs: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/extension-resource-types. The resource ID can be retrieved via:

“[extensionResourceId(tenantResourceId(‘Microsoft.Management/managementGroups’, ‘ targetmanagement group name’), ‘Microsoft.Authorization/policyDefinitions’, ‘custom-policy-name’)]”

•For extension resource(s), the scope needs to be specified. For example, you can retrieve a custom policy definition that resides at the subscription scope using:

[subscriptionResourceId(‘subscriptionGUID’, ‘Microsoft.Authorization/policyDefinitions’, ‘custom-policy-name’)]”

•Note: A built-in policy definition resides at the tenant scope and is not an extension resource. You can use:

[tenantResourceId(Microsoft.Authorization/policyDefinitions’, ‘build-in-policy-guid’)] to retrieve the resource ID.

[resourceId(‘Microsoft.Authorization/policyDefinitions’, ‘built-in-policy-guid’)]
will also work to retrieve the resource ID but we do not recommend any reliance on it. In the context of a tenant-level or management level deployment, the subscription ID and resource group ID are both null so the resourceId() function will generate a tenant-level ID. Since the built-in policy definition is a tenant level resource, it works, but it is much better to rely on tenantResourceId () which would work at any scope.

•Additional documentation can be found here: https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource#resourceid

•Example ARM Template:

{
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"targetMG": {
"type": "string",
"metadata": {
"description": "Target Management Group"
}
},
"allowedLocations": {
"type": "array",
"defaultValue": [
"australiaeast",
"australiasoutheast",
"australiacentral"
],
"metadata": {
"description": "An array of the allowed locations, all other locations will be denied by the created policy."
}
}
},
"variables": {
"mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
"policyDefinition": "LocationRestriction"
},
"resources": [
{
"type": "Microsoft.Authorization/policyDefinitions",
"name": "[variables('policyDefinition')]",
"apiVersion": "2019-09-01",
"properties": {
"policyType": "Custom",
"mode": "All",
"parameters": {
},
"policyRule": {
"if": {
"not": {
"field": "location",
"in": "[parameters('allowedLocations')]"
}
},
"then": {
"effect": "deny"
}
}
}
},
{
"type": "Microsoft.Authorization/policyAssignments",
"name": "location-lock",
"apiVersion": "2019-09-01",
"dependsOn": [
"[variables('policyDefinition')]"
],
"properties": {
"scope": "[variables('mgScope')]",
"policyDefinitionId": "[extensionResourceId(variables('mgScope'), 'Microsoft.Authorization/policyDefinitions', variables('policyDefinition'))]"
}
}
]
}

[carlosonunez]

Thanks for the detailed reply, @detienne20!

I didn’t know about these functions. I’m glad that they exist, as I couldn’t find any examples of them being used in the wild. However, the documentation for resourceId insinuates that resourceId should be able to retrieve resource IDs regardless of scope (emphasis mine):

The format of the returned identifier varies based on whether the deployment happens at the scope of a resource group, subscription, management group, or tenant.

[detienne20]

Hi @carlosonunez!

Thank you for your comments on this issue, I know the documentation is a little confusing. i.e. I realize the example for resourceId at the management level is for a built-in policy definition, but this is not explained or specified, which prompts confusion.

The snippet you provided notes that the returned identifier varies based on the deployment scope, not the scope of the resource. This is insinuated here, the format of the return value is provided, as well as how to retrieve the resource ID in other formats. Among those listed is how to retrieve the resource ID for an extension resource - which has another format.

I hope my explanation provides some clarity, apologies for all the confusion. We will be updating the documentation..

Thanks again for bringing this to our attention!

[carlosnunez-10m]

Fair enough. Thanks for all of your help!

[SwathiDhanwada-MSFT]

@tfitzmac @mumian Can you please update the doc with above information ?

[tfitzmac]

Yes, I will work on that update today.

[SwathiDhanwada-MSFT]

Thanks @tfitzmac.

@carlosnunez-10m We will close the issue for now. If there are further questions , please revert and we will be glad to assist you.

[carlosnunez-10m]

Y'all are awesome. Thank you so much!

---

From: SwathiDhanwada-MSFT [e-mail]
Sent: Friday, September 4, 2020 10:26 AM
To: MicrosoftDocs/azure-docs [e-mail]
Cc: Carlos Nunez [e-mail]; Mention [e-mail]
Subject: Re: [MicrosoftDocs/azure-docs] resourceId() does not work when deploying a template against management groups (#61122)

Thanks @tfitzmachttps://github.com/tfitzmac.

@carlosnunez-10mhttps://github.com/carlosnunez-10m We will close the issue for now. If there are further questions , please revert and we will be glad to assist you.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHubhttps://github.com/MicrosoftDocs/azure-docs/issues/61122#issuecomment-687219031, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AQBXIVTMCZXHN3RLN3UVAJDSEEBLHANCNFSM4QEFWAFA.

[tfitzmac]

Here are the docs that were updated to clarify the use of these functions:

• Resource functions for ARM templates
• Create resource groups and resources at the subscription level
• Create resources at the management group level
• Create resources at the tenant level

[carlosnunez-10m]

Amazing. Thank you so much, Tom!

Carlos Nunez
Cloud Architect | 10th Magnitude
www.10thmagnitude.com | carlos.[email protected] | [phone]

---

From: Tom FitzMacken [e-mail]
Sent: Friday, September 4, 2020 12:33:39 PM
To: MicrosoftDocs/azure-docs [e-mail]
Cc: Carlos Nunez [e-mail]; Mention [e-mail]
Subject: Re: [MicrosoftDocs/azure-docs] resourceId() does not work when deploying a template against management groups (#61122)

Here are the docs that were updated to clarify the use of these functions:

• Resource functions for ARM templateshttps://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource
• Create resource groups and resources at the subscription levelhttps://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-to-subscription
• Create resources at the management group levelhttps://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-to-management-group
• Create resources at the tenant levelhttps://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-to-tenant

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHubhttps://github.com/MicrosoftDocs/azure-docs/issues/61122#issuecomment-687286127, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AQBXIVTPKGMQXHWME4HZXPLSEEQHHANCNFSM4QEFWAFA.