☁️ Azure Resource Policy Remediation Terraform Module

Runs an Azure Policy remediation task against a single resource, bringing existing non-compliant resources into line by executing the assigned policy's effect. Targets hashicorp/azurerm ~> 4.0.

• 🔧 Runs a remediation task against exactly one resource -- the narrowest scope Azure offers.
• ⚡ Executes the assigned policy's deployIfNotExists or modify effect — this changes infrastructure.
• 🎚️ Exposes the three blast-radius controls and reports when none of them is set.
• 🌍 Can restrict the task to named Azure regions.
• 🚨 Flags tolerates_total_failure, because failure_percentage is a fraction, not a percentage.
• ⏱️ Documents why ReEvaluateCompliance makes terraform destroy slow — a cancel-and-poll the schema never mentions.

💡 Why it matters: this is the mirror image of a policy exemption. An exemption suppresses evaluation and changes nothing; a remediation reaches into resources Terraform has never managed and modifies them. The two sit next to each other in this library and are easy to confuse.

If this module saved you time:

• ⭐ Star the repository — it genuinely helps other people find it.
• 💼 Connect on LinkedIn — linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee — buymeacoffee.com/microsoftexpert

flowchart TB
    DEF["terraform-azurerm-policy-definition"]
    subgraph assign["Assignments, one module per scope"]
        MGA["terraform-azurerm-management-group-policy-assignment"]
        SUBA["terraform-azurerm-subscription-policy-assignment"]
        RGA["terraform-azurerm-policy-assignment"]
    end
    subgraph remed["Remediations, one module per scope, widest first"]
        MGR["terraform-azurerm-management-group-policy-remediation"]
        SUBR["terraform-azurerm-subscription-policy-remediation"]
        RGR["terraform-azurerm-resource-group-policy-remediation"]
        RESR["terraform-azurerm-resource-policy-remediation"]
    end
    EXEMPT["terraform-azurerm-resource-group-policy-exemption"]
    TARGET["existing resources, CHANGED in place"]
    DEF -->|"only deployIfNotExists or modify can be remediated"| RGA
    DEF -->|"policy_definition_id"| MGA
    DEF -->|"policy_definition_id"| SUBA
    MGA -->|"policy_assignment_id, updatable in place"| MGR
    SUBA -->|"policy_assignment_id, updatable in place"| SUBR
    RGA -->|"policy_assignment_id, updatable in place"| RGR
    RGA -->|"policy_assignment_id, updatable in place"| RESR
    RGR -->|"runs the policy effect against"| TARGET
    RESR -->|"runs the policy effect against"| TARGET
    EXEMPT -.->|"the opposite operation: suppresses evaluation, changes nothing"| RGA
    style RGR fill:#0078D4,stroke:#004578,color:#ffffff
    style RESR fill:#0078D4,stroke:#004578,color:#ffffff
    style RGA fill:#004578,stroke:#004578,color:#ffffff
    style TARGET fill:#8A2B06,stroke:#5C1D04,color:#ffffff
    style MGR fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style SUBR fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style MGA fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style SUBA fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style DEF fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style EXEMPT fill:#F3F2F1,stroke:#8A8886,color:#201F1E

Azure offers remediations at four scopes as four separate resource types, and this library has one module for each. The dotted edge to the exemption module is the contrast worth holding onto: both attach to an assignment, and they do opposite things.

