Cleanup the docs. (#447)

Docs/ci-cd-overview.md

@@ -48,7 +48,9 @@ While this script intended to be used in CI/CD, they can be run manually to crea
 * CI/CD environment is not yet available.
 * Debugging the scripts from Visual Studio Code.
 
-The image below shows the scripts and the roles required for their execution. To setup the SPNs and roles, see [Setup App Registrations](./ci-cd-app-registrations.md).
+Deployment scripts require permissions to the Azure environment and Microsoft Graph API. In a CI/CD scenario, App Registration (SPNs) are used to execute the scripts. These identities must be granted the necessay permissions as documented in [App Registrations Setup](./ci-cd-app-registrations.md). In a semi-automated scenario, the user executing the scripts must have the necessary permissions. The scripts will prompt for the necessary permissions.
+
+The image below shows the scripts and the roles required for their execution.
 
 * `Build-DeploymentPlans.ps1` requires `EPAC Resource Policy Reader` custom role on the root or pseudo-root management group and the Microsoft Graph permissions described below.
 * `Deploy-PolicyPlan.ps1` requires `Resource Policy Contributor` built-in role on the root or pseudo-root management group. Microsoft Graph permissions are not required.
@@ -93,55 +95,3 @@ Creates the role assignments for the Managed Identities required for `DeployIfNo
 |----------|-------------|
 | `InputFolder` | Input folder path for plan files. Defaults to environment variable `$env:PAC_INPUT_FOLDER`, `$env:PAC_OUTPUT_FOLDER` or `./Output`. |
 
-## Deployments
-
-* Feature branch during development
-    * Trigger on push
-        * branch `feature/**`
-        * files `Definitions/**`
-    * Deploy to `epac-dev` environment
-        * Scripts: `Build-DeploymentPlans.ps1`, `Deploy-PolicyPlan.ps1`, `Deploy-RolesPlan.ps1`
-        * App Registration (SPN): `ci-cd-epac-owner`
-        * Roles: `Owner` on `epac-dev` management group (Owner simplifies need for app registrations)
-        * [Microsoft Graph Permissions](#ms-graph-permissions)
-    * *Optional:* Calculate deployment plan for each tenant's prod environment
-        * Script `Build-DeploymentPlans.ps1`
-        * App Registration (SPN): `ci-cd-root-policy-reader`
-        * Roles: [`EPAC Resource Policy Reader`](#custom-epac-resource-policy-reader-role) on root or pseudo-root management group
-        * [Microsoft Graph Permissions](#ms-graph-permissions)
-* Optional testing when opening a PR (rarely useful)
-    * Trigger on PR open/reopen
-        * target branch `main`
-        * source branch `feature/**`
-        * files `Definitions/**`
-    * Deploy to `epac-test` environment
-        * Scripts `Build-DeploymentPlans.ps1`, `Deploy-PolicyPlan.ps1`, `Deploy-RolesPlan.ps1`
-        * App Registration (SPN): `ci-cd-epac-test-owner`
-        * Roles: `Owner` on `epac-test` management group (Owner simplifies need for app registrations)
-        * [Microsoft Graph Permissions](#ms-graph-permissions)
-    * *Optional:* Calculate deployment plan for each tenant's prod environment
-        * Script `Build-DeploymentPlans.ps1`
-        * App Registration (SPN): `ci-cd-root-policy-reader`
-        * Roles: [`EPAC Resource Policy Reader`](#custom-epac-resource-policy-reader-role) on root or pseudo-root management group
-        * [Microsoft Graph Permissions](#ms-graph-permissions)
-* Main branch
-    * Trigger on push
-        * branch `feature/**`
-        * files `Definitions/**`
-    * Deploy to each tenant's prod environment
-        * Script `Build-DeploymentPlans.ps1`
-            * App Registration (SPN): `ci-cd-root-policy-reader`
-            * Roles: [`EPAC Resource Policy Reader`](#custom-epac-resource-policy-reader-role) on root or pseudo-root management group
-            * [Microsoft Graph Permissions](#ms-graph-permissions)
-        * Script `Deploy-PolicyPlan.ps1`
-            * Requires an environment **approval gate**
-            * App Registration (SPN): `ci-cd-root-policy-contributor`
-            * Roles: `Resource Policy Contributorader` on root or pseudo-root management group
-        * Script `Deploy-RolesPlan.ps1`
-            * Requires an environment **approval gate**
-            * App Registration (SPN): `ci-cd-root-policy-reader`
-            * Roles: `User Access Administrator` on root or pseudo-root management group
-            * [Microsoft Graph Permissions](#ms-graph-permissions)
-
-
-[Setup App Registrations](./ci-cd-app-registrations.md) contains detailed instructions. We also recommend reading the the Microsoft documentation: [Learn more about MS Graph Application Permissions](https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http#application-permissions).

Docs/clone-github.md

@@ -1,10 +1,6 @@
-# GitHub repository: How to clone or fork, update and contribute
+# Alternate Script Installation cloning the GitHub Repository
 
-Git lacks a capability to ignore files/directories during a PR only. This repo has been organized so that Definitions and Pipeline folders are not touched by syncing latest update from GitHub to your repo or reverse syncing to contribute to the project.
-
-!!! note
-    This steps are no longer necessary if you use the [PowerShell Module](powershell-module.md). You may still need to copy files from the starter kit.
-    You can still use this method to continue your current approach or to [contribute improvements](#contribute-to-github).
+Instead of installing `EnterprisePolicyAsCode` from the PowerShell Gallery, you can clone the GitHub repository and use the scripts described below to install the script source code. This is useful, if your organization has overly restrictive policies on installing PowerShell modules from the PowerShell Gallery. It can also be usefule if you want to contribute EPAC source code to the project.
 
 ## Setting up your Repo
 
@@ -35,9 +31,11 @@ Git lacks a capability to ignore files/directories during a PR only. This repo h
 3. PR changes in your fork (`MyForkRepo`) to GitHub.
 4. GitHub maintainers will review the PR.
 
-## Sync-Repo.ps1
+## Sync-Repo.ps1, Sync-FromGH.ps1, Sync-ToGH.ps1
+
+### Sync-Repo.ps1
 
-The repo contains a script to synchronize directories in both directions: `Sync-Repo.ps1`. It only works if you do not modify:
+The repo contains script to synchronize directories in both directions: `Sync-Repo.ps1`. It only works if you do not modify:
 
 * `Docs`, `Scripts`, `Module` and `StarterKit` directories
 * `*.md`, `*.ps1`, `*.yml`, and `LICENSE` files in repo root directory
@@ -48,6 +46,10 @@ The repo contains a script to synchronize directories in both directions: `Sync-
 | `DestinationDirectory` | Required | Directory with the destination (your private repo) |
 | `SuppressDeleteFiles` | Optional | Switch parameter to suppress deleting files in `$destinationDirectory` tree |
 
+### Sync-FromGH.ps1 and Sync-ToGH.ps1
+
+Sync-FromGH.ps1 and Sync-ToGH.ps1 are a wrapper around Sync-Repo.ps1 used by the EPAC maintainers to simplify syncing their development repo `epac-development` and the GitHub repo `enterprise-azure-policy-as-code`.
+
 ## Process for Development (Maintainers Only)
 
 ### Syncing latest Version from GitHub repo to `epac-development` repo

Docs/desired-state-strategy.md

@@ -9,7 +9,31 @@ This original (previously the only) use case assumes one team/repo manages all P
 * `inheritedDefinitionsScopes`
 * `desiredState`
 
-## Use Case 2: Multiple Teams with Shared Responsibility
+## Use case 2: Manage Policy Definitions, Assignments, or Exemptions differently
+
+In some organizations the lifecycle of different parts may be managed separately. For example, you may have one repo to manage Definitions and Assignments separately from Exemptions. Since the ownership of Exemptions is managed from the Assignment `pacOwnerId`, changing it is not effective.
+
+EPAC only manages items with a directory in the `Definitions` folder. Therefore, you can use the same `pacOwnerId` from two repos and remove the folders to separate them. In this example:
+
+* Repo1: `Definitions` contains `policyDefinitions`, `policySetDefinitions` and `policyAssignments` folders.
+* Repo2: `Definitions` contains `policyExemptions` folder.
+
+Policy resource that would be defined in the folder. It is important to remove the folders. GitHub repos remove empty folder automatically.
+
+If you have an empty folder or a folder with a file extension not recognized by EPAC, EPAC will delete any item which the folder could define from your environment.
+
+## Use case 3: Include Resource Groups
+
+By default, Policy Assignments at resource groups are not managed by EPAC. Prior to v6.0, managing resource groups was to expensive. **Breaking change:** If you used the `-IncludeResourceGroup` switch in prior versions, set `includeResourceGroups` to `true` to achieve the same effect. We also recommend this for new installations.
+
+```json
+"desiredState": {
+    "strategy": "full",
+    "includeResourceGroups": true
+}
+```
+
+## Use Case 4: Multiple Teams with Shared Responsibility
 
 In a shared responsibility model multiple teams manage the same tenant(s) at the same scope. Additionally, a variant of this use case is well suited to what previously was called `brownfield` which needs to preserve Policy resources deployed prior to EPAC. The following diagram shows two EPAC solutions managing the same root (tenant). Other Policy as Code solutions can also participate if the solution sets `metadata.pacOwnerId`.
 
@@ -25,7 +49,7 @@ You may add the following JSON for clarity/documentation of the default behavior
 }
 ```
 
-## Use Case 3:  Multiple Teams in a Hierarchical Organization
+## Use Case 5:  Multiple Teams in a Hierarchical Organization
 
 The hierarchical model allows a central team to manage the commonality while giving parts of the organization a capability to further restrict resources with Policies. This is a common scenario in multi-national corporations with additional jurisdictional requirements (e.g., data sovereignty, local regulations, ...).
 
@@ -42,7 +66,7 @@ Repo A is managed the same as in use cases 1, 2 and 2a. Repo C sets sets the sam
 }
 ```
 
-## Use Case 4: Transitioning to EPAC
+## Use Case 6: Transitioning to EPAC
 
 While transitioning to EPAC, existing Policy resources may need to be kept. Setting `desiredState` to `ownedOnly` allows EPAC to remove its own resources while preserving instances requiring (temporary) preservation.
 
@@ -53,10 +77,7 @@ While transitioning to EPAC, existing Policy resources may need to be kept. Sett
 }
 ```
 
-!!! warning
-    **Breaking change:** Previously this was accomplished with the `brownfield` variable in the pipeline used to set the `SuppressDeletes` flag on the planning script. Unfortunately, the previous approach was to course-grained, preventing an EPAC solution to remove its own deprecated Policy resources. The above is the new approach to the problem
-
-## Use Case 5: Exclude some Scopes and Policy Resources
+## Use Case 7: Exclude some Scopes and Policy Resources
 
 In rare cases you may need to exclude individual child scopes, or Policy resources from management by an EPAC solution.
 
@@ -108,24 +129,3 @@ Examples
 
 ![image.png](Images/shared-excluded.png)
 
-## Use case 6: Include Resource Groups
-
-By default, Policy Assignments at resource groups are not managed by EPAC. Prior to v6.0, managing resource groups was to expensive. **Breaking change:** If you used the `-IncludeResourceGroup` switch in prior versions, set `includeResourceGroups` to `true` to achieve the same effect.
-
-```json
-"desiredState": {
-    "strategy": "full",
-    "includeResourceGroups": true
-}
-```
-
-## Use case 7: Manage Policy Definitions, Assignments, or Exemptions differently
-
-In some organizations the lifecycle of different parts may be managed separately. For example, you may have one repo to manage Definitions and Assignments separately from Exemptions. Since the ownership of Exemptions is managed from the Assignment `pacOwnerId`, changing it is not effective.
-
-EPAC only manages items with a directory in the `Definitions` folder. Therefore, you can use the same `pacOwnerId` from  two repos and remove the folders to separate them. In this example:
-
-* Repo1: `Definitions` contains `policyDefinitions`, `policySetDefinitions` and `policyAssignments` folders.
-* Repo2: `Definitions` contains `policyExemptions` folder.
-
-Policy resource that would be defined in the folderIt is important to remove the folders. If you have an empty folder, EPAC will delete any item which the folder could define from your environment.

Docs/index.md

@@ -22,9 +22,11 @@ EPAC can be used by small organizations with a small number of Policies, Policy
 
 For extremely small Azure customers with one or two subscriptions Microsoft Defender for Cloud automated Policy Assignments for built-in Policies is sufficient.
 
-## Major Change in v8.0.0
+## Tracking EPAC Usage
 
-Starting with v8.0.0, Enterprise Policy as Code (EPAC) is tracking the usage using Customer Usage Attribution (PID). For details and how to **opt-out** see [Usage Tracking](usage-tracking.md).
+Starting with v8.0.0, Enterprise Policy as Code (EPAC) is tracking the usage using [Customer Usage Attribution](https://learn.microsoft.com/en-us/partner-center/marketplace/azure-partner-customer-usage-attribution) EPAC is in the role of a partner as defined in the linked documentation. We use this data to justify the investment in EPAC and to prioritize features.
+
+You have the right and means to **opt-out**; see [Usage Tracking](usage-tracking.md).
 
 ## Project Links
 
@@ -39,17 +41,6 @@ Starting with v8.0.0, Enterprise Policy as Code (EPAC) is tracking the usage usi
 
 This `enterprise-policy-as-code` **(EPAC)** repo has been developed in partnership with the Security & Compliance for Cloud Infrastructure (S&C4CI) offering available from Microsoft's Industry Solutions (Consulting Services). Microsoft Industry Solutions can assist you with securing your cloud. S&C4CI improves your new or existing security posture in Azure by securing platforms, services, and workloads at scale.
 
-## Breaking changes in v7.0
-
-Script `Export-AzPolicyResources` replaces `Build-PolicyDefinitionFolder` with a [substantial increase in capability](extract-existing-policy-resources.md). It has a round-trip capability supporting the extract to be used in the build `Definitions`.
-
-Introducing a new approach using PowerShell Module. This not (actually) breaking existing implementation since you can continue as is; however, for a simplified usage of EPAC, the PowerShell module is the best approach.
-
-The move from synchronizing your repo with the GitHub repo to a PowerShell module necessitated the reworking of the default values for `Definitions`, `Output`, and `Input` folders. Many scripts use parameters for definitions, input and output folders. They default to the current directory, which should be the root of the repo. make sure that the current directory is the root of your repo. We recommend that you do one of the following approaches instead of accepting the default:
-
-- Set the environment variables `PAC_DEFINITIONS_FOLDER`, `PAC_OUTPUT_FOLDER`, and `PAC_INPUT_FOLDER`.
-- Use the script parameters `-DefinitionsRootFolder`, `-OutputFolder`, and `-InputFolder` (They vary by script).
-
 ## Terminology
 
 | Full name                                                                 | Simplified use in this documentation |
@@ -80,18 +71,23 @@ EPAC supports single and multi-tenant deployments from a single source. In most
 
 In some multi-tenant implementations, not all policies, policy sets, and/or assignments will function in all tenants, usually due to either built-in policies that don't exist in some tenant types or unavailable resource providers.  In order to facilitate multi-tenant deployments in these scenarios, utilize the "   epacCloudEnvironments" property to specify which cloud type a specific file should be considered in.  For example in order to have a policy definition deployed only to epacEnvironments that are China cloud tenants, add a metadata property like this to that definition (or definitionSet) file:
 
-    "metadata": {
-      "epacCloudEnvironments": [
-        "AzureChinaCloud"
-      ]
-    },
+```json
+"metadata": {
+  "epacCloudEnvironments": [
+    "AzureChinaCloud"
+  ]
+},
+```
 
 For assignment files, this is a top level property on the assignment's root node:
 
-    "nodeName": "/root",
-    "epacCloudEnvironments": [
-        "AzureChinaCloud"
-    ],
+```json
+"nodeName": "/root",
+"epacCloudEnvironments": [
+    "AzureChinaCloud"
+],
+```
+
 ## Operational Scripts
 
 Scripts to simplify [operational task](operational-scripts.md) are provided. Examples are:
@@ -126,30 +122,6 @@ The `pacSelector` is just a name. We highly recommend to call the Policy develop
 - Script parameter when executing different deployment stages in a CI/CD pipeline or semi-automated deployment targeting a specific EPAC environments.
 - `scopes`, `notScopes`, `additionalRoleAssignments`, `managedIdentityLocations`, and `userAssignedIdentity` definitions in Policy Assignment JSON files.
 
-## CI/CD Scenarios Flexibility
-
-The solution supports any DevOps CI/CD approach you desire. The starter kits assume a GitHub flow approach to branching and CI/CD integration with a standard model below.
-
-- **Simple**
-  - Create a feature branch
-  - Commits to the feature branch trigger:
-    - Plan and deploy changes to a Policy resources development Management Group or subscription.
-    - Create a plan (based on feature branch) for te EPAC production environment(s)/tenant(s).
-  - Pull request (PR) merges trigger:
-    - Plan and deploy from the merged main branch to your EPAC production environment(s) without additional approvals.
-- **Standard** - starter kits implement this approach
-  - Create a feature branch
-  - Commits to the feature branch trigger:
-    - Plan and deploy changes to a Policy resources development Management Group or subscription
-    - Create a plan (based on feature branch) for te EPAC production environment(s)/tenant(s).
-  - Pull request (PR) merges trigger:
-    - Plan from the merged main branch to your EPAC production environment(s).
-  - Approval gate for plan deployment is inserted.
-  - Deploy the planned changes to environment(s)/tenant(s)
-    - Deploy Policy resources.
-    - [Recommended] Approval gate for Role Assignment is inserted.
-    - Deploy Role Assignment.
-
 ## Coexistence and Desired State Strategy
 
 EPAC is a desired state system. It will remove Policy resources in an environment which are not defined in the definition files. To facilitate transition from previous Policy implementations and coexistence of multiple EPAC and third party Policy as Code systems, a granular way to control such coexistence is implemented. Specifically, EPAC supports:

Docs/module-release-process.md

@@ -1,6 +1,6 @@
 # Module Release Process
 
-This is a guide on how to release a new version of the project - including automated PowerShell module publish.
+This is a guide on how to release a new version of the project - including automated PowerShell module publish. It is used by the EPAC maintainers only.
 
 ## GitHub Release Process