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>/
-
Branch from
mainand 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 -
Keep it audit-only unless you are following the audit to enforcement steps in ADR-0001.
- Bump the version in the file's header comment and add a
CHANGEline, like the existing files do. - Open an MR. The
planjob 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 fromDefinitions/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.
-
Create the identity.
π
azure-monitoring: πpolicy-identity.tfresource "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.
-
Let EPAC attach it.
π
azure-service-principals-platform: πpla-tool-epac.tfIn the
sp-pla-tool-epac-deploy-policy-rwblock,azure_role_assignmentshas:{ 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.
-
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 onmain
- Merge the MR.
planruns again onmain. - Press play on
deploy-policy. It is manual on purpose. It does nothing when the plan has no changes. - Let
docsrun. It regeneratesDocs/policy-documentation/grinntec-grinntec-policy-assignments.mdfrom the live state and commits it tomain.
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.
- Edit
azure_role_assignmentsin the matching block. - 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. |