flowchart TB
    SCOPEIN["resource_id: WHERE resources get changed"]
    ASSIGNIN["policy_assignment_id: WHICH effect runs"]
    MODEIN["resource_discovery_mode: also decides how DESTROY behaves"]
    BOUNDS["resource_count, parallel_deployments, failure_percentage"]
    FILTERS["location_filters"]
    THIS["azurerm_resource_policy_remediation.this"]
    EFFECT["deployIfNotExists or modify RUNS against existing resources"]
    FACTS["parsed scope facts and posture flags"]
    RISK["is_unbounded and tolerates_total_failure"]
    CANCEL["destroy may CANCEL and POLL before deleting"]
    SCOPEIN -->|"FORCE-NEW"| THIS
    ASSIGNIN -->|"NOT force-new at any scope, unlike exemptions"| THIS
    MODEIN --> THIS
    BOUNDS -->|"all optional: unset means Azure decides"| THIS
    FILTERS -->|"the only geographic limit"| THIS
    THIS --> EFFECT
    THIS --> FACTS
    THIS --> RISK
    MODEIN -.->|"ReEvaluateCompliance only"| CANCEL
    style THIS fill:#0078D4,stroke:#004578,color:#ffffff
    style EFFECT fill:#8A2B06,stroke:#5C1D04,color:#ffffff
    style RISK fill:#8A2B06,stroke:#5C1D04,color:#ffffff
    style CANCEL fill:#8A2B06,stroke:#5C1D04,color:#ffffff
    style ASSIGNIN fill:#004578,stroke:#004578,color:#ffffff
    style SCOPEIN fill:#004578,stroke:#004578,color:#ffffff
    style MODEIN fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style BOUNDS fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style FILTERS fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style FACTS fill:#F3F2F1,stroke:#8A8886,color:#201F1E

This diagram is shared with terraform-azurerm-resource-policy-remediation, deliberately: the two resources are identical in the schema apart from the name of the scope field.

Schema notes that bite, each confirmed against the provider's own source at the pinned version:

• 🔴 resource_discovery_mode = "ReEvaluateCompliance" changes how DESTROY behaves. The provider must cancel the running task and poll until the cancellation completes before deleting — and it checks the state first, because cancelling a completed remediation returns a 400. Invisible in the schema.
• 🔴 failure_percentage is a FRACTION between 0 and 1, despite the name. 0.1 is ten per cent. 1 is one hundred.
• 🔴 failure_percentage = 0 is silently discarded. The validator accepts it; the expand function only sends the field when it is non-zero. The strictest setting a caller can express becomes Azure's default. This module rejects 0.
• 🔴 policy_assignment_id is NOT force-new at any scope — the opposite of the policy exemption resources, where three of the four scopes replace.
• ⚠️ name must be lower case, because Azure returns it lower-cased and an upper-case name would differ on every plan. The provider enforces this; the reason is only in its source comment.
• ⚠️ The forbidden character set %^#/\&? is the provider's empirical finding, not a published Azure rule — Azure publishes naming rules for assignments, definitions and exemptions, but not for remediations.
• ⚠️ policy_definition_reference_id is a SINGLE string here, where the exemption resources take a list.
• ⚠️ The management-group-scoped remediation has no resource_discovery_mode at all — the one scope of four without it.
• ✅ The default ExistingNonCompliant is already the cheaper, more predictable mode. This module keeps it.
• No tags.

🔴 The permission that does the work is not yours. A remediation executes under the policy assignment's managed identity, using the roles granted to that identity in the assignment. So triggering a remediation is a small permission, and what it then changes is bounded by a different principal's rights entirely. Review both together — terraform-azurerm-policy-assignment emits identity_principal_id for exactly this.

✅ No secret is involved. This resource accepts none and emits none.

• Microsoft.PolicyInsights registered on the subscription.
• An existing policy assignment at or above this scope, whose policy effect is deployIfNotExists or modify. Anything else gives the task nothing to do.
• A managed identity on that assignment, with the roles the effect needs. Without it the remediation runs and fails.
• An evaluation cycle to have run, unless you are using ReEvaluateCompliance.
• A generous delete timeout if you use ReEvaluateCompliance.

terraform-azurerm-resource-policy-remediation/
├── providers.tf    # required_version + pinned azurerm; no provider block
├── variables.tf    # 3 required inputs, 7 optional, 21 validations
├── main.tf         # the keystone `this` + derived locals
├── outputs.tf      # 26 outputs; id first; none sensitive
├── README.md       # this file
├── SCOPE.md        # the cross-module contract
├── LICENSE         # MIT
└── .gitignore      # the canonical library ignore set

provider "azurerm" {
  features {}
}

module "remediate_diagnostics" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-policy-remediation.git?ref=v1.0.0"

  name                 = "remediate-diagnostics"
  resource_id          = "${module.rg.id}/providers/Microsoft.Storage/storageAccounts/observabilitylogs"
  policy_assignment_id = module.deploy_diagnostics.id

  resource_count       = 100
  parallel_deployments = 5
  failure_percentage   = 0.1
}

