Skip to content

Manage Azure Policy (EPAC)ΒΆ

The engineer's guide to changing Azure Policy with Enterprise Policy as Code (EPAC). Use this runbook to:

  • Change a policy, initiative or assignment.
  • Set up or attach the zero-permission identity id-policy-noperms-001.
  • Deploy the change.
  • Exempt a resource.
  • Change what the EPAC pipeline identities can do.
  • Fix the pipeline when it fails.

For the design (the three-layer model, audit to enforcement), see Azure Policy (EPAC).

Two identities, no roles stage

The pipeline plans as sp-pla-tool-epac-plan-ro (Reader) and deploys as sp-pla-tool-epac-deploy-policy-rw (Resource Policy Contributor, main only). There is no Deploy-RolesPlan stage, and no CI identity can grant roles. Every assignment is DoNotEnforce, and assignments that need an identity use the zero-role id-policy-noperms-001. Never give an assignment a system-assigned identity: EPAC would plan role assignments that nothing can deploy.

The projectsΒΆ

Project Lane Holds
azure-governance-epac Tier 1, CI applies Every policy artefact, in Definitions/.
ci-templates n/a The shared pipeline: epac-pipeline.yml and lib/epac/ (plan.yml, deploy-policy.yml, docs.yml).
azure-service-principals-platform Tier 1, CI applies The two pipeline identities and their federated credentials, in pla-tool-epac.tf.

Change a policy or assignmentΒΆ

πŸ“ azure-governance-epac: πŸ“ƒ Definitions/<type>/<domain>/

  1. Branch from main and edit the file:

    To change Edit
    A custom policy Definitions/policyDefinitions/<domain>/
    A custom initiative (psd-*) Definitions/policySetDefinitions/<domain>/
    An assignment, or an effect Definitions/policyAssignments/<domain>/
    Tenant, root scope or lifecycle settings Definitions/global-settings.jsonc
  2. Keep it audit-only unless you are following the audit to enforcement steps in ADR-0001.

  3. Bump the version in the file's header comment and add a CHANGE line, like the existing files do.
  4. Open an MR. The plan job runs and posts the plan summary as an MR comment.

Check the comment before you ask for review:

  • The changes listed are the ones you expected.
  • No deletes you didn't intend. EPAC runs with strategy: full, so an assignment missing from Definitions/ is deleted from Azure.
  • No "Role assignment changes planned" warning. If you see it, an assignment has a system-assigned identity. Switch it to id-policy-noperms-001.

Use the zero-permission identityΒΆ

Azure requires an identity on any assignment whose policies could deploy or modify (DeployIfNotExists, Modify), even when it is DoNotEnforce. Every such assignment here attaches id-policy-noperms-001. It has no role anywhere, so the policy can report but never change anything.

It takes three pieces, in three projects:

Piece Where Lane
The identity itself, in rg-monitoring-prod azure-monitoring: πŸ“ƒ policy-identity.tf Tier 1, CI applies
Managed Identity Operator on that one identity, so EPAC's deploy identity may attach it azure-service-principals-platform: πŸ“ƒ pla-tool-epac.tf Tier 1, CI applies
The userAssignedIdentity block on each assignment azure-governance-epac: πŸ“ƒ Definitions/policyAssignments/<domain>/ Tier 1, CI applies

Set it up from scratchΒΆ

Only needed if the identity is missing, for example in a new tenant. Apply in this order, or the later steps fail because the identity doesn't exist yet.

  1. Create the identity.

    πŸ“ azure-monitoring: πŸ“ƒ policy-identity.tf

    resource "azurerm_user_assigned_identity" "policy_noperms" {
      name                = "id-policy-noperms-001"
      resource_group_name = module.resource_group.name
      location            = local.location
      tags                = merge(local.identity_alert_tags, { Workload = "policy-identity" })
    }
    

    Give it no role assignments. Merge and apply.

  2. Let EPAC attach it.

    πŸ“ azure-service-principals-platform: πŸ“ƒ pla-tool-epac.tf

    In the sp-pla-tool-epac-deploy-policy-rw block, azure_role_assignments has:

    {
      scope = "/subscriptions/<sub-id>/resourceGroups/rg-monitoring-prod/providers/Microsoft.ManagedIdentity/userAssignedIdentities/id-policy-noperms-001"
      role  = "Managed Identity Operator"
    },
    

    Scope it to the identity only, never the resource group. Merge and apply.

  3. Attach it to each assignment (next section).

