Sample - Enforce tag and its value on resource groups

This policy requires a tag and value on a resource group. You specify the required tag name and value.

You can deploy this sample policy using:

If you don't have an Azure subscription, create a free account before you begin.

Sample policy

Policy definition

The complete composed JSON policy definition, used by the REST API, 'Deploy to Azure' buttons, and manually in the portal.

{
   "properties": {
      "displayName": "Enforce tag and its value on resource groups",
      "description": "Enforces a required tag and its value on resource groups.",
      "mode": "All",
      "parameters": {
         "tagName": {
            "type": "String",
            "metadata": {
               "description": "Name of the tag, such as costCenter"
            }
         },
         "tagValue": {
            "type": "String",
            "metadata": {
               "description": "Value of the tag, such as headquarter"
            }
         }
      },
      "policyRule": {
         "if": {
            "allOf": [
               {
                  "field": "type",
                  "equals": "Microsoft.Resources/subscriptions/resourceGroups"
               },
               {
                  "not": {
                     "field": "[concat('tags[',parameters('tagName'), ']')]",
                     "equals": "[parameters('tagValue')]"
                  }
               }
            ]
         },
         "then": {
            "effect": "deny"
         }
      }
   }
}

Note

If manually creating a policy in the portal, use the properties.parameters and properties.policyRule portions of the above. Wrap the two sections together with curly braces {} to make it valid JSON.

Policy rules

The JSON defining the rules of the policy, used by Azure CLI and Azure PowerShell.

{
   "if": {
      "allOf": [
         {
            "field": "type",
            "equals": "Microsoft.Resources/subscriptions/resourceGroups"
         },
         {
            "not": {
               "field": "[concat('tags[',parameters('tagName'), ']')]",
               "equals": "[parameters('tagValue')]"
            }
         }
      ]
   },
   "then": {
      "effect": "deny"
   }
}

Policy parameters

The JSON defining the policy parameters, used by Azure CLI and Azure PowerShell.

{
    "tagName": {
        "type": "String",
        "metadata": {
            "description": "Name of the tag, such as costCenter"
        }
    },
    "tagValue": {
        "type": "String",
        "metadata": {
            "description": "Value of the tag, such as headquarter"
        }
    }
}
Name Type Field Description
tagName String tags Name of the tag, such as costCenter
tagValue String tags Value of the tag, such as headquarter

When creating an assignment via PowerShell or Azure CLI, the parameter values can be passed as JSON in either a string or via a file using -PolicyParameter (PowerShell) or --params (Azure CLI). PowerShell also supports -PolicyParameterObject which requires passing the cmdlet a Name/Value hashtable where Name is the parameter name and Value is the single value or array of values being passed during assignment.

In this example parameter, a tagName of costCenter and tagValue of headquarter is defined.

{
    "tagName": {
        "value": "costCenter"
    },
    "tagValue": {
        "value": "headquarter"
    }
}

Azure portal

Deploy the Policy sample to Azure Deploy the Policy sample to Azure Gov

Azure PowerShell

This sample requires Azure PowerShell. Run Get-Module -ListAvailable Az to find the version. If you need to install or upgrade, see Install Azure PowerShell module.

Run Connect-AzAccount to create a connection with Azure.

Deploy with Azure PowerShell

# Create the Policy Definition (Subscription scope)
$definition = New-AzPolicyDefinition -Name 'enforce-resourceGroup-tags' -DisplayName 'Enforce tag and its value on resource groups' -description 'Enforces a required tag and its value on resource groups.' -Policy 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/ResourceGroup/enforce-resourceGroup-tags/azurepolicy.rules.json' -Parameter 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/ResourceGroup/enforce-resourceGroup-tags/azurepolicy.parameters.json' -Mode All

# Set the scope to a resource group; may also be a resource, subscription, or management group
$scope = Get-AzResourceGroup -Name 'YourResourceGroup'

# Set the Policy Parameter (JSON format)
$policyParam = '{ "tagName": { "value": "costCenter" }, "tagValue": { "value": "headquarter" } }'

# Create the Policy Assignment
$assignment = New-AzPolicyAssignment -Name 'enforce-resourceGroup-tags-assignment' -Scope $scope.ResourceId -PolicyDefinition $definition -PolicyParameter $policyParam

Remove with Azure PowerShell

Run the following commands to remove the previous assignment and definition:

