I’ve been working with Azure Policy for several years now. A couple of jobs ago as a contractor, I created a policy-as-code process using Azure Blueprints (are those even around anymore?). It worked, but man was it clunky. A few years ago, I was asked to help a customer again setup a policy-as-code solution and was recommended one by a coworker. I dove in to it, learned it, and was able to get it up and running. It worked well-ish for a while, but eventually there were enough issues with it that I was asked by the same customer to find an alternative. Enter Enterprise-Policy-as-Code, or EPAC. In addition to “installing” my own POC so I could demo it, and helping the customer set it up and operationalize it, I ended up joining the team that maintains and updates EPAC.

The below guide is not a full guide on how to use EPAC to manage your tenant’s policy. It in no way will help you make decisions about what policy to implement, what to manage with EPAC, how to configure your specific environment, how to author custom policies. It’s not a why you should use Azure Policy article. This is just a quick start guide to setting up EPAC.

At the end of this setup, you will….

• Have an EPAC repository in ADO
• A single pipeline in ADO for deploying to a dev environment/Management Group
• A basic understanding of what is happening during the phases of the EPAC build process
• A basic understanding of the policy update process

Prerequisites

1. An Azure tenant with permissions to create Management Groups and Service Principals.
2. An Azure DevOps (ADO) instance where you are a project administrator of at least one project.

Setup

1. Repo Setup – Clone or download the repository from GitHub and push it to your own repository:
   • Simple instructions for Azure DevOps (ADO):
     1. Download as a zip from https://github.com/Azure/enterprise-azure-policy-as-code (Click the green “Code” button and choose “Download ZIP”).
     2. Create a repository named “EPAC” in ADO with a README.md.
     3. Clone your empty “EPAC” repository to Visual Studio Code (VSCode).
     4. In VSCode, right-click the README.md in the file explorer and choose “Reveal in File Explorer”.
     5. Copy the contents of the zip file from step 1 into the location of the README.md, replacing the existing README with the one from the zip.
     6. Stage, commit, and push to ADO.
     7. Verify that the repository now contains all EPAC files in ADO.
2. Prepare your repository – The necessary folders for a functioning instance of EPAC are Definitions, Pipelines, Schema, and Scripts.
   • In VSCode, go to the “View” menu and select “Terminal”. 
   • Run .\Scripts\HydrationKit\New-HydrationDefinitionsFolder.ps1-DefinitionsRootFolder Definitions (You may need to set the execution policy to allow the script to run: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass).
   • Run .\Scripts\Operations\New-PipelinesFromStarterKit.ps1 -PipelineType AzureDevOps -BranchingFlow GitHub -ScriptType Module.
   • Clean up the repository:
     1. Delete the Docs, Module, and StarterKit folders.
     2. Delete the three “Sync-” files.
   • Stage, commit, and push to ADO.
3. Set up the EPAC environment and Service Principal/Connection – Note: You must have an Azure tenant where you can create Management Groups and Service Principals and assign roles at the created Management Group.
   • Create a Management Group called EPAC-Dev. This will be the root of your EPAC environment for testing

NOTE: Different organizations may have their own policies on how to and what kind of service principals/connections can be created.  Below are two example processes.

Option 1:

• Create a service principal with the owner role at the created Management Group: az ad sp create-for-rbac --name EPAC_Dev --role Owner --scopes /providers/Microsoft.Management/managementGroups/EPAC-Dev.
  1. Copy the output of this command.
• Create a service connection in ADO with this Service Principal:
  1. Go to Project Settings -> Service Connections.
  2. Create a new service connection:
     • Select “Azure Resource Manager”.
     • Choose “Service Principal (manual)”.
     • Set Environment to “Azure Cloud”.
     • Set Scope Level to “Management Group”.
     • Management Group ID: EPAC-Dev.
     • Management Group Name: EPAC-Dev.
     • Service Principal ID: appId from the output in step 2.
     • Service Principal Key: password from the output in step 2.
     • Tenant ID: Tenant from the output in step 2.
  3. Click Verify and fix any issues until verification passes.
  4. Name the service connection “EPAC-Dev”.
  5. Verify and save.

Option 2 (recommended)

• Create a service connection in ADO with App Registration:
  1. Log in to ADO with the credentials that have access to your azure tenant.  The credentials must have Mangement Group read and the ability to manage users/grant roles.
  2. Go to Project Settings -> Service Connections.
  3. Create a new service connection:
     1. Select “Azure Resource Manager”.
     2. Identity type =  App Registration (automatic)
     3. Credential = Workload identity federation”.
     4. Set Scope Level to “Management Group”.
     5. Management Group: EPAC-Dev.
     6. Service connection name:  EPAC-Dev
  4. Press Save and log in to Azure

4. Define your PacEnv – In your repository, update globalSettings.json with your PAC information (replace the tenantID with your tenantID):

    {
        "pacOwnerId": "11111111-2222-3333-4444-555555555555",
        "pacEnvironments": [
            {
                "pacSelector": "epac-dev",
                "cloud": "AzureCloud",
                "tenantId": "xxxx-xxxxxx-xxxxxxx-xxxxxxx",
                "deploymentRootScope": "/providers/Microsoft.Management/managementGroups/EPaC-Dev",
                "managedIdentityLocation": "eastus2",
                "desiredState": {
                    "strategy": "full",
                    "keepDfcSecurityAssignments": false
                },
                "deployedBy": "My Org Admins"
            }
        ]
    }

5. Edit Pipeline – Update your development pipeline (Pipelines\epac-dev-pipeline.yml) with the name of the service connection created in step 3. This will be the “devServiceConnection” variable.

6. Save all changes, commit, and push.

7. Quick verification:

• In VSCode, navigate to Scripts\Deploy\Build-DeploymentPlans.ps1 and click it.
• Press the PowerShell debug icon and start debugging.
• Verify that:
  • It opens a browser window for Azure login (log in at this time).

8. Create some policy objects in Azure (custom policy, custom init, assignments, exemptions)

9. Under scripts/Operations open the Export-AzPolicyResources.ps1 file. Look at some of the sample example commands and run the appropriate command to export from a location in your tenant where you have some customer policies or policy assignments. Note: You may need to create a new PacEnv to point to the root of the location that has these custom policies/assignments.

10. Take some of the exported items (outputs\ folder) and move them to the appropriate folder under Definitions.

11. Check this in and run the deployment pipeline. This will deploy these objects to the root of your test PacEnv.

11. Edit one of the policy objects (change a name, change a parameter name, change the description, etc.) and save that change. Check it in and run the pipeline again.

I hope this helps you get started with EPAC. Please let me know if any of this doesn’t work or isn’t clear so I can make the appropriate updates.

Skål,
   Greg