azurerm_management_group_policy_assignment parameters

Manage Azure Policy with Terraform

I am going to reverse the order I would normally explain a concept, in this blog we will look at the call to the module first and then dive into each of the components.

The Module Call

The initiative definition.

Let's step into the initiative definition next.

There are four top-level keys that we have to set:

• name — unique name for the initiative.
• display_name — the name displayed with the initiative.
• description — a description of what the policy is for and does.
• policies — objects containing the value definitions of BuiltIn and Custom policies.

With these properties we will be able to pass in all of the relevant values into our policies for a range of environments, further, we can also set a default if we don't have values specific to an environment. Let's take a look at the two types of policy definitions.

First, let's take a look at the policy properties:

• type — the type of policy that we are referencing; Custom or BuiltIn .
• file — if the policy is Custom we require the name of the file to import. This will be forced into the ${path.root}/policies/ directory by the Terraform code.
• id — the GUID id of an existing Azure policy provided by Microsoft, this is required when type is set to BuiltIn .
• default — the default parameter and effect values.
• dev/uat/prd/... — the key is the environment and the keys must be the same as default , this provides an optional setting of policy parameters by the environment.

Inside the default or environment block we have the following few properties:

• effect — the effect this policy will have, deny as an example. This property cannot be set on BuiltIn policies.

Custom Policy Definition

The key at the beginning AllowedLocations is how we will reference our policy and retrieve its components in the Terraform code. By allowing us to pass in the file to a json file it allows us to easily create custom policies alongside the fantastic baseline policies that Microsoft already give us. In the above example if we were running our Terraform code in the uat environment our code would use the properties we have defined in default as there are no environment-specific overrides. Allowing this makes our Terraform more powerful as perhaps when we start with Azure policy we don't necessarily understand what each environment requires, or they all explicitly require the same types of enforcement.

Built-in Policy Definition

The above is how we would set our parameters for a Built-in Azure policy. Remembering that we cannot set the effect of this policy as that is set by Microsoft, if you did need to alter that effect then it would be best to use a custom policy.

The Custom Policy Definition

We won't go into the mud on how to write an Azure Policy Definition if you're interested in that then check out the Azure Policy definition structure article by Microsoft.

The main point here is that you have a json definition of the Azure Policy either that you have written from scratch or perhaps you're pulling from the Azure portal so that you're now able to change the effect. As you can see on the high-lighted line below the value for the effect key is using string interpolation which will be set by templatefile in our Terraform code later. This is how we are going to be setting the effect on a per-environment basis.

Now we get into the fun stuff 🎉! Whilst going through the module I am going to split it up into some sub-sections to make it easier for us to talk through. Further, the module supports three scopes; Management Group ( mg ), Subscription ( sub ), and Resource Group ( rg ) I will just be referencing the resource group code below as it is almost identical to the other scopes.

The Module Interface .css-1a60e3e{transition-property:var(--chakra-transition-property-common);transition-duration:var(--chakra-transition-duration-fast);transition-timing-function:var(--chakra-transition-easing-ease-out);cursor:pointer;-webkit-text-decoration:none;text-decoration:none;outline:2px solid transparent;outline-offset:2px;color:inherit;font-weight:var(--chakra-fontWeights-normal);opacity:0;margin-left:var(--chakra-space-2);}.css-1a60e3e:hover,.css-1a60e3e[data-hover]{opacity:1;color:var(--chakra-colors-accent-500);-webkit-text-decoration:underline;text-decoration:underline;}.css-1a60e3e:focus,.css-1a60e3e[data-focus]{opacity:1;color:var(--chakra-colors-accent-500);-webkit-text-decoration:underline;text-decoration:underline;} #

If you've worked with me or read my articles before you would know that I treat the variables.tf as our documented API interface, think of it like an OpenAPI definition for a REST API. We will go through each variable one by one.

Our first variable is initiative_definition this is where we pass the full path to our definition yaml file like we discussed in The Initiative Definition .

