Fixing admonitions (#525)

Docs/changes.md

@@ -2,15 +2,15 @@
 
 !!! danger "Caution"
 
-  Read the [breaking changes](#breaking-changes-in-v1000) carefully and adjust your environment accordingly.
+    Read the [breaking changes](#breaking-changes-in-v1000) carefully and adjust your environment accordingly.
 
 ## Breaking Changes in v10.0.0
 
 ### Changes in `globalSettings.jsonc`
 
 !!! warning
 
-  We heavily reworked the `globalSettings.jsonc` file. You will need to update the file.
+    We heavily reworked the `globalSettings.jsonc` file. You will need to update the file.
 
 Deprecated top-level elements:
 

Docs/ci-cd-github-actions.md

@@ -46,8 +46,9 @@ This section is retained from the previous documentation to enable you to contin
 8. For role changes when the PR is approved again the same action runs - this time using the `Deploy-RolesPlan` for deployment.
 9. When complete the PR is closed and the branch containing the plan is deleted.
 
-> [!NOTE]
-> This is a sample method of deploying policy and role changes - feel free to modify it to suit your environment and contribute to this project if you want to share an update.
+!!! note
+
+    This is a sample method of deploying policy and role changes - feel free to modify it to suit your environment and contribute to this project if you want to share an update.
 
 ### Setup in GitHub -- Legacy
 

Docs/epac-extracting-policy-resources.md

@@ -2,20 +2,23 @@
 
 Script `Export-AzPolicyResources` (Operations) extracts existing Policies, Policy Sets, and Policy Assignments and Exemptions outputing them in EPAC format into subfolders in folder `$outputFolders/Definitions`. The subfolders are `policyDefinitions`, `policySetDefinitions`, `policyAssignments` and `policyExemptions`.
 
-> [!TIP]
-> In a new EPAC instance these subfolders can be directly copied to the `Definitions` folder enabling an initial transition from a pre-EPAC to EPAC environment.
+!!! tip
 
-> [!NOTE]
-> The script collects information on ownership of the Policy resources into a CSV file. You can analyze this file to assist in the transition to EPAC.
+    The script collects information on ownership of the Policy resources into a CSV file. You can analyze this file to assist in the transition to EPAC.
 
-The scripts creates a `Definitions` folder in the `OutputFolder` with the subfolders for `policyDefinitions`, `policySetDefinitions`, `policyAssignments` and `policyExemptions`. To use the generated files copy them to your `Definitions` folder.
+The scripts creates a `Definitions` folder in the `OutputFolder` with the subfolders for `policyDefinitions`, `policySetDefinitions`, `policyAssignments` and `policyExemptions`.
+
+!!! tip
+
+    In a new EPAC instance these folders can be directly copied to the `Definitions` folder enabling an initial transition from a pre-EPAC to EPAC environment.
 
 * `policyDefinitions`, `policySetDefinitions` have a subfolder based on `metadata.category`. If the definition has no `category` `metadata` they are put in a subfolder labeled `Unknown Category`. Duplicates when including child scopes are sorted into the `Duplicates` folder. Creates one file per Policy and Policy Set.
 * `policyAssignments` creates one file per unique assigned Policy or Policy Set spanning multiple Assignments.
 * `policyExemptions` creates one subfolder per EPAC environment
 
-> [!WARNING]
-> The script deletes the `$outputFolders/Definitions` folder before creating a new set of files. In interactive mode it will ask for confirmation before deleting the directory.
+!!! warning
+
+    The script deletes the `$outputFolders/Definitions` folder before creating a new set of files. In interactive mode it will ask for confirmation before deleting the directory.
 
 ## Use case 1: Interactive or non-interactive single tenant
 

Docs/epac-implementing.md

@@ -2,7 +2,7 @@
 
 !!! danger "Caution"
 
-  EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](desired-state-strategy.md) page.
+    EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](desired-state-strategy.md) page.
 
 ## Getting Started
 
@@ -28,8 +28,9 @@ The following steps are required to implement Enterprise Policy as Code (EPAC) i
 
 ## EPAC Concepts and Environments
 
-> [!IMPORTANT]
-> Understanding the concepts and  environments is crucial. Do **not** proceed until you completely understand this section.
+!!! success "Important"
+
+    Understanding the concepts and  environments is crucial. Do **not** proceed until you completely understand this section.
 
 ### EPAC Concepts
 
@@ -57,26 +58,6 @@ These associations are stored in [global-settings.jsonc](settings-global-setting
 
 EPAC supports single and multi-tenant deployments from a single source. In most cases you should have a fully or partially isolated area for Policy development and testing, such as a Management Group. An entire tenant can be used; however, it is not necessary since EPAC has sophisticated partitioning capabilities.  EPAC also supports deployments to managed (Lighthouse) tenants and is able to deploy cross tenant role assignments to projected subscriptions in order to facilitate writing data back to the managing tenant (e.g. diagnostic settings).
 
-> [!IMPORTANT]
-> 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:
-
-```json
-"metadata": {
-  "epacCloudEnvironments": [
-    "AzureChinaCloud"
-  ]
-},
-```
-
-For assignment files, this is a top level property on the assignment's root node:
-
-```json
-"nodeName": "/root",
-"epacCloudEnvironments": [
-    "AzureChinaCloud"
-],
-```
-
 ### Example Management Group Structure and EPAC Environments
 
 Assuming that you have a single tenant with a management group hierarchy as follows (with additional levels of management groups not shown for brevity):
@@ -134,6 +115,28 @@ The simplest `global-settings.jsonc` for the above structure is:
 }
 ```
 
+## Cloud Environment with Unsupported/Missing Policy Definitions
+
+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:
+
+```json
+"metadata": {
+  "epacCloudEnvironments": [
+    "AzureChinaCloud"
+  ]
+},
+```
+
+For assignment files, this is a top level property on the assignment's root node:
+
+```json
+"nodeName": "/root",
+"epacCloudEnvironments": [
+    "AzureChinaCloud"
+],
+```
+
+
 ## Install Powershell and EPAC
 
 EPAC can be installed in two ways:

Docs/index.md

@@ -2,12 +2,13 @@
 
 Enterprise Azure Policy as Code (EPAC for short) is a number of PowerShell scripts which can be used in CI/CD based system or a semi-automated use to deploy Policies, Policy Sets, Policy Assignments, Policy Exemptions and Role Assignments. It also contains operational scripts to simplify operational tasks.
 
-!!! danger
+!!! danger "Caution"
 
     v10.0.0 has breaking changes. Please review the [Changes](changes.md) document.
 
-> [!IMPORTANT]
-> 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). In accordance with Microsoft's privacy policies, you have the right to **opt-out** of this tracking. Please review [Telemetry below](#telemetry-tracking-using-customer-usage-attribution-pid) and [Microsoft Privacy](https://privacy.microsoft.com/en-US/) for more information.
+!!! success "Important"
+
+    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). In accordance with Microsoft's privacy policies, you have the right to **opt-out** of this tracking. Please review [Telemetry below](#telemetry-tracking-using-customer-usage-attribution-pid) and [Microsoft Privacy](https://privacy.microsoft.com/en-US/) for more information.
 
 ## Benefits of EPAC
 
@@ -21,16 +22,17 @@ Enterprise Azure Policy as Code (EPAC for short) is a number of PowerShell scrip
 - Integration with Azure Landing Zone recommended policies
 - Starter Kit with examples
 
-!!! danger
+!!! danger "Caution"
 
     EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](settings-desired-state.md) page.
 
 ## Who Should use EPAC?
 
 EPAC is designed for medium and large organizations with a larger number of Policies, Policy Sets and Assignments and/or complex deployment scenarios, such as, multiple tenants, multiple teams managing Policies.
 
-> [!TIP]
-> EPAC provides a mature [integration with Azure Landing Zones](integrating-with-alz.md). Utilizing [Azure Landing Zones](https://aka.ms/alz/aac) together with EPAC is highly recommended.
+!!! tip
+
+    EPAC provides a mature [integration with Azure Landing Zones](integrating-with-alz.md). Utilizing [Azure Landing Zones](https://aka.ms/alz/aac) together with EPAC is highly recommended.
 
 ### Smaller Organizations
 

Docs/integrating-with-alz.md

@@ -182,9 +182,6 @@ To deploy the ALZ policies using EPAC follow the steps below.
 
 7. Follow the normal steps to deploy the solution to the environment.
 
-> [!TIP]
-> Searching for comments in the assignment JSON files will show which values need to be updated.
-
 ## Keeping up to date with changes manually
 
 The Azure Landing Zone deployment contains a number of policies which help provide guardrails to an environment, and the team which works on these policies is always providing updates to the original content to keep in line with Microsoft best practice and road map. The EPAC solution contains a function to help synchronize changes from the upstream project
@@ -197,14 +194,17 @@ Sync-ALZPolicies -DefinitionsRootFolder .\Definitions -CloudEnvironment AzureClo
 
 Carefully review the proposed changes before deploying them. It is best to make sure you're project is stored in source control so you can easily see which files have changed before deployment.
 
-> [!WARNING]
-> If you have follow Scenario 1 above, the first time you run the `Sync-ALZPolicies` there will be many changes recorded due to formatting. Review the files completely before deploying.
+!!! warning
+
+    If you have follow Scenario 1 above, the first time you run the `Sync-ALZPolicies` there will be many changes recorded due to formatting. Review the files completely before deploying.
+
+!!! warning
+
+    Assignments deployed via the ALZ accelerators are kept in sync with the EnterprisePolicyAsCode module so ensure you have the latest PowerShell module installed before running `Sync-ALZPolicies`
 
-> [!WARNING]
-> Assignments deployed via the ALZ accelerators are kept in sync with the EnterprisePolicyAsCode module so ensure you have the latest PowerShell module installed before running `Sync-ALZPolicies`
+!!! tip
 
-> [!TIP]
-> Rename or copy the default ALZ assignment files - when you do a sync it makes it easier to compare changes. 
+    Rename or copy the default ALZ assignment files - when you do a sync it makes it easier to compare changes. 
 
 ## Keeping up to date with GitHub Actions
 

Docs/policy-assignments-csv-parameters.md

@@ -5,8 +5,9 @@ Assigning single or multiple security and compliance focused Policy Sets (Initia
 
 To address the problem of reading and maintaining hundreds or thousands of JSON lines, EPAC can use the content of a spreadsheet (CSV) to create `parameters`, `overrides` and optionally `nonComplianceMessages` for a single Policy assignment `definitionEntry` or multiple Policy definitions (`definitionEntryList`).
 
-> [!TIP]
-> This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`.
+!!! tip
+
+    This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`.
 
 ## Generate the CSV File
 
@@ -31,8 +32,9 @@ The CSV file generated contains the following headers/columns:
 * `<env>Parameters` can contain additional parameters. You can also specify such parameters in JSON. EPAC will use the union of all parameters.
 * `nonComplianceMessages` column is optional. The documentation script does not generate this columns.
 
-> [!NOTE]
-> Additional columns are allowed and ignored by EPAC.
+!!! note
+
+    Additional columns are allowed and ignored by EPAC.
 
 EPAC will find the effect parameter name for each Policy in each Policy Set and use them. If no effect parameter is defined by the Policy Set, EPAC will use `overrides` to set the effect. EPAC will generate the `policyDefinitionReferenceId` for `nonComplianceMessages`.
 
@@ -131,5 +133,6 @@ If a Policy is added to a Policy Set, add the row manually to the CSV file. The
 
 Better, [regenerate the CSV file from the deployed Policy Assignments](operational-scripts-documenting-policy.md#assignment-documentation). This will ensure that all Policies are included in the CSV file. However, this does not generate the `nonComplianceMessages` column or any additional columns you added.
 
-> [!NOTE]
-> We have planned to add a feature to generate the CSV file from the Policy Assignments and merge them with your existing CSV File to preserve extra columns.
+!!! note
+
+    We have planned to add a feature to generate the CSV file from the Policy Assignments and merge them with your existing CSV File to preserve extra columns.

Docs/policy-assignments.md

@@ -47,8 +47,9 @@ To utilize the schema add a ```$schema``` tag to the JSON file.
 - Role Assignments for user-assigned Managed Identities (UAMI) are not managed by EPAC, and will not generate a `roles-plan.json` file.
 - `additionalRoleAssignments` are used when a resource required is not in the current scope. For example, a Policy Assignment that requires a Event Hub to be managed in a subscription not contained in the current management group.
 
-> [!TIP]
-> The tree is not required to be balanced. The number of levels is not restricted; however, anything beyond 3 levels is unnecessary in real scenarios and would be difficult to read and manage as the depth increases.
+!!! tip
+
+    The tree is not required to be balanced. The number of levels is not restricted; however, anything beyond 3 levels is unnecessary in real scenarios and would be difficult to read and manage as the depth increases.
 
 ## Assignment Element and Metadata
 
@@ -64,8 +65,9 @@ Each Assignment is required to have a `name` which is used in it's resource id.
 
 Multiple `assignment` naming components in a tree branch are string concatenated for each of the three fields.
 
-> [!WARNING]
-> Azure has a limit of 24 characters for the concatenated `name` string. EPAC displays an error if this limit is exceeded.
+!!! warning
+
+    Azure has a limit of 24 characters for the concatenated `name` string. EPAC displays an error if this limit is exceeded.
 
 ### Defining `metadata`
 
@@ -274,8 +276,9 @@ Assigning single or multiple security and compliance focused Policy Sets (Initia
 
 To address the problem of reading and maintaining hundreds or thousands of JSON lines, EPAC can use the content of a spreadsheet (CSV) to create `parameters`, `overrides` and optionally `nonComplianceMessages` for a single Policy assignment `definitionEntry` or multiple Policy definitions (`definitionEntryList`).
 
-> [!TIP]
-> This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`.
+!!! tip
+
+    This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`.
 
 Implement these steps as documented in [Managing Policy Assignment Parameters with a CSV file](policy-assignments-csv-parameters.md).
 
@@ -286,8 +289,9 @@ Implement these steps as documented in [Managing Policy Assignment Parameters wi
 
 ### Defining `parameters` with JSON
 
-> [!WARNING]
-> `parameters` have a simplified JSON structure. You do not need the additional `value` indirection Azure requests (EPAC will inject that indirection).
+!!! warning
+
+    `parameters` have a simplified JSON structure. You do not need the additional `value` indirection Azure requests (EPAC will inject that indirection).
 
 ```json
 "parameters": {
@@ -303,8 +307,9 @@ Implement these steps as documented in [Managing Policy Assignment Parameters wi
 },
 ```
 
-> [!NOTE]
-> Too enable `definitionEntryList`, parameters not present in the Policy or Policy Set definition are quietly ignored.
+!!! note
+
+    Too enable `definitionEntryList`, parameters not present in the Policy or Policy Set definition are quietly ignored.
 
 ## Advanced Elements
 

Docs/policy-definitions.md

@@ -4,9 +4,6 @@
 
 Policy definition files are managed within the folder `policyDefinitions` under `Definitions`.  The Policy definition files are structured based on the official [Azure Policy definition structure](https://docs.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure) published by Microsoft. There are numerous definition samples available on Microsoft's [GitHub repository for azure-policy](https://github.com/Azure/azure-policy).
 
-> [!TIP]
-> When authoring Policy and Policy definitions, check out the [Maximum count of Azure Policy objects](https://docs.microsoft.com/en-us/azure/governance/policy/overview#maximum-count-of-azure-policy-objects)
-
 The names of the definition JSON files don't matter, the Policy and Policy Set definitions are registered based on the `name` attribute. The solution also allows the use of JSON with comments by using `.jsonc` instead of `.json` for the file extension.
 
 ## JSON Schema

Docs/policy-exemptions.md

@@ -31,8 +31,9 @@ To utilize the schema add a ```$schema``` tag to the JSON file.
 
 ## Defining Exemptions
 
-> [!TIP]
-> In v10.0.0, exemptions can be defined by specifying the Policy definition Ids or Names instead of Policy Assignment Ids. This significantly reduces the complexity of defining exemptions for Policy Sets with overlapping Policy definitions. **We recommend using Policy definition Ids or Names for new exemptions.**
+!!! tip
+
+    In v10.0.0, exemptions can be defined by specifying the Policy definition Ids or Names instead of Policy Assignment Ids. This significantly reduces the complexity of defining exemptions for Policy Sets with overlapping Policy definitions. **We recommend using Policy definition Ids or Names for new exemptions.**
 
 Each exemption must define the following properties:
 - `name` - unique name, we recommend a GUID.