The caller configures the provider, its authentication and the mandatory features {} block. The module declares none of them.

Consumes

Emits

module "remediation" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-policy-remediation.git?ref=v1.0.0"

  name                 = "remediate-diagnostics"
  resource_id          = var.resource_id
  policy_assignment_id = var.policy_assignment_id
}

resource_count       = 100
parallel_deployments = 5
failure_percentage   = 0.1

failure_percentage = 0.1   # ten per cent

# failure_percentage = 50  # REJECTED: not a percentage
# failure_percentage = 1   # legal, but means ONE HUNDRED per cent

# REJECTED by this module:
failure_percentage = 0

location_filters = ["eastus2", "westus2"]

policy_definition_reference_id = "deployDiagnosticsToStorage"

resource_discovery_mode = "ReEvaluateCompliance"

timeouts = {
  delete = "60m"
}

check "remediation_is_bounded" {
  assert {
    condition     = !module.remediation.is_unbounded
    error_message = "This remediation sets none of resource_count, parallel_deployments or failure_percentage, so Azure decides how much changes."
  }
}

check "remediation_fully_bounded" {
  assert {
    condition     = module.remediation.bounded_control_count == 3
    error_message = "Set all of resource_count, parallel_deployments and failure_percentage before remediating in production."
  }

  assert {
    condition     = !module.remediation.tolerates_total_failure
    error_message = "failure_percentage is 1, which tolerates every remediation failing. Did you mean 0.01?"
  }
}

locals {
  tasks = {
    "remediate-diagnostics" = var.diagnostics_assignment_id
    "remediate-tags"        = var.tags_assignment_id
  }
}

module "remediations" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-policy-remediation.git?ref=v1.0.0"
  for_each = local.tasks

  name                 = each.key
  resource_id          = var.resource_id
  policy_assignment_id = each.value

  resource_count       = 50
  parallel_deployments = 2
  failure_percentage   = 0.05
}

policy_assignment_id = var.new_assignment_id

# All REJECTED:
name = "Remediate-Diagnostics"   # must be lower case
name = "remediate#diagnostics"   # %^#/\&? are not allowed

# This module: exactly one resource, and it never widens.
resource_id = var.resource_id

# REJECTED by this module, though the PROVIDER would accept both:
# resource_id = "/subscriptions/0000.../resourceGroups/rg-prod"   # a resource group
# resource_id = "/subscriptions/0000..."                          # a whole subscription

provider "azurerm" {
  features {}
}

module "rg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name     = "rg-observability"
  location = "eastus2"
}

module "deploy_diagnostics_definition" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-policy-definition.git?ref=v1.0.0"

  name         = "deploy-diagnostics-to-law"
  display_name = "Deploy diagnostic settings to Log Analytics"
}

module "deploy_diagnostics" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-policy-assignment.git?ref=v1.0.0"

  name                 = "deploy-diagnostics"
  resource_group_id    = module.rg.id
  policy_definition_id = module.deploy_diagnostics_definition.id
}

module "grant_remediation_identity" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"

  scope = module.rg.id

  role_assignments = {
    contributor = {
      principal_id         = module.deploy_diagnostics.identity_principal_id
      role_definition_name = "Contributor"
      principal_type       = "ServicePrincipal"
    }
  }
}

module "remediation" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-policy-remediation.git?ref=v1.0.0"

  name                 = "remediate-diagnostics"
  resource_id          = "${module.rg.id}/providers/Microsoft.Storage/storageAccounts/observabilitylogs"
  policy_assignment_id = module.deploy_diagnostics.id

  resource_count       = 100
  parallel_deployments = 5
  failure_percentage   = 0.1
}

check "remediation_is_bounded" {
  assert {
    condition     = !module.remediation.is_unbounded
    error_message = "This remediation is unbounded."
  }
}

No output is sensitive. Nothing about this resource is a credential.

A remediation changes resources; an exemption suppresses evaluation. The two attach to the same policy assignment and sit side by side in this library, and they are opposites. Applying this module reaches into infrastructure Terraform has never managed — resources it has never seen, in whatever state they are in — and runs the assigned policy's deployIfNotExists or modify effect against them. Everything else in the module follows from taking that seriously.