Secondly, we need to pass in an environment , this must be in whatever format you've used in the initiative definition otherwise our Terraform code won't be able to retrieve the properties for an environment.

The most important input variable for us is the assignment variable, this is where we pass in a single or list of resource IDs we are going to be assigning the policy initiative. Allowing a list of assignments means that we can deal with assignments on a larger scale than a single resource. This is especially powerful when operating in an enterprise environment.

The name property of the assignments object we will use as part of our exemptions process, this ensures there is an easy and intentional lookup for us when we are trying to exempt a resource from a given initiative.

We also have some validation ensuring that the scope passed in is valid for our scenario.

When Azure Policy is concerned there is always going to be a requirement to be able to exempt some resources from having that policy applied/enforced on them. We manage that here through the use of the exemptions variable. This variable allows us to pass in a list of our exemptions object. We have the assignment_reference which as we mentioned above is a reference to name in the assignments object. This allows us to cleanly look up which assignment we are looking to exempt a given resource for.

In this variable, we need to validate that our exemption scope is valid, not only valid for Azure but for our given scenario. For instance, you can exempt a single resource from a policy but our module only supports down to the resource group is the most granular level. The second thing we are validating is that the category on the exemption is one of the two valid strings as expected by Microsoft.

Local Variables and Setup #

The first few pieces of setup that we are going to do is get some random_uuid 's setup that we can use for unique names of our policies, assignments and exemptions. Some properties in the azurerm the provider will auto-generate names for us, and others won't. In this instance, we are going to be dealing with the generation of the names.

Next, we need to decode our initiative_definition yaml into a Terraform object that we can use throughout our module. The policies local variable is a convenience variable for us so that we can quickly access the property. Also, if the way we access the policies object/key from our yaml file changes the code that consumes the policies doesn't need to know about that change.

Policy definitions #

We use an azurerm_policy_definition resource for a Custom policy and the azurerm_policy_definition data source for our BuiltIn policies. Doing so allows us to support both in our module.

When we are creating a Custom policy we have an object that is the filename of a policy json file before creating these policy instances we need to complete the templatefile on each policy. We will loop through our local.policies object and decodes each file to json once the templatefile action has been performed and we have applied the effect either via a default key from our initiative definition or an environment-specific one. This will only occur when the type property is Custom . Then we simply take the properties from our json and plug them into the resource. Some properties such as; metadata , policy_rule , and parameters require to have jsonencode on the object we are retrieving from the policy json as when we do our for_each those are converted into objects that Terraform can deal with.

For the data source, we simply need to loop through our local.policies object and filter to only use objects where the type property is BuiltIn . We do this by using a for expression within the for_each block. You can read more about that in my post Terraform For Expressions .

Policy Initiative #

Now that we have all of our policies in the state we require them its time to create our initiative and pass in the parameter values to each policy.

First off we will merge all our policies, both the resource and the data source. This will give us a single object to operate on. Using the new all_policies object we will get the parameter values, this will be environment specific if available otherwise it will return default . Having a pre-populated property for this allows for easy access within the azurerm_policy_set_definition resource.

Now we have two objects; all_policies and parameters these two combined are what allow us to set up all the policies within the initiative. Using a dynamic block -which you can read more about here - we will iterate over each policy in local.all_policies and assign the parameter_values from the local.parameters variable based on the key from our for_each . This is easily possible as when we created the local.parameters variable we did so by doing a for_each over the local.all_policies variable, this means that both the dynamic block and our parameters variable will use the same value as a key.

Policy Assignment #

The actual policy assignment portion of the module is most likely the simplest part. In this, we simply for through the var.assignment.assignments list and return a map where the key is the name property and the value is the id property of our assignments object.

We do however do a check on scope to ensure that we are operating on the right scope for the right resource type. In this instance the resource group. If we were doing this on azurerm_management_group_policy_assignment the resource then our check would be if var.assignment.scope == "mg" . You can see that in the full module code the terraform-azurerm-policy-initiative repository on my GitHub.

Policy Exemption #

The exemptions are where things get a little funkier, as we need to be able to match zero or more exemptions to the correct assignment.

