[pull] main from Azure:main

.github/PULL_REQUEST_TEMPLATE.md

@@ -37,5 +37,6 @@ The below URLs can be updated where the placeholders are, look for `{YOUR GITHUB
 - [ ] Associated it with relevant [issues](https://github.com/Azure/Enterprise-Scale/issues), for tracking and closure.
 - [ ] Ensured my code/branch is up-to-date with the latest changes in the `main` [branch](https://github.com/Azure/Enterprise-Scale/tree/main)
 - [ ] Performed testing and provided evidence.
+- [ ] Ensured [contribution guidance](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Contribution-Guide) is followed.
 - [ ] Updated relevant and associated documentation.
 - [ ] Updated the ["What's New?"](https://github.com/Azure/Enterprise-Scale/wiki/Whats-new) wiki page (located: `/docs/wiki/whats-new.md`)

.github/workflows/update-portal.yml

@@ -57,6 +57,9 @@ jobs:
       - name: Update policies
         run: bicep build ./src/templates/policies.bicep --outfile ./eslzArm/managementGroupTemplates/policyDefinitions/policies.json
 
+      - name: Update roles
+        run: bicep build ./src/templates/roles.bicep --outfile ./eslzArm/managementGroupTemplates/roleDefinitions/customRoleDefinitions.json
+
       - name: Check git status
         run: |
           echo "==> Check git status..."

.github/workflows/wiki-sync.yml

@@ -61,5 +61,5 @@ jobs:
           echo "Pushing changes to origin..."
           git add .
           git commit -m "$github_commit_message [$GITHUB_ACTOR/${GITHUB_SHA::8}]"
-          git push --set-upstream https://[email protected]/$wiki_target_repo.git master
+          git push --set-upstream "https://[email protected]/$wiki_target_repo.git" master
         working-directory: ${{ env.wiki_target_repo }}

README.md

@@ -1,28 +1,11 @@
 # Enterprise-Scale - Reference Implementation
 
-## Navigation Menu
-
-* [What's New?](https://github.com/Azure/Enterprise-Scale/wiki/Whats-new)
-* [Community Calls](https://github.com/Azure/Enterprise-Scale/wiki/Community-Calls)
-* [Enterprise-Scale Landing Zones - User Guide](https://github.com/Azure/Enterprise-Scale/wiki#enterprise-scale-landing-zones-user-guide)
-* [Enterprise-Scale Architecture](./docs/EnterpriseScale-Architecture.md)
-* [Telemetry Tracking Using Customer Usage Attribution (PID)](https://github.com/Azure/Enterprise-Scale/wiki/Deploying-Enterprise-Scale-CustomerUsage)
-* [Configure Azure permission for ARM Template deployments](./docs/EnterpriseScale-Setup-azure.md)
-* [Deploy Reference Implementation](./docs/EnterpriseScale-Deploy-reference-implentations.md)
-  * [Policies included in Azure landing zones reference implementations](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Policies)
-  * [Contoso Reference - Scope and Design](./docs/reference/contoso/Readme.md)
-  * [AdventureWorks Reference - Scope and Design](./docs/reference/adventureworks/README.md)
-  * [WingTip Reference - Scope and Design](./docs/reference/wingtip/README.md)
-  * [Trey Research Reference - Scope and Design](./docs/reference/treyresearch/README.md)
-* [Create Landing Zones](./docs/EnterpriseScale-Deploy-landing-zones.md)
-* [Deploy workloads into Landing Zones](./workloads)
-* [Getting started with Infrastructure-as-Code](https://github.com/Azure/AzOps-Accelerator/wiki)
-* [Azure Landing Zones Deprecated Services](./docs/wiki/ALZ-Deprecated-Services.md)
-* [Known Issues](./docs/EnterpriseScale-Known-Issues.md)
-* [How Do I Contribute?](./docs/EnterpriseScale-Contribution.md)
-* [Frequently Asked Questions (FAQ)](https://github.com/Azure/Enterprise-Scale/wiki/FAQ)
-* [Roadmap](./docs/EnterpriseScale-Roadmap.md)
-* [Microsoft Support Policy](./SUPPORT.md)
+[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/azure/enterprise-scale.svg)](http://isitmaintained.com/project/azure/enterprise-scale "Average time to resolve an issue")
+[![Percentage of issues still open](http://isitmaintained.com/badge/open/azure/enterprise-scale.svg)](http://isitmaintained.com/project/azure/enterprise-scale "Percentage of issues still open")
+
+## User documentation
+
+To find out more about the Azure landing zones reference implementation, please refer to the [documentation on our Wiki](https://github.com/Azure/Enterprise-Scale/wiki)
 
 ---
 
@@ -32,7 +15,7 @@ The Enterprise-Scale architecture provides prescriptive guidance coupled with Az
 
 The Enterprise-Scale architecture is modular by design and allows organizations to start with foundational landing zones that support their application portfolios, and the architecture enables organizations to start as small as needed and scale alongside their business requirements regardless of scale point.
 
-![hippo](./docs/media/ESLZ.gif)
+![Animated image showing the modularity of Azure landing zones](./docs/wiki/media/ESLZ.gif)
 
 ---
 
@@ -52,7 +35,7 @@ The Enterprise-Scale reference implementations in this repository are intended t
 | Be aligned with cloud provider’s platform roadmap | Yes |
 | UI Experience and simplified setup | Yes, Azure portal |
 | All critical services are present and properly configured according to recommend best practices for identity & access management, governance, security, network and logging | Yes, using a multi-subscription design, aligned with Azure platform roadmap |
-| Automation capabilities (IaC/DevOps) | Yes: ARM, Policy, GitHub/Azure DevOps CICD pipeline option included |
+| Automation capabilities (IaC/DevOps) | Yes: ARM, Policy, GitHub/Azure DevOps CI/CD pipeline option included |
 | Provides long-term self-sufficiency | Yes, enterprise-scale architecture -> 1:N landing zones. Approach & architecture prepare the customer for long-term self-sufficiency, the RIs are there to get you started |
 | Enables migration velocity across the organization | Yes, enterprise-scale architecture -> 1:N landing zones, Architecture includes designs for segmentation and separation of duty to empower teams to act within appropriate landing zones |
 | Achieves operational excellence | Yes. Enables autonomy for platform and application teams with a policy driven governance and management |
@@ -63,7 +46,7 @@ To fully leverage this reference implementation in this repository, readers must
 
 It is also assumed that readers have a broad understanding of key Azure constructs and services in order to fully contextualize the prescriptive recommendations contained within Enterprise-Scale.
 <!--
-![Enterprise-Scale ](./docs/media/ES-process.png)
+![Enterprise-Scale ](./docs/wiki/media/ES-process.png)
 -->
 
 ## Deploying Enterprise-Scale Architecture in your own environment
@@ -84,7 +67,7 @@ The Enterprise-Scale architecture is modular by design and allows customers to s
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+the rights to use your contribution. For details, visit [Contributor License Agreement (CLA)](https://cla.opensource.microsoft.com).
 
 When you submit a pull request, a CLA bot will automatically determine whether you need to provide
 a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions

SECURITY.md

@@ -4,27 +4,27 @@
 
 Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
 
-If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below.
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below.
 
 ## Reporting Security Issues
 
 **Please do not report security vulnerabilities through public GitHub issues.**
 
 Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
 
-If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
+If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/msrc/pgp-key-msrc).
 
-You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
 
 Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
 
-  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
-  * Full paths of source file(s) related to the manifestation of the issue
-  * The location of the affected source code (tag/branch/commit or direct URL)
-  * Any special configuration required to reproduce the issue
-  * Step-by-step instructions to reproduce the issue
-  * Proof-of-concept or exploit code (if possible)
-  * Impact of the issue, including how an attacker might exploit the issue
+* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+* Full paths of source file(s) related to the manifestation of the issue
+* The location of the affected source code (tag/branch/commit or direct URL)
+* Any special configuration required to reproduce the issue
+* Step-by-step instructions to reproduce the issue
+* Proof-of-concept or exploit code (if possible)
+* Impact of the issue, including how an attacker might exploit the issue
 
 This information will help us triage your report more quickly.
 
@@ -36,6 +36,6 @@ We prefer all communications to be in English.
 
 ## Policy
 
-Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/msrc/cvd).
 
 <!-- END MICROSOFT SECURITY.MD BLOCK -->

SUPPORT.md

@@ -2,7 +2,7 @@
 
 ## Microsoft Support Policy
 
-If issues are encountered when deploying these reference implementations users will be able to engage Microsoft support via their usual channels. Please provide corelation IDs where possible when contacting support to be able to investigate issue effectively and in timely fashion. For instruction on how to get deployments and correlation ID, please follow this link [here](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/deployment-history?tabs=azure-portal#get-deployments-and-correlation-id).
+If issues are encountered when deploying these reference implementations users will be able to engage Microsoft support via their usual channels. Please provide corelation IDs where possible when contacting support to be able to investigate issue effectively and in timely fashion. For instruction on how to get deployments and correlation ID, please follow this link [here](https://docs.microsoft.com/azure/azure-resource-manager/templates/deployment-history?tabs=azure-portal#get-deployments-and-correlation-id).
 
 Following list of issues are within the scope of Microsoft support:
 

docs/Deploy/deploy-policy-driven-routing.md

@@ -1,4 +1,5 @@
 # Policy-driven routing configuration in hub and spoke networks
+
 The policy `Deploy a route table with specific user defined routes` allows applying a customer-defined routing configuration to in-scope VNets. For each in-scope VNet, the policy checks the existence of a route table containing a set of customer-defined UDRs; and deploys it if it does not exist. The route table is deployed to the same resource group as the VNet evaluated against the policy. The route table deployed by the policy must be manually associated to subnets.
 
 The main usage scenario for the policy is automated routing configuration in Enterprise-Scale hub and spoke topologies (the reference architecture for Enterprise Scale with hub and spoke is documented [here](https://github.com/Azure/Enterprise-Scale/tree/main/docs/reference/adventureworks)). By assigning the policy to landing zone subscriptions that contain the spoke VNet(s), it allows enforcing routing rules such as:
@@ -12,9 +13,10 @@ The main usage scenario for the policy is automated routing configuration in Ent
 - Route all traffic from spoke VNet to shared services in the hub via the hub’s firewall cluster.
 
 The policy supports the parameters documented below.
+
 - **effect**: A `String` that defines the effect of the policy. Allowed values are `DeployIfNotExist` (default) and `Disabled`.
 
-- **requiredRoutes**: An `Array` of `String` objects. Each `String` object defines a User-Defined Route (UDR) in the custom route table deployed by the policy. The format is `"address-prefix;next-hop-type;next-hop-ip-address"`. The next-hop IP address must be provided on when the next hop type is "VirtualAppliance". Allowed values for the next hop type field are documented [here](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-udr-overview#next-hop-types-across-azure-tools). This is an example of a *requiredRoutes* array that defines four UDRs:  
+- **requiredRoutes**: An `Array` of `String` objects. Each `String` object defines a User-Defined Route (UDR) in the custom route table deployed by the policy. The format is `"address-prefix;next-hop-type;next-hop-ip-address"`. The next-hop IP address must be provided on when the next hop type is "VirtualAppliance". Allowed values for the next hop type field are documented [here](https://docs.microsoft.com/azure/virtual-network/virtual-networks-udr-overview#next-hop-types-across-azure-tools). This is an example of a *requiredRoutes* array that defines four UDRs:  
 
 ```json
 [
@@ -24,6 +26,7 @@ The policy supports the parameters documented below.
 "192.168.2.0/24;VnetLocal"
 ]
 ```
+
 - **vnetRegion**: A `String` that defines the region of the `Microsoft.Network/virtualNetworks` resources that are evaluated against the policy. Only VNets in the specified region are evaluated against the policy. This parameter enables multiple assignments to enforce different routing policies in different regions.
-- **routeTableName**: A `String` that defines the name of the custom route table automatically deployed by the policy (when one that contains all the *requiredRoutes* is found). 
-- **disableBgpPropagation**: A `Boolean` that defines the value of the *disableBgpRoutePropagation* property of the deployed route table. The default value is `false`.
+- **routeTableName**: A `String` that defines the name of the custom route table automatically deployed by the policy (when one that contains all the *requiredRoutes* is found).
+- **disableBgpPropagation**: A `Boolean` that defines the value of the *disableBgpRoutePropagation* property of the deployed route table. The default value is `false`.

docs/Deploy/es-schema.md

@@ -10,7 +10,7 @@ This article will help you to familiarize with the [Enterprise-Scale ARM templat
 
 ## ARM template objectives for Enterprise-Scale
 
-Some of the key [design principles](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/design-principles) of Enterprise-Scale is to have a single control and management plane, be Azure native and aligned to the platform roadmap, and employ Azure Policy to enable policy driven governance and management. That means we rely on platform capabilities in order to compose and deploy the Enterprise-Scale architecture end-2-end.
+Some of the key [design principles](https://docs.microsoft.com/azure/cloud-adoption-framework/ready/enterprise-scale/design-principles) of Enterprise-Scale is to have a single control and management plane, be Azure native and aligned to the platform roadmap, and employ Azure Policy to enable policy driven governance and management. That means we rely on platform capabilities in order to compose and deploy the Enterprise-Scale architecture end-2-end.
 
 The objectives includes:
 

docs/ESLZ-Policies.md

@@ -1,3 +1,3 @@
-## This page has moved
+# This page has moved to our Wiki
 
-Please refer to [Policies included in Azure landing zones reference implementations](./wiki/ALZ-Policies.md)
+Please refer to [Policies included in Azure Landing Zones reference implementations](https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Policies)