Skip to content

README.md

Latest commit

 

History

History
172 lines (140 loc) · 13.2 KB

README.md

File metadata and controls

172 lines (140 loc) · 13.2 KB

AzPolicyFactory — Documentation

Supported Platforms

The following DevOps / CICD platforms are supported:

Azure DevOps Pipelines and GitHub Actions Workflows

Name 📝 ADO Pipeline 📝 GitHub Action Description
Policy Definitions Documentation Documentation Deploys custom Azure Policy definitions to the target Azure environment
Policy Initiatives Documentation Documentation Deploys Azure Policy initiatives (policy sets) to the target Azure environment
Policy Assignments Documentation Documentation Deploys Azure Policy assignments based on environment-specific configuration files
Policy Exemptions Documentation Documentation Deploys Azure Policy exemptions based on environment-specific configuration files

Test and Validation Pipelines and Workflows

  • PR Validation Code Scan: Runs GitHub Super-Linter to validate code quality and syntax in pull requests
  • PR Validation for Policy Assignment Consistency:Validates that policy assignment configurations in development and production environments are consistent and do not contain unintended differences |

Instructions

FAQs

Repository Structure

The repository is organized into the following folders:

Folder Description
.azuredevops/ Azure DevOps pipeline definitions and reusable pipeline templates
    pipelines/ Azure DevOps pipeline YAML definitions for policy deployments and validations
    templates/ Reusable Azure DevOps pipeline stage, job, and task templates
.github/ GitHub-specific configurations including Actions, workflows, and linter settings
    actions/ Custom composite GitHub Actions
    linters/ Linter configuration files used by GitHub Super-Linter (e.g., codespell, textlint, PSScriptAnalyzer)
    workflows/ GitHub Actions workflow definitions for policy deployments, PR code scans, and environment consistency checks
.ps-rule/ PSRule configuration and rule suppression files
.vscode/ Visual Studio Code workspace settings, recommended extensions, and script analyzer configuration
bicep/ Bicep modules and deployment templates for Azure Policy resources
    modules/ Reusable Bicep modules including authorization role assignments and user-defined types
    templates/ Bicep deployment templates for policy definitions, initiatives, assignments, and exemptions
docs/ Project documentation
policyAssignments/ Azure Policy assignment configuration files (JSON), organized by environment
    dev/ Development environment policy assignment configuration files
    prod/ Production environment policy assignment configuration files
policyDefinitions/ Custom Azure Policy definition files, organized by resource type
policyExemptions/ Azure Policy exemption configuration files (JSON), organized by environment
    dev/ Development environment policy exemption configuration files
    prod/ Production environment policy exemption configuration files
policyInitiatives/ Azure Policy initiative (policy set) definition files
scripts/ PowerShell scripts used in CI/CD pipelines and supporting utilities
    pipelines/ PowerShell scripts invoked by CI/CD pipelines for deployment, validation, remediation, and resource management
    support/ Supporting utilities including PSDocs-based documentation generators
tests/ Pester and PSRule test files for validating Bicep templates and policy configurations
    bicep/ Pester tests for validating Bicep templates, modules, and bicepconfig settings
    policyAssignment/ Tests for policy assignment configuration syntax validation and cross-environment consistency checks
    policyExemption/ Tests for policy exemption configuration syntax validation
    policy-integration-tests/ Policy integration tests

Pipeline and Workflow Overview

The repository includes the following CI/CD pipelines and GitHub Actions workflows:

Name 🔗 ADO Pipeline 🔗 GitHub Action Description
Policy Definitions Link Link Deploys custom Azure Policy definitions to the target Azure environment
Policy Initiatives Link Link Deploys Azure Policy initiatives (policy sets) to the target Azure environment
Policy Assignments Link Link Deploys Azure Policy assignments based on environment-specific configuration files
Policy Exemptions Link Link Deploys Azure Policy exemptions based on environment-specific configuration files
PR Validation Code Scan Link Link Runs GitHub Super-Linter to validate code quality and syntax in pull requests
PR Validation for Policy Assignment Consistency Link Link Validates that policy assignment configurations in development and production environments are consistent and do not contain unintended differences
Policy Integration Tests Link Link Tests assigned policies in Dev management group using real resources in Azure and validate the expected results

Configurations

The repository includes the following configuration files:

