Documentation: Enhancements and adjustments to documentation

infra-as-code/bicep/modules/mgDiagSettings/README.md

@@ -21,49 +21,67 @@ The inputs for this module are defined in `parameters/mgDiagSettings.parameters.
 
 ```bash
 # For Azure global regions
-az deployment mg create \
-  --template-file infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep \
-  --parameters @infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json \
-  --location eastus \
-  --management-group-id alz
+
+dateYMD=$(date +%Y%m%dT%H%M%S%NZ)
+NAME="alz-mgDiagSettings-${dateYMD}"
+LOCATION="eastus"
+TEMPLATEFILE="infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep"
+PARAMETERS="infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json"
+# Set the top level Management Group ID in accordance to your environment. This example assumes default 'alz'.
+MGID="alz"
+
+az deployment mg create --name $NAME --location $LOCATION --template-file $TEMPLATEFILE --parameters $PARAMETERS --management-group-id $MGID
 ```
 
 OR
 
 ```bash
 # For Azure China regions
-az deployment mg create \
-  --template-file infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep \
-  --parameters @infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json \
-  --location chinaeast2 \
-  --management-group-id alz
+
+dateYMD=$(date +%Y%m%dT%H%M%S%NZ)
+NAME="alz-mgDiagSettings-${dateYMD}"
+LOCATION="chinaeast2"
+TEMPLATEFILE="infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep"
+PARAMETERS="infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json"
+# Set the top level Management Group ID in accordance to your environment. This example assumes default 'alz'.
+MGID="alz"
+
+az deployment mg create --name $NAME --location $LOCATION --template-file $TEMPLATEFILE --parameters $PARAMETERS --management-group-id $MGID
 ```
 
 ### PowerShell
 
 ```powershell
 # For Azure global regions
-New-AzManagementGroupDeployment `
-  -TemplateFile infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep `
-  -TemplateParameterFile @infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json `
-  -Location eastus `
-  -ManagementGroupId alz
+
+$inputObject = @{
+  DeploymentName        = 'alz-mgDiagSettings-{0}' -f (-join (Get-Date -Format 'yyyyMMddTHHMMssffffZ')[0..63])
+  Location              = 'eastus'
+  TemplateFile          = "infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep"
+  TemplateParameterFile = 'infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json'
+  ManagementGroupId     = 'alz'
+}
+New-AzManagementGroupDeployment @inputObject
 ```
 
 OR
 
 ```powershell
 # For Azure China regions