Our first problem to solve is how we reference the correct Terraform resource block given each assignment type ( mg , sub , rg ) has its own Terraform resource. We do this by using the local variables' ability to reference a resource rather than a string. The try is important as Terraform will try to evaluate each of these even if they're not called which would be fine except that they will never all exist at the same time given assignment can only be done on a single scope.

With the above we can now access the right Terraform resource with the following:

To be honest, the ability to reference other resources with locals is INCREDIBLY powerful!!

Now that we can get the right policy assignment it's time to deal with the exemption side of things. For this, we are going to for through our assignments and our exemptions variables to create a new data structure containing all the relevant pieces of data. The assignment_id key will only ever return one value due to the use of the one function, this behavior is 💯 what we want if there was an instance where there were more than one assignment ID for a specific assignment_reference we would know someone has made a mistake. At this stage, we also validate that the assignment.scope is correct.

You can read more about the for expressions in my Terraform For Expressions post.

The name property is something that we construct out of the random_uuid for the exemptions as well as the last component of the resource ID. In the instance of a resource group that will be the name of the resource group. We also use this same logic to generate the id or key field on our for_each it is because of this that the resource we are referencing must exist before this code is run. If the resource does not exist then Terraform will error out saying that it is unable to determine the value of something that is part of the ID of a map. Whilst this behavior is not ideal I also don't think that it is that bad. The reason being is that should we ever try and exempt a policy on a resource that doesn't exist Terraform/Azure is going to wig out, therefore the behavior is more or less the same just at a different place in the run.

Closing Out #

Today we have gone through a module I've created to deal with creating Azure Policy initiatives. We went through the initiative definition, the custom policy definition and the module itself. By using this module we are now easily able to deploy and manage Azure Policies and exemptions on our cloud platform at scale. We also ensured that we can have the right level of flexibility when it comes to setting the parameter values and the effects on an Azure Policy.

For me, this was not what I would call an easy module to write, as it required me to think about how I could get the most amount of configuration information into the module without making it overly complex to consume. However, going back to My Development Workflow helped me through the process. This module had four iterations before it got to what we have here today.

You can find this module at BrendanThompson/terraform-azurerm-policy-initiative

I would love to hear from you on if you think this module is useful and what you have done to manage something as complex as Azure Policy in your cloud environment!

Search code, repositories, users, issues, pull requests...

Provide feedback.

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly.

To see all available qualifiers, see our documentation .

• Notifications

[Examples] Deploy Management Resources With Custom Settings

This page describes how to deploy your Azure landing zone with the Management resources created in the current Subscription context, using custom configuration settings.

The module supports customizing almost any part of the configuration, however each subset of resources has it's own configuration block which is designed to simplify setting specific options. For the Management resources, this is configured through the configure_management_resources input variable.

In this example, we take the base Deploy Management resources configuration and make the following changes:

• Add input variable on the root module for enabling/disabling Management resources
• Update the retention period for data stored in the Log Analytics workspace from 30 days to 50 days (controlled through an input variable on the root module)
• Set a valid email address for Security alerts (controlled through an input variable on the root module)
• Disable Azure Defender for Azure Kubernetes Service (AKS)
• Set a different location for Management resources (controlled through an input variable on the root module)
• Add custom resource tags for Management resources (controlled through an input variable on the root module)
• Disable deployment of specified monitoring solutions in Azure Monitor ( ServiceMap , SQLAssessment , SQLAdvancedThreatProtection , SQLVulnerabilityAssessment )

The module allows for further customization of the Management resources through the advanced setting, however this is out-of-scope for this example.

Use of the advanced setting is currently undocumented and experimental. Please be aware that using this setting may result in future breaking changes.

If you've already deployed the Management resources using default settings , you will be able to see the changes made when moving to this configuration.

Due to the way the Azure RM Provider manages dependencies, you may see a number of azurerm_role_assignment resources being replaced when updating Policy Assignments. Unfortunately this is a product limitation, but should have minimal impact due to the way Azure Policy works.

