|
| 1 | +--- |
| 2 | +title: Deploy resources to tenant |
| 3 | +description: Describes how to deploy resources at the tenant scope in an Azure Resource Manager template. |
| 4 | +ms.topic: conceptual |
| 5 | +ms.date: 03/06/2020 |
| 6 | +--- |
| 7 | + |
| 8 | +# Create resources at the tenant level |
| 9 | + |
| 10 | +Typically, you deploy Azure resources to a resource group in your Azure subscription. However, you can also create resources at the: |
| 11 | + |
| 12 | +* [subscription level](deploy-to-subscription.md) |
| 13 | +* [management group level](deploy-to-management-group.md) |
| 14 | +* tenant level (covered in this article) |
| 15 | + |
| 16 | +You use tenant level deployments to take actions that make sense at that level, such as assigning [role-based access control](../../role-based-access-control/overview.md) or applying [policies](../../governance/policy/overview.md). |
| 17 | + |
| 18 | +## Supported resources |
| 19 | + |
| 20 | +You can deploy the following resource types at the tenant level: |
| 21 | + |
| 22 | +* [deployments](/azure/templates/microsoft.resources/deployments) - for nested templates that deploy to management groups or subscriptions. |
| 23 | +* [policyAssignments](/azure/templates/microsoft.authorization/policyassignments) |
| 24 | +* [policyDefinitions](/azure/templates/microsoft.authorization/policydefinitions) |
| 25 | +* [policySetDefinitions](/azure/templates/microsoft.authorization/policysetdefinitions) |
| 26 | +* [roleAssignments](/azure/templates/microsoft.authorization/roleassignments) |
| 27 | +* [roleDefinitions](/azure/templates/microsoft.authorization/roledefinitions) |
| 28 | + |
| 29 | +### Schema |
| 30 | + |
| 31 | +The schema you use for tenant deployments is different than the schema for resource group deployments. |
| 32 | + |
| 33 | +For templates, use: |
| 34 | + |
| 35 | +```json |
| 36 | +https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json# |
| 37 | +``` |
| 38 | + |
| 39 | +For parameter files, use: |
| 40 | + |
| 41 | +```json |
| 42 | +https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentParameters.json# |
| 43 | +``` |
| 44 | + |
| 45 | +## Required access |
| 46 | + |
| 47 | +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. |
| 48 | + |
| 49 | +The Global Administrator for the Azure Active Directory doesn't automatically have permission to assign roles. To enable template deployments at the tenant scope, the Global Administrator must do the following steps: |
| 50 | + |
| 51 | +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](../../role-based-access-control/elevate-access-global-admin.md). |
| 52 | + |
| 53 | +1. Assign Owner or Contributor to the principal that needs to deploy the templates. |
| 54 | + |
| 55 | + ```azurepowershell-interactive |
| 56 | + New-AzRoleAssignment -SignInName "[userId]" -Scope "/" -RoleDefinitionName "Owner" |
| 57 | + ``` |
| 58 | + |
| 59 | + ```azurecli-interactive |
| 60 | + az role assignment create --assignee "[userId]" --scope "/" --role "Owner" |
| 61 | + ``` |
| 62 | + |
| 63 | +The principal now has the required permissions to deploy the template. |
| 64 | + |
| 65 | +## Deployment commands |
| 66 | + |
| 67 | +The commands for tenant deployments are different than the commands for resource group deployments. |
| 68 | + |
| 69 | +For Azure PowerShell, use [New-AzTenantDeployment](/powershell/module/az.resources/new-aztenantdeployment). |
| 70 | + |
| 71 | +```azurepowershell-interactive |
| 72 | +New-AzTenantDeployment ` |
| 73 | + -Location "West US" ` |
| 74 | + -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/tenant-level-deployments/new-mg/azuredeploy.json |
| 75 | +``` |
| 76 | + |
| 77 | +For REST API, use [Deployments - Create Or Update At Tenant Scope](/rest/api/resources/deployments/createorupdateattenantscope). |
| 78 | + |
| 79 | +## Deployment location and name |
| 80 | + |
| 81 | +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. |
| 82 | + |
| 83 | +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 template named **azuredeploy.json** creates a default deployment name of **azuredeploy**. |
| 84 | + |
| 85 | +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. If you get the error code `InvalidDeploymentLocation`, either use a different name or the same location as the previous deployment for that name. |
| 86 | + |
| 87 | +## Use template functions |
| 88 | + |
| 89 | +For tenant deployments, there are some important considerations when using template functions: |
| 90 | + |
| 91 | +* The [resourceGroup()](template-functions-resource.md#resourcegroup) function is **not** supported. |
| 92 | +* The [subscription()](template-functions-resource.md#subscription) function is **not** supported. |
| 93 | +* The [reference()](template-functions-resource.md#reference) and [list()](template-functions-resource.md#list) functions are supported. |
| 94 | +* Use the [tenantResourceId()](template-functions-resource.md#tenantresourceid) function to get the resource ID for resources that are deployed at tenant level. |
| 95 | + |
| 96 | + For example, to get the resource ID for a policy definition, use: |
| 97 | + |
| 98 | + ```json |
| 99 | + tenantResourceId('Microsoft.Authorization/policyDefinitions/', parameters('policyDefinition')) |
| 100 | + ``` |
| 101 | + |
| 102 | + The returned resource ID has the following format: |
| 103 | + |
| 104 | + ```json |
| 105 | + /providers/{resourceProviderNamespace}/{resourceType}/{resourceName} |
| 106 | + ``` |
| 107 | + |
| 108 | +## Create management group |
| 109 | + |
| 110 | +The [following template](https://github.com/Azure/azure-quickstart-templates/tree/master/tenant-level-deployments/new-mg) creates a management group. |
| 111 | + |
| 112 | +```json |
| 113 | +{ |
| 114 | + "$schema": "https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#", |
| 115 | + "contentVersion": "1.0.0.0", |
| 116 | + "parameters": { |
| 117 | + "mgName": { |
| 118 | + "type": "string", |
| 119 | + "defaultValue": "[concat('mg-', uniqueString(newGuid()))]" |
| 120 | + } |
| 121 | + }, |
| 122 | + "resources": [ |
| 123 | + { |
| 124 | + "type": "Microsoft.Management/managementGroups", |
| 125 | + "apiVersion": "2019-11-01", |
| 126 | + "name": "[parameters('mgName')]", |
| 127 | + "properties": { |
| 128 | + } |
| 129 | + } |
| 130 | + ] |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +## Assign role |
| 135 | + |
| 136 | +The [following template](https://github.com/Azure/azure-quickstart-templates/tree/master/tenant-level-deployments/tenant-role-assignment) assigns a role at the tenant scope. |
| 137 | + |
| 138 | +```json |
| 139 | +{ |
| 140 | + "$schema": "https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#", |
| 141 | + "contentVersion": "1.0.0.0", |
| 142 | + "parameters": { |
| 143 | + "principalId": { |
| 144 | + "type": "string", |
| 145 | + "metadata": { |
| 146 | + "description": "principalId if the user that will be given contributor access to the resourceGroup" |
| 147 | + } |
| 148 | + }, |
| 149 | + "roleDefinitionId": { |
| 150 | + "type": "string", |
| 151 | + "defaultValue": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635", |
| 152 | + "metadata": { |
| 153 | + "description": "roleDefinition for the assignment - default is owner" |
| 154 | + } |
| 155 | + } |
| 156 | + }, |
| 157 | + "variables": { |
| 158 | + // This creates an idempotent guid for the role assignment |
| 159 | + "roleAssignmentName": "[guid('/', parameters('principalId'), parameters('roleDefinitionId'))]" |
| 160 | + }, |
| 161 | + "resources": [ |
| 162 | + { |
| 163 | + "name": "[variables('roleAssignmentName')]", |
| 164 | + "type": "Microsoft.Authorization/roleAssignments", |
| 165 | + "apiVersion": "2019-04-01-preview", |
| 166 | + "properties": { |
| 167 | + "roleDefinitionId": "[tenantResourceId('Microsoft.Authorization/roleDefinitions', parameters('roleDefinitionId'))]", |
| 168 | + "principalId": "[parameters('principalId')]", |
| 169 | + "scope": "/" |
| 170 | + } |
| 171 | + } |
| 172 | + ] |
| 173 | +} |
| 174 | +``` |
| 175 | + |
| 176 | +## Next steps |
| 177 | + |
| 178 | +* To learn about assigning roles, see [Manage access to Azure resources using RBAC and Azure Resource Manager templates](../../role-based-access-control/role-assignments-template.md). |
| 179 | +* To learn about creating Azure Resource Manager templates, see [Authoring templates](template-syntax.md). |
| 180 | +* For a list of the available functions in a template, see [Template functions](template-functions.md). |
0 commit comments