Name Description
settings.yml Centralized configuration file for pipeline variables and configurations
policy_integration_test_config.jsonc Configuration file for policy integration tests
ps-rule.yml PSRule configuration file
bicepconfig.json Bicep configuration file
markdownlint.json Markdownlint configuration file
.gitignore Git ignore file specifying untracked files and folders
.ps-rule/ PSRule rule suppression files
.vscode/ Visual Studio Code workspace settings, recommended extensions, and script analyzer configuration
.github/linters/ Linter configuration files used by GitHub Super-Linter (e.g., codespell, textlint, PSScriptAnalyzer)

Policy Resources

This repository includes a comprehensive set of Azure Policy resources that can be used as samples, including:

Resource Type Location Description
Policy Definitions policyDefinitions/ Custom Azure Policy definition files
Policy Initiatives policyInitiatives/ Azure Policy initiative (policy set) definition files
Policy Assignments policyAssignments/ Azure Policy assignment configuration files (JSON), organized by environment
Policy Exemptions policyExemptions/ Azure Policy exemption configuration files (JSON), organized by environment

Order of Deployment

The policy resources are recommended to be developed, deployed and tested in the development management group prior to production deployment. The diagram below illustrates the recommended approach for developing and deploying Azure Policy resources in the development management group:

flowchart TD
    start[Start]  -->
    createGitBranch[Create a Git feature branch] -->
    policyCode[Create or Update code for Policy Definitions, Initiatives, Assignments and Exemptions] -->
    policyAssignmentEnvConsistCode[Create or Update Policy Assignment environment consistency configuration file] -->
    policyIntTestCode[Create or Update Policy Integration Tests]-->
    deployPolicyDefDev[Run Policy Definition Pipeline / Workflow from Feature Branch] -->
    deployPolicyInitiativeDev[Run Policy Initiative Pipeline / Workflow from Feature Branch]-->
    deployPolicyAssignmentDev[Run Policy Assignment Pipeline / Workflow from Feature Branch]-->
    deployPolicyExemptionDev[Run Policy Exemption Pipeline / Workflow from Feature Branch]-->
    manualRunIntTest[Manually run Policy Integration Tests if required]
    style start fill:#28F906,stroke:#333,stroke-width:4px
Loading

Once the policy resources are developed and fully tested in the development management group, then follow the recommended approach as shown below to promote the code to the default branch for production deployment:

flowchart TD
    pr[Raise PR]-->prCodeScan[PR Validation - Code Scan]
    pr[Raise PR]-->policyIntTest[PR Validation - Policy Integration Tests]
    pr[Raise PR]-->assignmentEnvConsistency[PR Validation - Policy Assignment Environment Consistency Tests]
    prCodeScan-->prreview[PR Review]
    policyIntTest-->prreview[PR Review]
    assignmentEnvConsistency-->prreview[PR Review]
    prreview-->prmerge[PR Merge]-->Complete
    style pr fill:#28F906,stroke:#333,stroke-width:4px
Loading

Once the code is merged to the default branch, the pipelines and workflows for production deployment are daisy-chained. To start the deployment, manually trigger the Policy Definitions pipeline / workflow, which will then trigger the Policy Initiatives, Policy Assignments, and Policy Exemptions pipelines / workflows in sequence (as shown below).

flowchart TD
    trigger[Manually trigger Policy Definitions pipeline / workflow] -->
    deployPolicyDef[Deploy Policy Definitions] -->
    defSuccess{Success?} -->|Yes|deployPolicyInitiative[Automatically Deploy Policy Initiatives]
    defSuccess-->|No|EndWithError[End with Error]
    deployPolicyInitiative -->
    intSuccess{Success?}-->|Yes|deployPolicyAssignment[Automatically Deploy Policy Assignments]
    intSuccess-->|No|EndWithError
    deployPolicyAssignment -->
    assignSuccess{Success?}-->|Yes|deployPolicyExemption[Automatically Deploy Policy Exemptions]
    assignSuccess-->|No|EndWithError
    deployPolicyExemption-->
    exemptSuccess{Success?}-->|Yes|EndSuccessfully[Completed Successfully]
    exemptSuccess-->|No|EndWithError
    style trigger fill:#28F906,stroke:#333,stroke-width:4px
    style EndSuccessfully fill:#28F906,stroke:#333,stroke-width:4px
    style EndWithError fill:#FF0000,stroke:#333,stroke-width:4px
Loading