If location is not specified, the resources will default to the same location set by default_location input variable.

IMPORTANT: Ensure the module version is set to the latest, and don't forget to run terraform init if upgrading to a later version of the module.

Example root module

To make the code easier to maintain when extending your configuration, we recommend splitting the root module into multiple files. For the purpose of this example, we use the following:

terraform.tf

Variables.tf, settings.management.tf.

TIP: The exact number of resources created depends on the module configuration, but you can expect upwards of 190 resources to be created by the module for this example.

The terraform.tf file is used to set the provider configuration, including pinning to a specific version (or range of versions) for the AzureRM Provider. For production use, we recommend pinning to a specific version, and not using ranges.

If you wish to deploy the Management resources to a different Subscription context than the one used for Core resources, please refer to our guide for Multi-Subscription deployment .

The variables.tf file is used to declare a couple of example variables which are used to customize deployment of this root module. Defaults are provided for simplicity, but these should be replaced or over-ridden with values suitable for your environment.

The main.tf file contains the azurerm_client_config resource, which is used to determine the Tenant ID and Subscription ID values from your user connection to Azure. These are used to ensure the deployment will target your Tenant Root Group by default, and to populate the subscription_id_management input variable.

It also contains the module declaration for this module, containing a number of customizations as needed to meet the specification defined in the overview above.

The settings.management.tf file contains a local variable containing the custom configuration for the configure_management_resources input variable. This helps to keep the module block clean, whilst providing clear separation between settings for different groups of resources.

Deployed Management Groups

You have successfully created the default Management Group resource hierarchy, along with the recommended Azure Policy and Access control (IAM) settings for your Azure landing zone.

You have also assigned the current Subscription from your provider configuration to the management Management Group.

Policy Assignment configuration

Check the following Policy Assignments to see how these have been configured with settings matching your Management resources configuration set by configure_management_resources :

• Audit-UnusedResources
• Deny-Classic-Resources
• Deny-UnmanagedDisk
• Deploy-ASC-Monitoring
• Deploy-AzActivity-Log
• Deploy-MDEndpoints
• Deploy-MDFC-Config
• Deploy-MDFC-OssDb
• Deploy-MDFC-SqlAtp
• Deploy-Resource-Diag
• Deploy-VM-Monitoring
• Deploy-VMSS-Monitoring
• Enforce-ACSB
• Deploy-Log-Analytics

These Policy Assignments should all be assigned with custom parameter values based on your configuration, with enforcement_mode correctly set. Once evaluated, the compliance state should also be updated and you can run remediation tasks to remediate any non-compliant resources.

Policy Assignment parameters example

The following shows the Deploy-AzActivity-Log Policy Assignment with a user-defined value set by the module for the logAnalytics parameter. You will see that this value matches the resource ID of the Log Analytics workspace deployed by this module.

Policy Assignment compliance

When reviewing the Policy Assignment compliance, you will see that some Policies may need remediation.

Deployed Management resources

You should also have the following resources deployed in your assigned Management Subscription:

Additional considerations

If you are using Archetype Exclusions or custom Archetypes in your code, make sure to not disable Log Analytics or Security Center policies if you require policy integration using this module. The relationship between the resources deployed and the Policy parameters is dependent on specific Policy Assignments being used.

Take particular note of the following changes:

The retentionInDays setting is now configured to 50 days on the Log Analytics workspace.

The dataRetention parameter value is also configured to 50 days on the Deploy-Log-Analytics Policy Assignment.

The emailSecurityContact parameter value is set to your own email address on the Deploy-MDFC-Config ( Deploy Azure Security Center configuration ) Policy Assignment. Once this policy is remediated, you can also view this setting in Azure Security Center.

The pricingTierKubernetesService parameter value is set to Free on the Deploy-MDFC-Config ( Deploy Azure Security Center configuration ) Policy Assignment. In Security Center, you should be able to see that Azure Defender is set to On for all resource types except Kubernetes 1 which is set to Off .