The work is done by somebody else's identity. A remediation executes under the policy assignment's managed identity, with the roles granted to that identity. Creating the remediation is therefore a small permission; what it goes on to change is bounded by a different principal's rights. Reviewing one without the other tells you very little, which is why the composition example puts the role assignment in the same frame and the permissions table names the split explicitly.

Three optional arguments are the only brakes, and the empty call sets none of them. resource_count, parallel_deployments and failure_percentage bound how much changes and how fast. The module cannot choose values on a caller's behalf without inventing numbers, so instead it counts how many were set and emits is_unbounded — making the absence of a decision visible rather than pretending a default is one.

failure_percentage is the sharpest trap on the resource, twice over. It is a fraction despite its name, so 1 means one hundred per cent and is exactly what somebody reaches for when they mean one; the module emits tolerates_total_failure because it cannot reject a legal value. And 0 — the strictest possible setting — passes validation and is then discarded by the expand function, silently substituting Azure's default. That second one the module can reject, and does.

ReEvaluateCompliance reaches into the destroy path. With that mode set and the task still running, the provider cancels the remediation and polls until the cancellation settles before it can delete, checking the state first because cancelling a completed task returns a 400. A terraform destroy is then bounded by the delete timeout rather than being immediate, and a destroy that times out leaves a cancelling task behind. None of this appears in the schema; it is only in the provider's delete body.

The naming rules come from three different authorities, and it is worth knowing which. The 260-character limit is what the service itself reports. The forbidden set %^#/\&? is the provider's own empirical finding, stated as such in its source. And the lower-case requirement exists because Azure returns the name lower-cased, so an upper-case name would produce a difference on every plan — a round-trip trap the provider prevents by refusing the input. Azure publishes naming rules for policy assignments, definitions and exemptions, but not for remediations.

Force-new differs from the neighbouring exemption family. Here policy_assignment_id updates in place at all four scopes. On the exemptions, three of the four scopes replace. Nothing in the schema shows either fact; both come from the ForceNew flags in the Go sources, and a reader who generalises from one family to the other will be wrong.

terraform init -backend=false
terraform validate
terraform fmt -check

Pin the module with ?ref=v1.0.0, never a branch. This library is plan-only: a human applies from CI.

What the offline gate covers:

• terraform validate proves the configuration parses and every type is satisfied.
• terraform fmt -check proves the HCL is canonically formatted.
• Feeding deliberately bad .tfvars through terraform console fires the input validations — all 21 validation blocks in this module have been proven reachable, each by a fixture that triggers it, with zero condition-evaluation errors.
• All 16 derived locals have been driven to more than one value, including is_unbounded and tolerates_total_failure in both states, and a CHILD resource ID proving resource_name takes the last segment while resource_type reports the top-level type.

What only a real plan or apply can exercise:

• Whether the assignment exists, sits at or above this scope, and has a remediable effect.
• Whether its managed identity holds the roles the effect needs.
• How long a ReEvaluateCompliance cancellation actually takes.
• What the remediation changes, which is the part that matters and which no static check can evaluate.

id                              = "/subscriptions/.../resourceGroups/rg-observability/providers/Microsoft.PolicyInsights/remediations/remediate-diagnostics"
name                            = "remediate-diagnostics"
resource_group_name             = "rg-observability"
policy_assignment_id            = "/subscriptions/.../providers/Microsoft.Authorization/policyAssignments/deploy-diagnostics"
resource_discovery_mode         = "ExistingNonCompliant"
re_evaluates_compliance         = false
location_filter_count           = 0
is_region_restricted            = false
resource_count                  = 100
parallel_deployments            = 5
failure_percentage              = 0.1
bounded_control_count           = 3
is_unbounded                    = false
tolerates_total_failure         = false
targets_single_policy_reference = false

• azurerm_resource_policy_remediation — provider resource reference.
• Remediate non-compliant resources — what a remediation task does and which effects it applies to.
• Sibling modules: terraform-azurerm-resource-group-policy-remediation, terraform-azurerm-subscription-policy-remediation, terraform-azurerm-management-group-policy-remediation, terraform-azurerm-policy-assignment, terraform-azurerm-resource-group-policy-exemption.
• This module's SCOPE.md.

💙 "Infrastructure as Code should be standardized, consistent, and secure."