Add Consumer Guide (#191)

* fix navigation with missing links and add consumer guide

* linter fixes

* Update ConsumerGuide.md

* resolve comments

* remove whitespace

Co-authored-by: Jan Faurskov <22591930+jfaurskov@users.noreply.github.com>

README.md

@@ -12,6 +12,9 @@ Detailed information about how to use, deploy and extend artifacts found in this
 
 - [Home][wiki_home]
 - [Deployment Flow][wiki_deployment_flow]
+  - [Network Topology: Hub and Spoke][wiki_deployment_flow_hs]
+  - [Network Topology: Virtual WAN][wiki_deployment_flow_vwan]
+- [Consumer Guide][wiki_consumer_guide]
 - [Contributing][wiki_contributing]
 - [Telemetry Tracking Using Customer Usage Attribution (PID)][wiki_cuaid]
 - [Azure Container Registry Deployment - Private Bicep Registry][wiki_acrdeploy]
@@ -80,6 +83,9 @@ Replace `./` with `https://github.com/Azure/terraform-azurerm-caf-enterprise-sca
 
 [wiki_home]:                                  https://github.com/Azure/ALZ-Bicep/wiki/home "Wiki - Home"
 [wiki_deployment_flow]:                            https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow "Wiki - Deployment Flow"
+[wiki_deployment_flow_hs]:                            https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowHS "Wiki - Deployment Flow - Hub and Spoke"
+[wiki_deployment_flow_vwan]:                            https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowVWAN "Wiki - Deployment Flow - Virtual WAN"
+[wiki_consumer_guide]:                          https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide "Wiki - Consumer Guide"
 [wiki_contributing]:                          https://github.com/Azure/ALZ-Bicep/wiki/Contributing "Wiki - Contributing"
 [wiki_cuaid]:                          https://github.com/Azure/ALZ-Bicep/wiki/CustomerUsage "Wiki - Telemetry Usage ID"
 [wiki_acrdeploy]:                          https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment "Wiki - Private Bicep Registry"

docs/wiki/ACRDeployment.md

@@ -4,6 +4,8 @@
 
 This document outlines the prerequisites, dependencies and flow to setup a Private/Organizational Azure Container Registry.  Once deployed, you can then upload the modules contained within this repository, and deploy.
 
+> This is based on the official Bicep docs here: [Create private registry for Bicep modules](https://docs.microsoft.com/azure/azure-resource-manager/bicep/private-module-registry)
+
 ## Prerequisites
 
 1. Azure Active Directory Tenant.

docs/wiki/ConsumerGuide.md

@@ -0,0 +1,65 @@
+<!-- markdownlint-disable -->
+## How to Consume `ALZ-Bicep`
+<!-- markdownlint-restore -->
+
+## Background
+
+> This guidance supports the [Deployment Flow](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow) guidance, it is not a replacement
+
+The `ALZ-Bicep` repository (this repository) has been created to help customers and partners to deploy and deliver the [Azure Landing Zones (ALZ) conceptual architecture](https://aka.ms/alz#azure-landing-zone-conceptual-architecture) into an Azure AD Tenant utilizing [Bicep](https://aka.ms/bicep) as the Infrastructure-as-Code (IaC) tooling and language.
+
+The style in which the Bicep modules have been authored in this repo are aimed at consumers of all skill levels. This is in an effort to make the modules as accessible as possible; especially for those that are newer to the world of IaC and/or Bicep.
+
+We authored the modules with this in mind to help consumers accelerate their journey to Azure, as ALZ is likely to be one of the key first pieces of Azure a customer or partner will deploy and configure to establish the platform guardrails, connectivity and security elements to enable the future success of workloads within Azure.
+
+> More on the style of the modules can be seen in the [Contribution Guide](https://github.com/Azure/ALZ-Bicep/wiki/Contributing)
+
+## Ways to Consume `ALZ-Bicep`
+
+There are various ways to consume the Bicep modules included in `ALZ-Bicep`. The options are:
+
+- Clone this repository
+- Fork & Clone this repository
+- Download a `.zip` copy of this repo
+- Upload a copy of the locally cloned/downloaded modules to your own:
+  - Git Repository
+  - Private Bicep Module Registry
+    - See:
+      - [Azure Landing Zones - Private/Organizational Azure Container Registry Deployment (also known as private registry for Bicep modules)](https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment)
+      - [Create private registry for Bicep modules](https://docs.microsoft.com/azure/azure-resource-manager/bicep/private-module-registry)
+  - Template Specs
+    - See:
+      - [Azure Resource Manager template specs in Bicep](https://docs.microsoft.com/azure/azure-resource-manager/bicep/template-specs)
+- Use and reference the modules directly from the Microsoft Public Bicep Registry - ***Coming Soon (awaiting feature release in Bicep)***
+
+The option to use will be different per consumer based on their experience and skill levels with the various pieces of technology and their features.
+
+> Consumers can also use the above listed methods together with CI/CD pipelines to deploy the modules. See [Azure Landing Zones Bicep - Pipelines](https://github.com/Azure/ALZ-Bicep/wiki/PipelinesOverview) for more information and guidance
+
+## Customizing the `ALZ-Bicep` Modules
+
+Whatever way you may choose to consume the modules we do expect, and want, customers and partners to customize the modules to suit their needs and requirements for their design in their local copies of the modules.
+
+For example, if you want to change the names of the Management Groups, outside of what the parameters allow you to change and customize, then by opening up the `managementGroups.bicep` module you should be able to read, understand and customize the required lines to meet your requirements easily; due to the way the modules have been authored as shared above.
+
+This customized module can then be deployed into your environment to deliver the desired changes and architecture.
+
+<!-- markdownlint-disable -->
+> **IMPORTANT:** If you believe the changes you have made should be more easily available to be customized by a parameter etc. in the module, then please raise an [issue](https://github.com/Azure/ALZ-Bicep/issues) for a 'Feature Request' on the repository 👍
+> 
+> If you wish to, also feel free to submit a pull request relating to the issue which we can review and work with you to potentially implement the suggestion/feature request 👍
+<!-- markdownlint-restore -->
+
+## Considerations when Customizing the `ALZ-Bicep` Module
+
+Whilst customizing the modules on the whole is straightforward and simple, there are some key things to consider depending on which modules you customize.
+
+> See a topic or something missing from this section? Please raise an [issue](https://github.com/Azure/ALZ-Bicep/issues) on the repo and let us know and feel free to contribute a pull request also 👍
+
+### Management Groups
+
+Whilst most of the modules rely upon the Intermediate Root Management Group (e.g. `alz` or `contoso`) some of the modules, like [`alzDefaultPolicyAssignments`](https://github.com/Azure/ALZ-Bicep/tree/main/infra-as-code/bicep/modules/policy/assignments/alzDefaults) rely upon other Management Groups existing like `corp` to make policy assignments at this scope.
+
+So if you customize the Management Group hierarchy you must also change references in other modules, as shown above. These are generally held in `variables` within each module to make it easier to customize in a single location per module, rather than multiple places per module.
+
+> This is mainly in the [`alzDefaultPolicyAssignments`](https://github.com/Azure/ALZ-Bicep/tree/main/infra-as-code/bicep/modules/policy/assignments/alzDefaults) module, but this module is designed to be prescriptive in its delivery of the ALZ conceptual architecture

docs/wiki/DeploymentFlow.md

@@ -57,3 +57,7 @@ A service principal account is required to automate through Azure DevOps or GitH
 - Azure DevOps: [Setup Service Connection](https://docs.microsoft.com/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml)
 
 - GitHub: [Connect GitHub Actions to Azure](https://docs.microsoft.com/azure/developer/github/connect-from-azure)
+
+## Consumption Methods
+
+The `ALZ-Bicep` modules can be consumed and used in a manner of different ways. For more information see the [Consumer Guide](https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide)

docs/wiki/Home.md

@@ -12,6 +12,9 @@ Artefacts like policies etc. are pulled down from the [`Azure/Enterprise-Scale`
 
 * [Wiki Home][wiki_home]
 * [Deployment Flow][wiki_deployment_flow]
+  * [Network Topology: Hub and Spoke][wiki_deployment_flow_hs]
+  * [Network Topology: Virtual WAN][wiki_deployment_flow_vwan]
+* [Consumer Guide][wiki_consumer_guide]
 * [Contributing][wiki_contributing]
 * [Telemetry Tracking Using Customer Usage Attribution (PID)][wiki_cuaid]
 * [Azure Container Registry Deployment - Private Bicep Registry][wiki_acrdeploy]
@@ -32,6 +35,9 @@ Replace `./` with `https://github.com/Azure/terraform-azurerm-caf-enterprise-sca
 
 [wiki_home]:                                  https://github.com/Azure/ALZ-Bicep/wiki/home "Wiki - Home"
 [wiki_deployment_flow]:                            https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow "Wiki - Deployment Flow"
+[wiki_deployment_flow_hs]:                            https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowHS "Wiki - Deployment Flow - Hub and Spoke"
+[wiki_deployment_flow_vwan]:                            https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowVWAN "Wiki - Deployment Flow - Virtual WAN"
+[wiki_consumer_guide]:                          https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide "Wiki - Consumer Guide"
 [wiki_contributing]:                          https://github.com/Azure/ALZ-Bicep/wiki/Contributing "Wiki - Contributing"
 [wiki_acrdeploy]:                          https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment "Wiki - Private Bicep Registry"
 [wiki_cuaid]:                          https://github.com/Azure/ALZ-Bicep/wiki/CustomerUsage "Wiki - Telemetry Usage ID"

docs/wiki/_Sidebar.md

@@ -4,6 +4,7 @@
 * [Deployment Flow](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow)
   * [Network Topology: Hub and Spoke](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowHS)
   * [Network Topology: Virtual WAN](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlowVWAN)  
+* [Consumer Guide](https://github.com/Azure/ALZ-Bicep/wiki/ConsumerGuide)
 * [Contributing](https://github.com/Azure/ALZ-Bicep/wiki/Contributing)
 * [Telemetry Tracking Using Customer Usage Attribution (PID)](https://github.com/Azure/ALZ-Bicep/wiki/CustomerUsage)
 * [Azure Container Registry Deployment - Private Bicep Registry](https://github.com/Azure/ALZ-Bicep/wiki/ACRDeployment)