Merge pull request #95214 from tfitzmac/1107mglevel

add management group level

Author: GitHubber17

articles/azure-resource-manager/deploy-to-management-group.md

@@ -0,0 +1,144 @@
+---
+title: Create resources at management group - Azure Resource Manager template
+description: Describes how to deploy resources at the management group scope in an Azure Resource Manager template.
+author: tfitzmac
+ms.service: azure-resource-manager
+ms.topic: conceptual
+ms.date: 11/07/2019
+ms.author: tomfitz
+---
+
+# Create resources at the management group level
+
+Typically, you deploy Azure resources to a resource group in your Azure subscription. However, you can also create resources at the management group level. You use management group 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).
+
+Currently, to deploy templates at the management group level, you must use the REST API.
+
+## Supported resources
+
+You can deploy the following resource types at the management group level:
+
+* [deployments](/azure/templates/microsoft.resources/deployments)
+* [policyAssignments](/azure/templates/microsoft.authorization/policyassignments)
+* [policyDefinitions](/azure/templates/microsoft.authorization/policydefinitions)
+* [policySetDefinitions](/azure/templates/microsoft.authorization/policysetdefinitions)
+* [roleAssignments](/azure/templates/microsoft.authorization/roleassignments)
+* [roleDefinitions](/azure/templates/microsoft.authorization/roledefinitions)
+
+### Schema
+
+The schema you use for management group deployments is different than the schema for resource group deployments.
+
+For templates, use:
+
+```json
+https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#
+```
+
+For parameter files, use:
+
+```json
+https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentParameters.json#
+```
+
+## Deployment commands
+
+The command for management group deployments is different than the command for resource group deployments.
+
+For REST API, use [Deployments - Create At Management Group Scope](/rest/api/resources/deployments/createorupdateatmanagementgroupscope).
+
+## Deployment location and name
+
+For management group 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.
+
+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**.
+
+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.
+
+## Use template functions
+
+For management group deployments, there are some important considerations when using template functions:
+
+* The [resourceGroup()](resource-group-template-functions-resource.md#resourcegroup) function is **not** supported.
+* The [subscription()](resource-group-template-functions-resource.md#subscription) function is **not** supported.
+* The [resourceId()](resource-group-template-functions-resource.md#resourceid) function is supported. Use it to get the resource ID for resources that are used at management group level deployments. For example, get the resource ID for a policy definition with `resourceId('Microsoft.Authorization/roleDefinitions/', parameters('roleDefinition'))`. It returns the resource ID in the format `/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}`.
+* The [reference()](resource-group-template-functions-resource.md#reference) and [list()](resource-group-template-functions-resource.md#list) functions are supported.
+
+## Create policies
+
+### Define policy
+
+The following example shows how to [define](../governance/policy/concepts/definition-structure.md) a policy at the management group level.
+
+```json
+{
+    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
+    "contentVersion": "1.0.0.0",
+    "parameters": {},
+    "variables": {},
+    "resources": [
+        {
+            "type": "Microsoft.Authorization/policyDefinitions",
+            "name": "locationpolicy",
+            "apiVersion": "2018-05-01",
+            "properties": {
+                "policyType": "Custom",
+                "parameters": {},
+                "policyRule": {
+                    "if": {
+                        "field": "location",
+                        "equals": "northeurope"
+                    },
+                    "then": {
+                        "effect": "deny"
+                    }
+                }
+            }
+        }
+    ]
+}
+```
+
+### Assign policy
+
+The following example assigns an existing policy definition to the management group. If the policy takes parameters, provide them as an object. If the policy doesn't take parameters, use the default empty object.
+
+```json
+{
+    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
+    "contentVersion": "1.0.0.0",
+    "parameters": {
+        "policyDefinitionID": {
+            "type": "string"
+        },
+        "policyName": {
+            "type": "string"
+        },
+        "policyParameters": {
+            "type": "object",
+            "defaultValue": {}
+        }
+    },
+    "variables": {},
+    "resources": [
+        {
+            "type": "Microsoft.Authorization/policyAssignments",
+            "name": "[parameters('policyName')]",
+            "apiVersion": "2018-03-01",
+            "properties": {
+                "policyDefinitionId": "[parameters('policyDefinitionID')]",
+                "parameters": "[parameters('policyParameters')]"
+            }
+        }
+    ]
+}
+```
+
+
+
+## Next steps
+
+* 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).
+* For an example of deploying workspace settings for Azure Security Center, see [deployASCwithWorkspaceSettings.json](https://github.com/krnese/AzureDeploy/blob/master/ARM/deployments/deployASCwithWorkspaceSettings.json).
+* To learn about creating Azure Resource Manager templates, see [Authoring templates](resource-group-authoring-templates.md). 
+* For a list of the available functions in a template, see [Template functions](resource-group-template-functions.md).

articles/azure-resource-manager/deploy-to-subscription.md

@@ -4,7 +4,7 @@ description: Describes how to create a resource group in an Azure Resource Manag
 author: tfitzmac
 ms.service: azure-resource-manager
 ms.topic: conceptual
-ms.date: 10/07/2019
+ms.date: 11/07/2019
 ms.author: tomfitz
 ---
 
@@ -18,7 +18,7 @@ To deploy templates at the subscription level, use Azure CLI, PowerShell, or RES
 
 You can deploy the following resource types at the subscription level:
 
-* [deployments](/azure/templates/microsoft.resources/deployments) 
+* [deployments](/azure/templates/microsoft.resources/deployments)
 * [peerAsns](/azure/templates/microsoft.peering/peerasns)
 * [policyAssignments](/azure/templates/microsoft.authorization/policyassignments)
 * [policyDefinitions](/azure/templates/microsoft.authorization/policydefinitions)
@@ -31,12 +31,18 @@ You can deploy the following resource types at the subscription level:
 
 The schema you use for subscription-level deployments is different than the schema for resource group deployments.
 
-For the schema, use:
+For templates, use:
 
 ```json
 https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#
 ```
 
+For parameter files, use:
+
+```json
+https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentParameters.json#
+```
+
 ## Deployment commands
 
 The commands for subscription-level deployments are different than the commands for resource group deployments.
@@ -71,14 +77,14 @@ For subscription level deployments, you must provide a location for the deployme
 
 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**.
 
-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 but 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.
+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.
 
 ## Use template functions
 
 For subscription-level deployments, there are some important considerations when using template functions:
 
 * The [resourceGroup()](resource-group-template-functions-resource.md#resourcegroup) function is **not** supported.
-* The [resourceId()](resource-group-template-functions-resource.md#resourceid) function is supported. Use it to get the resource ID for resources that are used at subscription level deployments. For example, get the resource ID for a policy definition with `resourceId('Microsoft.Authorization/roleDefinitions/', parameters('roleDefinition'))`
+* The [resourceId()](resource-group-template-functions-resource.md#resourceid) function is supported. Use it to get the resource ID for resources that are used at subscription level deployments. For example, get the resource ID for a policy definition with `resourceId('Microsoft.Authorization/roleDefinitions/', parameters('roleDefinition'))`. Or, use the [subscriptionResourceId()](resource-group-template-functions-resource.md#subscriptionresourceid) function to get the resource ID for a subscription level resource.
 * The [reference()](resource-group-template-functions-resource.md#reference) and [list()](resource-group-template-functions-resource.md#list) functions are supported.
 
 ## Create resource groups

articles/azure-resource-manager/resource-group-template-deploy-cli.md

@@ -32,9 +32,11 @@ To deploy to a **subscription**, use [az deployment create](/cli/azure/deploymen
 az deployment create --location <location> --template-file <path-to-template>
 ```
 
-Currently, management group deployments are only supported through the REST API. See [Deploy resources with Resource Manager templates and Resource Manager REST API](resource-group-template-deploy-rest.md).
+For more information about subscription level deployments, see [Create resource groups and resources at the subscription level](deploy-to-subscription.md).
 
-The examples in this article use resource group deployments. For more information about subscription deployments, see [Create resource groups and resources at the subscription level](deploy-to-subscription.md).
+Currently, management group deployments are only supported through the REST API. For more information about management group level deployments, see [Create resources at the management group level](deploy-to-management-group.md).
+
+The examples in this article use resource group deployments.
 
 ## Deploy local template
 

articles/azure-resource-manager/resource-group-template-deploy-rest.md

@@ -29,13 +29,17 @@ To deploy to a **subscription**, use [Deployments - Create At Subscription Scope
 PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-05-01
 ```
 
+For more information about subscription level deployments, see [Create resource groups and resources at the subscription level](deploy-to-subscription.md).
+
 To deploy to a **management group**, use [Deployments - Create At Management Group Scope](/rest/api/resources/deployments/createorupdateatmanagementgroupscope). The request is sent to:
 
 ```HTTP
 PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{groupId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-05-01
 ```
 
-The examples in this article use resource group deployments. For more information about subscription deployments, see [Create resource groups and resources at the subscription level](deploy-to-subscription.md).
+For more information about management group level deployments, see [Create resources at the management group level](deploy-to-management-group.md).
+
+The examples in this article use resource group deployments.
 
 ## Deploy with the REST API
 

articles/azure-resource-manager/resource-group-template-deploy.md

@@ -28,9 +28,11 @@ To deploy to a **subscription**, use [New-AzDeployment](/powershell/module/az.re
 New-AzDeployment -Location <location> -TemplateFile <path-to-template>
 ```
 
-Currently, management group deployments are only supported through the REST API. See [Deploy resources with Resource Manager templates and Resource Manager REST API](resource-group-template-deploy-rest.md).
+For more information about subscription level deployments, see [Create resource groups and resources at the subscription level](deploy-to-subscription.md).
 
-The examples in this article use resource group deployments. For more information about subscription deployments, see [Create resource groups and resources at the subscription level](deploy-to-subscription.md).
+Currently, management group deployments are only supported through the REST API. For more information about management group level deployments, see [Create resources at the management group level](deploy-to-management-group.md).
+
+The examples in this article use resource group deployments.
 
 ## Prerequisites
 

articles/azure-resource-manager/toc.yml

@@ -138,6 +138,8 @@
       href: resource-group-create-multiple.md
     - name: Subscription level resources
       href: deploy-to-subscription.md
+    - name: Management group level resources
+      href: deploy-to-management-group.md
   - name: Deploy templates
     items:
     - name: Deploy - portal