# Remove the Policy Assignment
Remove-AzPolicyAssignment -Id $assignment.ResourceId

# Remove the Policy Definition
Remove-AzPolicyDefinition -Id $definition.ResourceId

Azure PowerShell explanation

The deploy and remove scripts use the following commands. Each command in the following table links to command-specific documentation:

Command Notes
New-AzPolicyDefinition Creates a new Azure Policy definition.
Get-AzResourceGroup Gets a single resource group.
New-AzPolicyAssignment Creates a new Azure Policy assignment. In this example, we provide it a definition, but it can also take an initiative.
Remove-AzPolicyAssignment Removes an existing Azure Policy assignment.
Remove-AzPolicyDefinition Removes an existing Azure Policy definition.

Azure CLI

To run this sample, make sure you have installed the latest version of the Azure CLI. To start, run az login to create a connection with Azure.

This sample works in a Bash shell. For options on running Azure CLI scripts on Windows client, see Install the Azure CLI on Windows.

Deploy with Azure CLI

# Create the Policy Definition (Subscription scope)
definition=$(az policy definition create --name 'enforce-resourceGroup-tags' --display-name 'Enforce tag and its value on resource groups' --description 'Enforces a required tag and its value on resource groups.' --rules 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/ResourceGroup/enforce-resourceGroup-tags/azurepolicy.rules.json' --params 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/ResourceGroup/enforce-resourceGroup-tags/azurepolicy.parameters.json' --mode All)

# Set the scope to a resource group; may also be a resource, subscription, or management group
scope=$(az group show --name 'YourResourceGroup')

# Set the Policy Parameter (JSON format)
policyParam='{ "tagName": { "value": "costCenter" }, "tagValue": { "value": "headquarter" } }'

# Create the Policy Assignment
assignment=$(
az policy assignment create --name 'enforce-resourceGroup-tags-assignment' --display-name 'Enforce tag and its value on resource groups'  --scope `echo $scope | jq '.id' -r` --policy `echo $definition | jq '.name' -r` --params "$policyparam")

Remove with Azure CLI

Run the following commands to remove the previous assignment and definition:

# Remove the Policy Assignment
az policy assignment delete --name `echo $assignment | jq '.name' -r`

# Remove the Policy Definition
az policy definition delete --name `echo $definition | jq '.name' -r`

Azure CLI explanation

Command Notes
az policy definition create Creates a new Azure Policy definition.
az group show Gets a single resource group.
az policy assignment create Creates a new Azure Policy assignment. In this example, we provide it a definition, but it can also take an initiative.
az policy assignment delete Removes an existing Azure Policy assignment.
az policy definition delete Removes an existing Azure Policy definition.

There are several tools that can be used to interact with the Resource Manager REST API such as ARMClient or PowerShell. An example of calling REST API from PowerShell can be found in the Aliases section of Policy definition structure.

REST API

Deploy with REST API

  • Create the Policy Definition (Subscription scope). Use the policy definition JSON for the Request Body.

    PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/enforce-resourceGroup-tags?api-version=2016-12-01
    
  • Create the Policy Assignment (Resource Group scope)

    PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/YourResourceGroup/providers/Microsoft.Authorization/policyAssignments/enforce-resourceGroup-tags-assignment?api-version=2017-06-01-preview
    

    Use the following JSON example for the Request Body:

  {
      "properties": {
          "displayName": "Enforce tag and its value Assignment",
          "policyDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/enforce-resourceGroup-tags",
          "parameters": {
              "tagName": {
                  "value": "costCenter"
              },
              "tagValue": {
                  "value": "headquarter"
              }
          }
      }
  }

Remove with REST API

  • Remove the Policy Assignment

    DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyAssignments/enforce-resourceGroup-tags-assignment?api-version=2017-06-01-preview
    
  • Remove the Policy Definition

    DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/enforce-resourceGroup-tags?api-version=2016-12-01
    

REST API explanation

Service Group Operation Notes
Resource Management Policy Definitions Create Creates a new Azure Policy definition at a subscription. Alternative: Create at management group
Resource Management Policy Assignments Create Creates a new Azure Policy assignment. In this example, we provide it a definition, but it can also take an initiative.
Resource Management Policy Assignments Delete Removes an existing Azure Policy assignment.
Resource Management Policy Definitions Delete Removes an existing Azure Policy definition. Alternative: Delete at management group

Next steps