AVM migration module docs updates (#75)

* update docs * archiving notice * updates * readme updates * updates * updates * updates * Update README.md Co-authored-by: Jack Tracey <[email protected]> * Update README.md Co-authored-by: Jack Tracey <[email protected]> * Update README.md Co-authored-by: Jack Tracey <[email protected]> * chore: Update module reference to br/public:avm/ptn/lz/sub-vending:x.x.x * chore: Update module reference to br/public:avm/ptn/lz/sub-vending:x.x.x --------- Co-authored-by: Seif Bassem <[email protected]>
Azure · Jun 12, 2024 · 80989d5 · 80989d5
1 parent daba29d
commit 80989d5
Show file tree

Hide file tree

Showing 14 changed files with 79 additions and 121 deletions.
diff --git a/README.md b/README.md
@@ -3,11 +3,51 @@
 [![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/azure/bicep-lz-vending.svg)](http://isitmaintained.com/project/azure/bicep-lz-vending "Average time to resolve an issue")
 [![Percentage of issues still open](http://isitmaintained.com/badge/open/azure/bicep-lz-vending.svg)](http://isitmaintained.com/project/azure/bicep-lz-vending "Percentage of issues still open")
 
+_____________________________________________________________________________________________________________________________________
+
+## ⚠️⚠️ Repository archival notice ⚠️⚠️
+
+We would like to inform you that this repository has been **archived** and the Bicep landing zone vending module for Azure now has a new home in the [Bicep public registry](https://aka.ms/lz-vending/bicep) and is now a pattern module in the [Azure Verified Modules](https://aka.ms/avm) initiative.
+
+### What does this mean?
+
+- This repository is now in a **read-only** state.
+- No further issues, pull requests, or updates will be maintained on this repository.
+- All future releases, fixes and improvements will be managed in the new AVM pattern module hosted on the [Bicep public registry](https://aka.ms/lz-vending/bicep).
+- We will continue to leverage the [Wiki](https://github.com/azure/bicep-lz-vending/wiki) in this repository as the module's additional documentation and guidance location.
+
+### Why was this done?
+
+We are converting this module to be an [Azure Verified pattern module](https://aka.ms/avm) to better align with the [Azure Verified Modules](https://azure.github.io/Azure-Verified-Modules/concepts/what-why-how/) initiative. This will help us align with the Well-architected framework guidance, have improved [module support](https://azure.github.io/Azure-Verified-Modules/help-support/module-support/) and provide you with a consistent experience consuming [AVM Bicep modules](https://azure.github.io/Azure-Verified-Modules/indexes/bicep/).
+
+📒 If you are not familiar with [Azure Verified Modules](https://aka.ms/avm), you can watch the following Youtube videos for a quick overview:
+
+- [An Introduction to Azure Verified Modules (AVM) by the Customer Architecture & Engineering team](https://youtu.be/JbIMrJKW5N0?si=4v69hlyBbINufHEO) 📽️🎬🎞️
+- [Azure Verified Modules Overview by John Savill](https://youtu.be/3FeIFHaJOtg?si=ZDXJ3EPwT9Xlzq2P) 📽️🎬🎞️
+
+### If I'm already using the Bicep Subscription vending module from the Bicep public registry, what do I need to change?
+
+We tried as much as possible to have a smooth transition path with minimal breaking changes. To switch to the new module:
+
+- Review the documentation for the [new AVM module](https://aka.ms/lz-vending/bicep).
+- Change the module reference in your code to reference `br/public:avm/ptn/lz/sub-vending:x.x.x` instead of `br/public:lz/sub-vending:x.x.x`
+- If you have a preference on sharing deployment elemetry for this module, the parameter `disableTelemetry` has been changed to `enableTelemetry`. This change is due to AVM modules mandate the use of this parameter.
+
+> **NOTE:** After the migration to Azure Verified Modules, version `1.5.2` of the Subscription Vending module is now `0.1.0` in the [Bicep public registry](https://aka.ms/lz-vending/bicep).
+
+### Feedback
+
+For any issues, suggestions or feedback for this module, please open an issue on the [Bicep public registry](https://github.com/Azure/bicep-registry-modules/issues).
+
+Thank you for your understanding and continued support.
+
+__________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________;
+
 ## Overview
 
 > ℹ️ This module requires the usage of Bicep version `v0.11.1` or later. For details on installing/upgrading Bicep see: [Install Bicep tools](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install) ℹ️
 >
-> ℹ️ This module is also available on the Bicep Module Registry [here](https://github.com/Azure/bicep-registry-modules/tree/main/modules/lz/sub-vending). Examples also included in our [wiki examples](https://github.com/Azure/bicep-lz-vending/wiki/examples). ℹ️
+> ℹ️ This module is also available on the Bicep Module Registry [here](https://github.com/Azure/bicep-registry-modules/tree/main/avm/ptn/lz/sub-vending). Examples also included in our [wiki examples](https://github.com/Azure/bicep-lz-vending/wiki/examples). ℹ️
 
 The landing zone Bicep modules are designed to accelerate deployment of the individual landing zones (aka Subscriptions) within an Microsoft Entra Tenant.
 

diff --git a/docs/wiki/ConsumerGuide.md b/docs/wiki/ConsumerGuide.md
@@ -9,12 +9,12 @@ This repository has been created to help customers and partners to create, deplo
 
 ### Recommended Way to Consume
 
-The recommend way is to consume the module directly from the [Bicep public registry](https://github.com/Azure/bicep-registry-modules/tree/main/modules/lz/sub-vending#examples)
+The recommend way is to consume the module directly from the [Bicep public registry](https://aka.ms/lz-vending/bicep)
 
 ```bicep
 targetScope = 'managementGroup'
 
-module sub001 'br/public:lz/sub-vending:1.5.1' = {
+module sub001 'br/public:avm/ptn/lz/sub-vending:0.1.0' = {
   name: 'sub001'
   params: {
     subscriptionAliasEnabled: true
@@ -36,14 +36,9 @@ module sub001 'br/public:lz/sub-vending:1.5.1' = {
 
 There are a number of other ways to consume the Bicep modules included in `bicep-lz-vending`. The options are:
 
-- Creating your own GitHub Repository & Utilizing the `Invoke-GitHubReleaseFetcher.ps1` script & `gh-release-checker.yml` GitHub Action Workflow
-  - See detailed instruction on using this [below](#creating-your-own-github-repository--utilizing-the-invoke-githubreleasefetcherps1-script--gh-release-checkeryml-github-action-workflow)
-- Use and reference the modules directly from the [Bicep Module Registry (Public)](https://github.com/Azure/bicep-registry-modules)
-  - [Bicep Landing Zone (Subscription) Vending Module on Bicep Module Registry (Public)](https://github.com/Azure/bicep-registry-modules/tree/main/modules/lz/sub-vending)
-  - See a live demo using the Bicep Module Registry on the [Bicep Community Call - November 2022](https://youtu.be/hu0PgCamxt0?t=1038) 📽️🎬🎞️
-- Clone this repository
-- Fork & Clone this repository
-- Download a `.zip` copy of this repo
+- Clone [this repository](https://aka.ms/brm)
+- Fork & Clone [this repository](https://aka.ms/brm)
+- Download a `.zip` copy of [this repo](https://aka.ms/brm)
 - Upload a copy of the locally cloned/downloaded modules to your own:
   - Git Repository
   - Private Bicep Module Registry
@@ -54,25 +49,3 @@ There are a number of other ways to consume the Bicep modules included in `bicep
       - [Azure Resource Manager template specs in Bicep](https://docs.microsoft.com/azure/azure-resource-manager/bicep/template-specs)
 
 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.
-
-## Creating your own GitHub Repository & Utilizing the `Invoke-GitHubReleaseFetcher.ps1` script & `gh-release-checker.yml` GitHub Action Workflow
-
-We have created a GitHub Action Workflow ([`gh-release-checker.yml`](https://github.com/Azure/bicep-lz-vending/blob/main/.github/workflows/gh-release-checker.yml)) and a supporting PowerShell script ([`Invoke-GitHubReleaseFetcher.ps1`](https://github.com/Azure/bicep-lz-vending/blob/main/.github/scripts/Invoke-GitHubReleaseFetcher.ps1)) that enables you to place only these 2 into a new GitHub repository and then either manually trigger the workflow or leave it to trigger on its schedule (every weekday at 00:00) and it will check for the latest releases available from this repository, `Azure/bicep-lz-vending`, and create a Pull Request into a `./releases/<VERSION>` folder in your repository.
-
-### Steps to use this method, action & scripts
-
-1. Create a new GitHub repository
-   - See [Create a repo](https://docs.github.com/get-started/quickstart/create-a-repo) for guidance
-2. Copy the [`Invoke-GitHubReleaseFetcher.ps1`](https://github.com/Azure/bicep-lz-vending/blob/main/.github/scripts/Invoke-GitHubReleaseFetcher.ps1) script into the following location in your new GitHub repository: `.github/scripts/`
-3. Copy the [`gh-release-checker.yml`](https://github.com/Azure/bicep-lz-vending/blob/main/.github/workflows/gh-release-checker.yml) GitHub Action into the following location in your new GitHub repository: `.github/workflows/`
-4. Commit these files into the `main` (default branch) in your GitHub repository
-5. Manually trigger the GitHub action called: `Check & Pull Latest Upstream GitHub Release` from the "Actions" blade in your GitHub repository
-   - Further guidance on this can be found here in [Manually running a workflow](https://docs.github.com/actions/managing-workflow-runs/manually-running-a-workflow)
-6. A Pull Request should now exist on your GitHub Repository like shown below:
-
-![Pull Request Screenshot](img/release-checker-pr.png)
-
-7. Review the Pull Request, approve and merge it into your `main` (default branch) into your GitHub repository
-8. You will now have the latest release from the `Azure/bicep-lz-vending` repository available in its own folder, based on the release version number, within the `releases` folder of your GitHub repository
-9. Create a `landingZones` folder in the root of your GitHub repository to contain your individual parameter files for each of the landing zone Subscriptions you wish to provision
-10. You can now build your own GitHub Actions to deploy your landing zone Subscriptions based on the `main.bicep` module being available from the `./releases/<VERSION>` folder and then you are in full control of moving to newer release of the Bicep Landing Zone (aka Subscription) vending module, but the process checking and pulling in the latest release is automatically handled for you by the above mentioned GitHub Action and PowerShell script.
diff --git a/docs/wiki/Contributing.md b/docs/wiki/Contributing.md
@@ -8,12 +8,7 @@
 - [Tooling](#tooling)
   - [Required Tooling](#required-tooling)
   - [Recommended Tooling](#recommended-tooling)
-- [Bicep Formatting Guidelines](#bicep-formatting-guidelines)
-  - [Bicep Best Practices](#bicep-best-practices)
-  - [Bicep Code Styling](#bicep-code-styling)
-  - [Bicep Module Documentation](#bicep-module-documentation)
-  - [Resource API Versions](#resource-api-versions)
-- [Git Information on Contributing](#git-information-on-contributing)
+- [Azure Verified Modules (AVM) contribution guide](#azure-verified-modules-avm-contribution-guide)
 
 ---
 
@@ -56,57 +51,8 @@ The following tooling/extensions are recommended to assist you developing for th
 - For visibility of Bracket Pairs:
   - Inside Visual Studio Code, add `"editor.bracketPairColorization.enabled": true` to your `settings.json`, to enable bracket pair colorization.
 
-## Bicep Formatting Guidelines
+## Azure Verified Modules (AVM) contribution guide
 
-The below guidelines should be adhered to whilst contributing to this projects Bicep code.
+Please follow the [contribution guide](https://azure.github.io/Azure-Verified-Modules/contributing/) in the AVM documentation and review [module specifications](https://azure.github.io/Azure-Verified-Modules/specs/module-specs/).
 
-### Bicep Best Practices
 
-Throughout the development of Bicep code you should follow the [Bicep Best Practices](https://docs.microsoft.com/azure/azure-resource-manager/bicep/best-practices).
-
-> It is suggested to keep this page open whilst developing for easy reference
-
-### Bicep Code Styling
-
-- Strict `camelCasing` must be used for all elements:
-  - Symbolic names for:
-    - Parameters
-    - Variables
-    - Resource
-    - Modules
-    - Outputs
-- Use [parameter decorators](https://docs.microsoft.com/azure/azure-resource-manager/bicep/parameters#decorators) to ensure integrity of user inputs are complete and therefore enable successful deployment
-  - Only use the [`@secure()` parameter decorator](https://docs.microsoft.com/azure/azure-resource-manager/bicep/parameters#secure-parameters) for inputs. Never for outputs as this is not stored securely and will be stored/shown as plain-text!
-- Comments should be provided where additional information/description of what is happening is required, except when a decorator like `@sys.description('Example description')` is providing adequate coverage
-  - Single-line `// <comment here>` and multi-line `/* <comment here> */` comments are both welcomed
-  - Provide contextual public Microsoft documentation recommendation references/URLs in comments to help user understanding of code implementation
-- All expressions, used in conditionals and loops, should be stored in a variable to simplify code readability
-- Specify default values for all parameters where possible - this improves deployment success
-  - The default value should be called out in the description of the parameter for ease of visibility
-  - Default values should also be documented in the appropriate location
-- Tab indents should be set to `2` for all Bicep files
-- Double line-breaks should exist between each element type section
-- When intended for scopes above resource group deployment, targetScope should be indicated at the beginning of the file
-- All parameters and outputs must have the following decorators:
-  - `description` or `sys.description` (see below for more info)
-  - `metadata` with an key called `example` key that has a value of an example parameter input value (see below for more info)
-
-### Bicep Module Documentation
-
-The [`main.bicep`](../../main.bicep) module has it's documentation automatically generated using [PSDocs.Azure](https://azure.github.io/PSDocs.Azure) from the Bicep module file itself and [this GitHub Action](../../.github/workflows/update-bicep-module-docs.yml) as part of PRs that amend this Bicep module.
-
-Therefore, any changes made to the [`main.bicep.parameters.md`](../../main.bicep.parameters.md) file will not be accepted. Any changes to this file must be added to the [`main.bicep`](../../main.bicep) as decorators of either `description` or `metadata`. The PSDocs for Azure tooling details how metadata is used to generate documentation
-
-> **Note:** the `@description` decorator in the `main.bicep` module specifically references the namespace of `sys` and is therefore shown as `@sys.description()` in the module. This is because there is a `metadata` resource that uses the name of `description` which therefore means we need to tell Bicep that it must use the `sys` namespace for all other instances of the `description` decorator usage instead of trying to refer to this `metadata` resource called `description`. More info on this can be found here [Namespaces for functions](https://learn.microsoft.com/azure/azure-resource-manager/bicep/bicep-functions#namespaces-for-functions)
-
-### Resource API Versions
-
-Each resource must use the latest available, working, API version. If the latest API version cannot be used for any reason, a comment must be placed above the resource in the module file stating why and also called out as part of the PR.
-
-> The Bicep linter rule `use-recent-api-versions` will now also check for this 👍
-
-## Git Information on Contributing
-
-To make contributions to this repo you must fork and clone this repo. You can follow the guidance here on how to do this [Fork a repo](https://docs.github.com/get-started/quickstart/fork-a-repo)
-
-You **will not** be able to create a branch or push directly to this repo. All changes into this repo **must** be made via a Pull Request. This process is documented here: [Contributing to projects](https://docs.github.com/get-started/quickstart/contributing-to-projects)
diff --git a/docs/wiki/Example-1-Hub-and-Spoke.md b/docs/wiki/Example-1-Hub-and-Spoke.md
@@ -3,15 +3,15 @@
 
 ### Bicep Module Registry
 
-Here is a simple example Bicep file for deploying a landing zone (Subscription) with a spoke Virtual Network peered to a Hub Virtual Network using the [Bicep Module Registry](https://github.com/Azure/bicep-registry-modules):
+Here is a simple example Bicep file for deploying a landing zone (Subscription) with a spoke Virtual Network peered to a Hub Virtual Network using the [Bicep Module Registry](https://aka.ms/lz-vending/bicep):
 
 ```bicep
 targetScope = 'managementGroup'
 
 @description('Specifies the location for resources.')
 param location string = 'uksouth'
 
-module sub003 'br/public:lz/sub-vending:1.5.1' = {
+module sub003 'br/public:avm/ptn/lz/sub-vending:0.1.0' = {
   name: 'sub-bicep-lz-vending-example-001'
   params: {
     subscriptionAliasEnabled: true
@@ -160,8 +160,8 @@ Here is a simple example parameter file for deploying a landing zone (Subscripti
         }
       ]
     },
-    "disableTelemetry": {
-      "value": false
+    "enableTelemetry": {
+      "value": true
     }
   }
 }

diff --git a/docs/wiki/Example-2-Virtual-WAN.md b/docs/wiki/Example-2-Virtual-WAN.md
@@ -3,15 +3,15 @@
 
 ### Bicep Module Registry
 
-Here is a simple example Bicep file for deploying a landing zone (Subscription) with a spoke Virtual Network peered to a Virtual WAN Hub using the [Bicep Module Registry](https://github.com/Azure/bicep-registry-modules):
+Here is a simple example Bicep file for deploying a landing zone (Subscription) with a spoke Virtual Network peered to a Virtual WAN Hub using the [Bicep Module Registry](https://aka.ms/lz-vending/bicep):
 
 ```bicep
 targetScope = 'managementGroup'
 
 @description('Specifies the location for resources.')
 param location string = 'uksouth'
 
-module sub002 'br/public:lz/sub-vending:1.5.1' = {
+module sub002 'br/public:avm/ptn/lz/sub-vending:0.1.0' = {
   name: 'sub-bicep-lz-vending-example-002'
   params: {
     subscriptionAliasEnabled: true
@@ -162,8 +162,8 @@ Here is a simple example parameter file for deploying a landing zone (Subscripti
         }
       ]
     },
-    "disableTelemetry": {
-      "value": false
+    "enableTelemetry": {
+      "value": true
     }
   }
 }

diff --git a/docs/wiki/Example-3-Use-With-Existing-Subscriptions.md b/docs/wiki/Example-3-Use-With-Existing-Subscriptions.md
@@ -3,15 +3,15 @@
 
 ### Bicep Module Registry
 
-Here is a simple example Bicep file for deploying a landing zone (Subscription) with a spoke Virtual Network peered to a Virtual WAN Hub using the [Bicep Module Registry](https://github.com/Azure/bicep-registry-modules):
+Here is a simple example Bicep file for deploying a landing zone (Subscription) with a spoke Virtual Network peered to a Virtual WAN Hub using the [Bicep Module Registry](https://aka.ms/lz-vending/bicep):
 
 ```bicep
 targetScope = 'managementGroup'
 
 @description('Specifies the location for resources.')
 param location string = 'uksouth'
 
-module sub003 'br/public:lz/sub-vending:1.5.1' = {
+module sub003 'br/public:avm/ptn/lz/sub-vending:0.1.0' = {
   name: 'sub003'
   params: {
     subscriptionAliasEnabled: false
@@ -160,8 +160,8 @@ Here is a simple example parameter file for deploying a landing zone (Subscripti
         }
       ]
     },
-    "disableTelemetry": {
-      "value": false
+    "enableTelemetry": {
+      "value": true
     }
   }
 }

diff --git a/docs/wiki/Example-4-Multiple-VNets-In-Same-Subscription.md b/docs/wiki/Example-4-Multiple-VNets-In-Same-Subscription.md
@@ -3,15 +3,15 @@
 
 ### Bicep Module Registry
 
-Here is a simple example Bicep file for deploying a landing zone (Subscription) with multiple spoke Virtual Networks peered to a Virtual WAN Hub using the [Bicep Module Registry](https://github.com/Azure/bicep-registry-modules):
+Here is a simple example Bicep file for deploying a landing zone (Subscription) with multiple spoke Virtual Networks peered to a Virtual WAN Hub using the [Bicep Module Registry](https://aka.ms/lz-vending/bicep):
 
 ```bicep
 targetScope = 'managementGroup'
 
 @description('Specifies the location for resources.')
 param location string = 'uksouth'
 
-module createSubAndFirstVnet 'br/public:lz/sub-vending:1.5.1' = {
+module createSubAndFirstVnet 'br/public:avm/ptn/lz/sub-vending:0.1.0' = {
   name: 'sub-with-multiple-vnets'
   params: {
     subscriptionAliasEnabled: true
@@ -37,7 +37,7 @@ module createSubAndFirstVnet 'br/public:lz/sub-vending:1.5.1' = {
   }
 }
 
-module createSubAndSecondVnet 'br/public:lz/sub-vending:1.5.1' = {
+module createSubAndSecondVnet 'br/public:avm/ptn/lz/sub-vending:0.1.0' = {
   name: 'additional-vnet'
   params: {
     subscriptionAliasEnabled: false