1 - Due to a pending feature addition, Azure Defender is also Off for Open-source relational databases . We plan to add this feature in a future release (date TBC).

Although not Policy Assignment related, also note the following changes:

• All Resource Groups and Resources created by the module for Management are now located in uksouth .
• All Resource Groups and Resources ( which support tags ) created by the module for Management have the custom tags applied.

Try updating the configuration settings in the configure_management_resources local variable to see how this changes your configuration. Also try setting your own values in the input variables, and toggling the deploy_management_resources input variable to see which resources are created/destroyed.

To learn more about module configuration using input variables, please refer to the Module Variables documentation.

Looking for further inspiration? Why not try some of our other examples ?

This wiki is being actively developed

If you discover any documentation bugs or would like to request new content, please raise them as an issue or feel free to contribute to the wiki via a pull request . The wiki docs are located in the repository in the docs/wiki/ folder.

Azure landing zones Terraform module

• Getting started
• Module outputs
• Module permissions
• Module variables
• Module releases
• Module upgrade guidance
• Provider configuration
• Archetype definitions
• Core resources
• Management resources
• Connectivity resources
• Identity resources
• Video guides
• Deploy default configuration
• Deploy demo landing zone archetypes
• Deploy custom Landing Zone Archetypes
• Deploy connectivity resources (Hub and Spoke)
• Deploy connectivity resources (Virtual WAN)
• Deploy identity resources
• Deploy management resources
• Assign a built-in policy
• Create and assign custom RBAC roles
• Set parameter values for Policy Assignments
• Deploy connectivity resources with custom settings (Hub and Spoke)
• Deploy connectivity resources with custom settings (Virtual WAN)
• Deploy with Zero Trust network principles (Hub and Spoke)
• Deploy identity resources with custom settings
• Deploy management resources with custom settings
• Expand built-in archetype definitions
• Create custom policies, initiatives and assignments
• Override module role assignments
• Control policy enforcement mode
• Policy assignments with user assigned managed identities
• Deploy using module nesting
• Deploy using multiple module declarations with orchestration
• Deploy using multiple module declarations with remote state
• Frequently Asked Questions
• Troubleshooting
• Raising an issue
• Feature requests
• Contributing to code
• Contributing to documentation

Clone this wiki locally

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

Azure Policy DeployIfNotExists fails to change values with Defender for Servers

I'm currently creating an Azure Policy that (is supposed to) deploys Microsoft Defender for Servers with Plan P1 if the current plan is different. Many subscriptions that I have currently have Microsoft Defender for Servers enabled, but use plan P2 instead of P1, so I created a policy with DeployIfNotExists that should change the values to the correct one, but it is not working as expected.

The policy is as follows (I'm using Terraform):

And the assignment is as follows:

I have also attached the Security Admin role to the System Managed Identity as there seems to be a bug regarding it:

I'm also able to create a remediation task and run it successfully:

All good then, right? Nah.

Maybe there was an error and the parameter is setup as P2 instead of P1? Nope:

Maybe for some reason the deployment didn't run? This is my current thesis, but on the activity log of the values this shows up:

Do you guys have any idea why this might be happening? Any light would be really appreciated :)

Azure Policy An Azure service that is used to implement corporate governance and standards at scale for Azure resources. 788 questions Sign in to follow

Microsoft Defender for Cloud An Azure service that provides threat protection for workloads running in Azure, on-premises, and in other clouds. Previously known as Azure Security Center and Azure Defender. 1,186 questions Sign in to follow

Leonardo Tavares , Thank you for posting this question here with so much of details. It really helped understand the context very well :)

Based on the snippet of policy definition shared above, one of the suggestions I have is to modify the deployment resource template for "DeployIfNotExists".

Based on the ARM template resource definition , API version "2018-06-01" as used in the policy definition did not have the "subPlan" field. The newer API version "2022-03-01" has it though.

You may use the API Versions: drop down list to toggle between the API definition based on versions on this page .

Hope this helps. If you are still facing this issue with the newer version of API, I would request reaching out to Azure Support so that it can be investigated 1:1, as it will require trace analysis from the resource deployment attempts.