Attach it to an assignmentΒΆ

πŸ“ azure-governance-epac: πŸ“ƒ Definitions/policyAssignments/<domain>/<file>.jsonc

Next to "enforcementMode": "DoNotEnforce", add:

// Audit-only: attach the zero-permission identity id-policy-noperms-001
// (azure-monitoring, policy-identity.tf) instead of a system-assigned one.
"userAssignedIdentity": {
    "grinntec": "/subscriptions/<sub-id>/resourceGroups/rg-monitoring-prod/providers/Microsoft.ManagedIdentity/userAssignedIdentities/id-policy-noperms-001"
},

Copy the exact resource ID from an existing assignment, such as regulatorycompliance/pa-reg-Iso27001.jsonc, or from the policy_noperms_identity_id output of azure-monitoring.

Check it worked: the MR plan comment shows the assignment change and no role assignment warning.

Deleting the identity breaks every assignment that uses it

This happened once, when the old t0-azure-service-principals project was removed. If deploy-policy fails because the identity isn't found, recreate it (step 1 above), then re-run the pipeline.


Deploy the changeΒΆ

πŸ“ azure-governance-epac: GitLab pipeline on main

  1. Merge the MR. plan runs again on main.
  2. Press play on deploy-policy. It is manual on purpose. It does nothing when the plan has no changes.
  3. Let docs run. It regenerates Docs/policy-documentation/grinntec-grinntec-policy-assignments.md from the live state and commits it to main.

Check it worked: the new or changed assignment shows in the Azure portal under Policy > Assignments, at mg-intermediate-root, and in the generated docs file.


Exempt a resourceΒΆ

πŸ“ azure-governance-epac: πŸ“ƒ Definitions/policyExemptions/grinntec/exemptions.jsonc

Follow Exempt one resource. In short: one entry, the narrowest scope, an expiry no more than 90 days out, and a CODEOWNER other than you approves. The full rules are in Definitions/policyExemptions/README.md.


Change what the pipeline identities can doΒΆ

πŸ“ azure-service-principals-platform: πŸ“ƒ pla-tool-epac.tf

Both identities are vended here. Don't change them by hand in the portal.

Identity Job Role Federated credential
sp-pla-tool-epac-plan-ro plan, docs Reader at mg-intermediate-root Any branch of the EPAC project (access = "ro")
sp-pla-tool-epac-deploy-policy-rw deploy-policy Resource Policy Contributor at mg-intermediate-root, plus Managed Identity Operator on id-policy-noperms-001 main only (access = "rw")

The solution module builds the federated credentials from access and consuming_gitlab_project_id. Issuer https://gitlab.com, audience api://AzureADTokenExchange, subject project_id:<id>:ref_type:branch:ref:main for -rw.

  1. Edit azure_role_assignments in the matching block.
  2. Open an MR and check the plan.

Don't add a role-granting role

Role Based Access Control Administrator, User Access Administrator or Owner at mg-intermediate-root makes EPAC Tier 0. See Prohibited CI Permissions. If an assignment needs to remediate, give it a user-assigned identity whose roles are granted in Terraform instead.

The client IDs reach the pipeline as the CI/CD variables EPAC_PLAN_CLIENT_ID and EPAC_DEPLOY_POLICY_CLIENT_ID on the EPAC project.


When it failsΒΆ

Symptom Cause Fix
Connect-AzAccount fails with no matching federated identity record deploy-policy ran from a branch other than main, or the project's ID token sub claim isn't project_id, ref_type, ref Run it from main. Check the project's ID token sub claim settings.
Build-DeploymentPlans fails with "unknown Policy name" A policy name or ID in Definitions/ doesn't exist Fix the name. See Manage MCSB Overrides.
MR comment warns Role assignment changes planned An assignment has a system-assigned identity Attach id-policy-noperms-001 instead.
deploy-policy fails because id-policy-noperms-001 isn't found, or can't be attached The identity was deleted, or the Managed Identity Operator grant is missing Set it up from scratch.
deploy-policy fails with AuthorizationFailed The change needs more than Resource Policy Contributor Check the change is policy only. If it really needs more, see Change what the pipeline identities can do.
No MR comment plan only runs on MR pipelines and main, not on a plain branch push Open the MR.