-New-AzManagementGroupDeployment `
-  -TemplateFile infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep `
-  -TemplateParameterFile @infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json `
-  -Location chinaeast2 `
-  -ManagementGroupId alz
+
+$inputObject = @{
+  DeploymentName        = 'alz-mgDiagSettings-{0}' -f (-join (Get-Date -Format 'yyyyMMddTHHMMssffffZ')[0..63])
+  Location              = 'chinaeast2'
+  TemplateFile          = "infra-as-code/bicep/modules/mgDiagSettings/mgDiagSettings.bicep"
+  TemplateParameterFile = 'infra-as-code/bicep/modules/mgDiagSettings/parameters/mgDiagSettings.parameters.all.json'
+  ManagementGroupId     = 'alz'
+}
+New-AzManagementGroupDeployment @inputObject
 ```
 
 ## Validation
 
-To validate if Diagnostic Settings was correctly enabled for any specific management group, a REST API GET call can be used. Documentation and easy way to try this can be found in this link [(Management Group Diagnostic Settings - Get)](https://learn.microsoft.com/rest/api/monitor/management-group-diagnostic-settings/get?tabs=HTTP&tryIt=true&source=docs#code-try-0). There is currently not a direct way to validate this in the Azure Portal, Azure CLI or PowerShell.
+To validate if Diagnostic Settings were correctly enabled for any specific management group, a REST API GET call can be used. Documentation and easy way to try this can be found in this link [(Management Group Diagnostic Settings - Get)](https://learn.microsoft.com/rest/api/monitor/management-group-diagnostic-settings/get?tabs=HTTP&tryIt=true&source=docs#code-try-0). There is currently not a direct way to validate this in the Azure Portal or with Azure PowerShell or the Azure CLI.
 
 ## Bicep Visualizer
 

infra-as-code/bicep/modules/spokeNetworking/README.md

@@ -1,20 +1,16 @@
 # Module: Spoke Networking
 
+> [!IMPORTANT]
+> We recommend utilizing the [Bicep Landing Zone Vending Module](https://github.com/Azure/bicep-lz-vending) in place of this Spoke Networking Module. Not only does the module handle spoke networking, but it also handles many other aspects of setting up the > foundational components of the application landing zones which are out of scope for this module.
+
 This module defines spoke networking based on the recommendations from the Azure Landing Zone Conceptual Architecture. If enabled spoke will route traffic to Hub Network with NVA.
 
 Module deploys the following resources:
 
 - Virtual Network (Spoke VNet)
 - Route Table with route to NVA - if Firewall is enabled
 
-> ## Note
->
-> ### Orchestration
->
-> Consider using the `hubPeeredSpoke` orchestration module instead to simplify spoke networking deployment, VNET Peering, UDR configuration and Subscription placement in a single module. [infra-as-code/bicep/orchestration/hubPeeredSpoke](https://github.com/Azure/ALZ-Bicep/tree/main/infra-as-code/bicep/orchestration/hubPeeredSpoke)
->
-> ### Subnet Declaration
->
+> [!NOTE]
 > This module only deploys the skeleton of a virtual network. Subnet(s) are not created nor does this module support declaring them. This is a blank vNet with the expectation of handing it over to the app/workload team to create their subnet(s), etc. The ALZ-Bicep core team decided not to add subnet support due to:
 >
 > - Complexity of managing all of the subnet properties, including NSG, UDR, service endpoints, subnet delegations, etc.
@@ -24,7 +20,7 @@ Module deploys the following resources:
 >
 > To customize spoke networking to include subnet declarations, we recommend the use of the following ordered methods:
 >
-> 1. [CARML](https://aka.ms/carml) - Utilize this mature Bicep repo for resource deployments
+> 1. [AVM](https://aka.ms/avm) - Utilize Azure Verified Modules to deploy the subnets
 > 2. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repo and customize the modules accordingly
 > 3. Write your own custom module
 

infra-as-code/bicep/orchestration/hubPeeredSpoke/README.md

@@ -1,5 +1,9 @@
 # Module: Orchestration - hubPeeredSpoke - Spoke network, including peering to Hub (Hub & Spoke or Virtual WAN)
 
+> [!IMPORTANT]
+> We recommend utilizing the [Bicep Landing Zone Vending Module](https://github.com/Azure/bicep-lz-vending) in place of this Spoke Networking Module. Not only does the module handle spoke networking, but it also handles many other aspects of setting up the > foundational components of the application landing zones which are out of scope for this module.
+
+
 This module acts as an orchestration module that create and configures a spoke network to deliver the Azure Landing Zone Hub & Spoke architecture, for both traditional Hub & Spoke and Virtual WAN, which is also described in the wiki on the [Deployment Flow article](https://github.com/Azure/ALZ-Bicep/wiki/DeploymentFlow).
 
 Module deploys the following resources:

infra-as-code/bicep/orchestration/mgDiagSettingsAll/README.md

@@ -83,6 +83,38 @@ In this example, the Diagnostic Settings are enabled on the management groups th
 
 > For the examples below we assume you have downloaded or cloned the Git repo as-is and are in the root of the repository as your selected directory in your terminal of choice.
 
+You will also need to ensure you have the Microsoft.Insights resource provider registered in the Management subscription.
+
+You can utilize this script to check if the resource provider is registered, and if not, register it:
+```powershell
+# Registering 'Microsoft.Insights' resource provider on the Management subscription
+Select-AzSubscription -SubscriptionId $ManagementSubscriptionId
+
+$providers = @('Microsoft.insights')
+
+foreach ($provider in $providers ) {
+  $iterationCount = 0
+  $maxIterations = 30
+  $providerStatus = (Get-AzResourceProvider -ListAvailable | Where-Object ProviderNamespace -eq $provider).registrationState
+  if ($providerStatus -ne 'Registered') {
+    Write-Output "`n Registering the '$provider' provider"
+    Register-AzResourceProvider -ProviderNamespace $provider
+    do {
+      $providerStatus = (Get-AzResourceProvider -ListAvailable | Where-Object ProviderNamespace -eq $provider).registrationState
+      $iterationCount++
+      Write-Output "Waiting for the '$provider' provider registration to complete....waiting 10 seconds"
+      Start-Sleep -Seconds 10
+    } until ($providerStatus -eq 'Registered' -and $iterationCount -ne $maxIterations)
+    if ($iterationCount -ne $maxIterations) {
+      Write-Output "`n The '$provider' has been registered successfully"
+    }
+    else {
+      Write-Output "`n The '$provider' has not been registered successfully"
+    }
+  }
+}
+```
+
 ### Azure CLI
 
 ```bash