From 86ddef06b27f95a5b425f41cb29a93c173891703 Mon Sep 17 00:00:00 2001 From: "Heinrich Gantenbein (techlake)" Date: Fri, 20 Jan 2023 15:55:30 -0600 Subject: [PATCH] Fixed broken links in markdown. --- Docs/breaking-changes-v6.0.md | 4 ++-- Docs/ci-cd-pipeline.md | 16 +++++++++++----- Docs/clone-github.md | 2 +- Docs/cloud-adoption-framework.md | 2 +- Docs/definitions-and-global-settings.md | 16 ++++++++-------- Docs/desired-state-strategy.md | 2 +- Docs/documenting-assignments-and-policy-sets.md | 12 ++++-------- Docs/operating-environment.md | 2 +- Docs/operational-scripts.md | 4 ++-- Docs/policy-assignments.md | 10 +++++----- Docs/policy-definitions.md | 2 +- Docs/policy-exemptions.md | 3 ++- README.md | 8 ++++---- 13 files changed, 43 insertions(+), 40 deletions(-) diff --git a/Docs/breaking-changes-v6.0.md b/Docs/breaking-changes-v6.0.md index 217c0467..d43f4be3 100644 --- a/Docs/breaking-changes-v6.0.md +++ b/Docs/breaking-changes-v6.0.md @@ -58,14 +58,14 @@ For details consult the above table and the newly updated samples in StarterKit. ``` * If you're using Azure DevOps pipelines add parameter `-devOpsType "ado"` to `Build-DeploymentPlans.ps1` -* Add required `MS Graph` [permissions](azure-devops-pipeline.md) for the pipeline service connections. +* Add required `MS Graph` [permissions](ci-cd-pipeline.md#ms-graph-permissions) for the pipeline service connections. ## Reading List * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/ci-cd-pipeline.md b/Docs/ci-cd-pipeline.md index 22da1c26..27831355 100644 --- a/Docs/ci-cd-pipeline.md +++ b/Docs/ci-cd-pipeline.md @@ -27,7 +27,7 @@ * [Azure DevOps Pipeline](#azure-devops-pipeline) * [Service Connections](#service-connections) * [Deployment Environments](#deployment-environments) -* [Deployment Scripts for Pipeline](#deployment-scripts-for-pipeline) +* [Deployment Scripts](#deployment-scripts) * [Common Script Parameters](#common-script-parameters) * [Build-DeploymentPlans.ps1](#build-deploymentplansps1) * [Deploy-PolicyPlan.ps1](#deploy-policyplanps1) @@ -43,7 +43,7 @@ The diagram below shows the use of GitHub Flow in Policy as Code. Builds are triggered for Commits, optionally for Pull Requests and for successful main branch merges. -![image.png](Images/PaC-GitHub-Flow.png) +![image.png](Images/epac-github-flow.png) ## Service connections for DevOps CI/CD @@ -140,6 +140,7 @@ After you configure the Permissions (`Add a permission`), you must `Grant admin ![image,png](Images/ms-graph-permissions.png) Read the following Microsoft instructions to [learn more about MS Graph Application Permissions](https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http#application-permissions) + 1. [Register your app](https://learn.microsoft.com/en-us/graph/auth-v2-service#1-register-your-app) 2. [Configure permissions for Microsoft Graph]() 3. [Get administrator consent](https://learn.microsoft.com/en-us/graph/auth-v2-service#3-get-administrator-consent) @@ -189,7 +190,7 @@ Service connections give the pipeline the proper permissions to deploy at desire Create distinct ADO environment to configure approval gates. Refer to the following documentation: -## Deployment Scripts for Pipeline +## Deployment Scripts > --- > --- @@ -203,6 +204,11 @@ Create distinct ADO environment to configure approval gates. Refer to the follow
+ +![image.pmg](Images/epac-deployment-scripts.png) + +
+ ### Common Script Parameters |Parameter | Required | Explanation | @@ -215,7 +221,7 @@ Create distinct ADO environment to configure approval gates. Refer to the follow Analyzes changes in policy, initiative, and assignment files. It calculates a plan to apply deltas. The deployment scripts are **declarative** and **idempotent**: this means, that regardless how many times they are run, they always push all changes that were implemented in the JSON files to the Azure environment, i.e. if a JSON file is newly created/updated/deleted, the pipeline will create/update/delete the Policy and/or Initiative definition in Azure. If there are no changes, the pipeline can be run any number of times, as it won't make any changes to Azure. -In addition to the [common parameters](#common-parameters-for-flexible-and-unified-definitions), these parameters are defined: +In addition to the [common parameters](#common-script-parameters), these parameters are defined: |Parameter | Required | Explanation | |----------|----------|-------------| @@ -290,7 +296,7 @@ Detail view: * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/clone-github.md b/Docs/clone-github.md index 031397c5..28da53f9 100644 --- a/Docs/clone-github.md +++ b/Docs/clone-github.md @@ -58,7 +58,7 @@ The repo contains a script to synchronize directories in both directions: `Sync- * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/cloud-adoption-framework.md b/Docs/cloud-adoption-framework.md index 281c53be..14c2d4fd 100644 --- a/Docs/cloud-adoption-framework.md +++ b/Docs/cloud-adoption-framework.md @@ -79,7 +79,7 @@ Several of the assignment files also have parameters which need to be in place. * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/definitions-and-global-settings.md b/Docs/definitions-and-global-settings.md index 5f881d83..c5a0f665 100644 --- a/Docs/definitions-and-global-settings.md +++ b/Docs/definitions-and-global-settings.md @@ -17,13 +17,13 @@ **On this page** -- [Folders](#folders) -- [Global Settings](#global-settings) - - [Uniquely identify deployments `pacOwnerId`](#uniquely-identify-deployments-pacownerid) - - [Define EPAC Environments in `pacEnvironments`](#define-epac-environments-in-pacenvironments) - - [DeployIfNotExists and Modify Policy Assignments need `managedIdentityLocation`](#deployifnotexists-and-modify-policy-assignments-need-managedidentitylocation) - - [Excluding scopes for all Assignments with `globalNotScopes`](#excluding-scopes-for-all-assignments-with-globalnotscopes) -- [Reading List](#reading-list) +* [Folders](#folders) +* [Global Settings](#global-settings) + * [Uniquely identify deployments `pacOwnerId`](#uniquely-identify-deployments-pacownerid) + * [Define EPAC Environments in `pacEnvironments`](#define-epac-environments-in-pacenvironments) + * [DeployIfNotExists and Modify Policy Assignments need `managedIdentityLocation`](#deployifnotexists-and-modify-policy-assignments-need-managedidentitylocation) + * [Excluding scopes for all Assignments with `globalNotScopes`](#excluding-scopes-for-all-assignments-with-globalnotscopes) +* [Reading List](#reading-list) ## Folders @@ -137,7 +137,7 @@ The arrays can have the following entries: - [Setup DevOps Environment](operating-environment.md) . - [Create a source repository and import the source code](clone-github.md) from this repository. - [Select the desired state strategy](desired-state-strategy.md) -- [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +- Copy starter kit pipeline definition and definition folder to your folders. - [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. - [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. - [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/desired-state-strategy.md b/Docs/desired-state-strategy.md index 06f42244..139aabbf 100644 --- a/Docs/desired-state-strategy.md +++ b/Docs/desired-state-strategy.md @@ -109,7 +109,7 @@ By default, Policy Assignments at resource groups are not managed by EPAC. Prior * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/documenting-assignments-and-policy-sets.md b/Docs/documenting-assignments-and-policy-sets.md index d6bcdb95..55d90fc8 100644 --- a/Docs/documenting-assignments-and-policy-sets.md +++ b/Docs/documenting-assignments-and-policy-sets.md @@ -17,7 +17,7 @@ The Documentation feature provides reports on Initiatives and Assignments deployed within an environment, and comparisons of Initiatives (deployed or not) for considering differences in policies and effects. Output is generated as Markdown (`.md`), and Excel (`.csv`) files. -The script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](../../Scripts/Operations/README.md#build-policyassignmentdocumentationps1) documents Initiatives and Assignments in your environment. It retrieves its instruction from the JSON files in this folder; the names of the definition JSON files don't matter as the script reads any file in the folder with a `.json` and `.jsonc` extension. +The script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](operational-scripts.md#build-policyassignmentdocumentationps1) documents Initiatives and Assignments in your environment. It retrieves its instruction from the JSON files in this folder; the names of the definition JSON files don't matter as the script reads any file in the folder with a `.json` and `.jsonc` extension. * Read and process Policy Assignments which are representative of an environment category, such as prod, test, dev, and sandbox. It generates Markdown (`.md`), and Excel (`.csv`) files. * Read and process Initiative definitions to compare them for Policy and effect overlap. It generates Markdown (`.md`), Excel (`.csv`) files, and JSON file (`.jsonc`). @@ -26,8 +26,8 @@ The script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](../. Each file must contain one or both documentation topics. This example file in the StarterKit has both topics. Element `pacEnvironment` references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the custom Policy and Initiative definitions are deployed. -* [`documentAssignments`](#specifying-assignment-documentation) -* [`documentInitiatives`](#specifying-initiative-documentation) +* [`documentAssignments`](#assignment-documentation) +* [`documentInitiatives`](#initiative-documentation) ```jsonc { @@ -146,10 +146,6 @@ Each `environmentCategories` entry specifies: ### Element `documentationSpecifications` -> **Warning: Breaking change in release v5.3** -> -> `type` is no longer needed and the field has been removed. The only previous `type` available is `effectsAcrossEnvironments`; the script will write a warning if it is specified. Specifying `"type": "effectsPerEnvironment",` will result in a script error. - Each entry in the array defines a set of outputs: * `fileNameStem`: the file name stem used to construct the filenames. @@ -226,7 +222,7 @@ Compares Policy and Initiative definitions to Initiative definitions for Policy * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/operating-environment.md b/Docs/operating-environment.md index 36145545..59f7ee2c 100644 --- a/Docs/operating-environment.md +++ b/Docs/operating-environment.md @@ -67,7 +67,7 @@ Agents (also called runners) are often hosted in VMs within Azure itself. It is * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/operational-scripts.md b/Docs/operational-scripts.md index b417fef8..9b505515 100644 --- a/Docs/operational-scripts.md +++ b/Docs/operational-scripts.md @@ -48,7 +48,7 @@ This script executes all remediation tasks in a Policy as Code environment speci ## Build-PolicyAssignmentDocumentation.ps1 -Generates documentation for assignments and initiatives based on JSON files in `$definitionsFolder/Documentation`. [See Define Documentation for details](../../Definitions/Documentation/README.md). +Generates documentation for assignments and initiatives based on JSON files in `$definitionsFolder/Documentation`. [See Define Documentation for details](documenting-assignments-and-policy-sets.md). |Parameter | Required | Explanation | |----------|----------|-------------| @@ -133,7 +133,7 @@ Exports a policy assignment from Azure to a local file in the EPAC format. Provi * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/policy-assignments.md b/Docs/policy-assignments.md index a2a097dd..038c1e62 100644 --- a/Docs/policy-assignments.md +++ b/Docs/policy-assignments.md @@ -19,7 +19,7 @@ ## Components -This chapter describes how **Policy Assignments** are handled by EPAC. To learn about how custom Policy and Initiative definitions are managed, see the [Policy Definitions](../Policies/README.md) and [Initiative Definitions](../Initiatives/README.md). +This chapter describes how **Policy Assignments** are handled by EPAC. To learn about how custom Policy and Initiative definitions are managed, see the [Policy Definitions](policy-definitions.md) and [Policy Set (Initiative) Definitions](policy-set-definitions.md). The components required for **creating / updating / deleting Policy assignments and Policy set (initiative) assignments** are the following: @@ -98,17 +98,17 @@ If you are using multiple Policy Sets, than EPAC will: ### Single node to assign allowed locations enforcement -Assignment file [allowed-locations-assignments.jsonc](../../StarterKit/Definitions/policyAssignments/allowed-locations-assignments.jsonc) contains a single node to assign a single Initiative to one scope. +Assignment file [allowed-locations-assignments.jsonc](../StarterKit/Definitions/policyAssignments/allowed-locations-assignments.jsonc) contains a single node to assign a single Initiative to one scope. ### Hierarchy to assign security and compliance initiatives -Assignment file [security-baseline-assignments.jsonc](../../StarterKit/Definitions/policyAssignments/security-baseline-assignments.jsonc) contains 2 levels of hierarchy containing the root node and 2 child nodes. It uses a `definitionEntryList` instead of `definitionEntry`. Defining this with the `definitionEntry` approach would have increased the hierarchy from 2 levels (3 nodes) to 3 levels (7 nodes). +Assignment file [security-baseline-assignments.jsonc](../StarterKit/Definitions/policyAssignments/security-baseline-assignments.jsonc) contains 2 levels of hierarchy containing the root node and 2 child nodes. It uses a `definitionEntryList` instead of `definitionEntry`. Defining this with the `definitionEntry` approach would have increased the hierarchy from 2 levels (3 nodes) to 3 levels (7 nodes). **Note**: With only two types of environments, 3 nodes versus 7 nodes is a small difference; however if you have a more complex environment differentiation with lots of environment types and parameters this becomes quickly untenable. As an extreme illustration with 8 environments (e.g., sandbox, dev, integration, testing, uat, perf, pre-prod and prod), you would need to specify 25 nodes. Such a file would likely be thousands of lines long and completely unreadable. ### Hierarchy to manage Azure resource tags -Assignment file [tag-assignments.jsonc](../../StarterKit/Definitions/policyAssignments/tag-assignments.jsonc) defines: +Assignment file [tag-assignments.jsonc](../StarterKit/Definitions/policyAssignments/tag-assignments.jsonc) defines: * Required tags and inherited tags with a `definitionEntryList` using 2 levels (plus the root node) * Environment tag values for resource groups with a `definitionEntry` using two levels (plus the shared root node) @@ -118,7 +118,7 @@ Assignment file [tag-assignments.jsonc](../../StarterKit/Definitions/policyAssig * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/policy-definitions.md b/Docs/policy-definitions.md index 06cc53ce..6b51252c 100644 --- a/Docs/policy-definitions.md +++ b/Docs/policy-definitions.md @@ -69,7 +69,7 @@ The names of the definition JSON files don't matter, the Policy and Initiative d * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/Docs/policy-exemptions.md b/Docs/policy-exemptions.md index e574bced..4bb65bb8 100644 --- a/Docs/policy-exemptions.md +++ b/Docs/policy-exemptions.md @@ -43,6 +43,7 @@ The pacEnvironment (see global-settings.jsonc) is represented with a folder, suc ### CSV/XLSX Format If you use spreadsheets (.csv or .xlsx): + * Column headers must be exactly as the JSON labels above. * `policyDefinitionReferenceIds` use comma separated list within each cell. * `metadata` cells must contain valid JSON. @@ -52,7 +53,7 @@ If you use spreadsheets (.csv or .xlsx): * [Setup DevOps Environment](operating-environment.md) . * [Create a source repository and import the source code](clone-github.md) from this repository. * [Select the desired state strategy](desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md) +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`. * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit. * [Add custom Policy definitions](policy-definitions.md). diff --git a/README.md b/README.md index 3a6fc37d..293d1fa2 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ * [Create the CI/CD (skip if using the semi-automated approach)](#create-the-cicd-skip-if-using-the-semi-automated-approach) * [Build your definitions and assignments](#build-your-definitions-and-assignments) * [Manage your Policy environment](#manage-your-policy-environment) - * [EPAC issues](#epac-issues) + * [Debug EPAC issues](#debug-epac-issues) * [Contributing](#contributing) * [Trademarks](#trademarks) @@ -48,7 +48,7 @@ Enterprise Policy as Code or EPAC for short comprises a number of scripts which Three deployment scripts plan a deployment, deploy Policy resource, and Role assignments respectively as shown in the following diagram. The solution consumes definition files (JSON and/or CSV files). The planning script (`Build-DeploymentPlan`) creates plan files (`policy-plan.json` and `roles-plan.json`) to be consumed by the two deployment steps (`Deploy-PolicyPlan` and `Deploy-RolesPlan`). The scripts require `Reader`, `Contributor` and `User Access Administrator` privileges respectively as indicated in blue text in the diagram. The diagram also shows the usual approval gates after each step/script for prod deployments. -![image.png](Docs/Images/PaC-Deploy-Scripts.png) +![image.png](Docs/Images/epac-deployment-scripts.png)
@@ -168,8 +168,8 @@ Desired state strategy documentation can be found [here.](Docs/desired-state-str ### Define your deployment scenarios -* [Select the desired state strategy](Docs/desired-state-strategy.md) -* [Copy starter kit pipeline definition and definition folder to your folders](Docs/starter-kits.md) +* [Select the desired state strategy](Docs/desired-state-strategy.md). +* Copy starter kit pipeline definition and definition folder to your folders. * [Define your deployment environment](Docs/definitions-and-global-settings.md) in `global-settings.jsonc`. ### Create the CI/CD (skip if using the semi-automated approach)