If the solution does help, please click Accept answer so that it can help others in the community looking for help on similar topics.

Leonardo Tavares , following up to check if you had a chance to review the response above.

If the answer helped, please click Accept answer so that it can help others in the community looking for help on similar topics.

Hello @AnuragSingh-MSFT , sorry for the delay and thanks for your answer! For some reason I didn't get an email notification.

It worked like a charm! Thanks for the resources on the API versions as well! It will be quite helpful in the future! :)

1 additional answer

I think the issue here is with the ExistenceCondition, can you specify the current state of the Plan instead of parameter? Also in the assignment terraform code it is P1, is this correct value?

Hope this helps.

Please accept as answer and do a Thumbs-up to upvote this response if you are satisfied with the community help. Your upvote will be beneficial for the community users facing similar issues.

Hello @JimmySalian-2011 , thanks for you input!

I don't know if I understand completely what you mean by "specify the current state of the Plan instead of parameter".

I would guess that the ExistenceCondition is not the problem, given that Azure Policy correctly picks it up as a non-complaint resource.

Indeed P1 is the correct value. I want these subscriptions to use the subPlan P1, and currently they use P2.

Thanks again for your answer!

Policy Assignment and managed identity

Were you able to fix this?

Azure Policy Set Definition

This page shows how to write Terraform and Azure Resource Manager for Policy Set Definition and write them securely.

Review your .tf file for Azure best practices

Shisho Cloud, our free checker to make sure your Terraform configuration follows best practices, is available (beta).

azurerm_policy_set_definition (Terraform)

The Set Definition in Policy can be configured in Terraform with the resource name azurerm_policy_set_definition . The following sections describe 10 examples of how to use the resource and its parameters.

• Example Usage from GitHub

Review your Terraform file for Azure best practices

• description optional - string
• display_name required - string
• id optional computed - string
• management_group_id optional computed - string
• management_group_name optional computed - string
• metadata optional computed - string
• name required - string
• parameters optional - string
• policy_definitions optional computed - string
• policy_type required - string
• additional_metadata_resource_id optional - string
• category optional - string
• display_name optional - string
• parameter_values optional computed - string
• parameters optional computed - map from string to string
• policy_definition_id required - string
• policy_group_names optional - set of string
• reference_id optional computed - string
• create optional - string
• delete optional - string
• read optional - string
• update optional - string

>> from Terraform Registry

• Explanation in Terraform Registry

Manages a policy set definition. - > NOTE: Policy set definitions (also known as policy initiatives) do not take effect until they are assigned to a scope using a Policy Set Assignment.

Microsoft.Authorization/policySetDefinitions (Azure Resource Manager)

The policySetDefinitions in Microsoft.Authorization can be configured in Azure Resource Manager with the resource name Microsoft.Authorization/policySetDefinitions . The following sections describe how to use the resource and its parameters.

The Other Related Azure Policy Resources

Azure Policy Assignment

Azure Policy Configuration Policy Assignment

Azure Policy Definition

Azure Policy Policy Assignment

Azure Policy Remediation

Azure Policy Resource Group Policy Assignment

Azure Policy Subscription Policy Assignment

Azure Policy Virtual Machine Configuration Assignment

• Frequently asked questions

What is Azure Policy Set Definition?

Azure Policy Set Definition is a resource for Policy of Microsoft Azure. Settings can be wrote in Terraform.

Where can I find the example code for the Azure Policy Set Definition?

For Terraform, the krishrocks1904/terraform-gets-started , BrettOJ/azuread_adfs_jwt_token and kevinhead/azurerm source code examples are useful. See the Terraform Example section for further details.

For Azure Resource Manager, the Pudding124/RestfulServiceDetect , Pudding124/SwaggerStructure and da-edra/scraping-azure source code examples are useful. See the Azure Resource Manager Example section for further details.

Automate config file reviews on your commits

Fix issues in your infrastructure as code with auto-generated patches.

Table of Contents