QoL: Bicep formatting & commenting, learn links, and typos (#59)

.ado/README.md

@@ -1,21 +1,25 @@
 # Azure Pipeline Deployment
+
 If you'd like to use an Azure Pipeline to deploy the ACA Landing Zone Accelerator, you will need:
+
 - A fork of the ACA Landing Zone repository
 - An Azure DevOps project
-- A [service connection](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml) available for your pipeline that connects to your Azure subscription
+- A [service connection](https://learn.microsoft.com/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml) available for your pipeline that connects to your Azure subscription
 - A variable group called "ACA-LZA" that contains the following variables:
   - location: The location of where you want the Azure resources deployed
   - azureServiceConnection: the name of the service connection you created in the previous step
 
-# Create your pipeline
+## Create your pipeline
+
 After you've created the items in the previous step, follow these instructions for creating your pipeline.
-1. Navigate into your Azure DevOps projects and click on Pipelines on the left sidebar. 
-2. Click *New Pipeline* in the upper right hand corner of the window or the *create pipeline* button in the middle if this is your first pipeline.
-3. Select *GitHub* as the source for your YAML. 
-4. Select your repository in GitHub. If you don't already have the Azure Pipeline app installed in your GitHub repository, it will prompt you to enable that and redirect you back to this creation screen.
-5. Select *Existing Azure Pipelines YAML file*, select the main branch and the file *lza-deployment-bicep.yaml*.
-6. Once you select the file, hit next and then click *Run* in the upper right hand corner of the *Review* tab. If you don't want to run it immediately, you can click the dropdown on the *Run* button and choose to save it. 
+
+1. Navigate into your Azure DevOps projects and click on Pipelines on the left sidebar.
+1. Click *New Pipeline* in the upper right hand corner of the window or the *create pipeline* button in the middle if this is your first pipeline.
+1. Select *GitHub* as the source for your YAML.
+1. Select your repository in GitHub. If you don't already have the Azure Pipeline app installed in your GitHub repository, it will prompt you to enable that and redirect you back to this creation screen.
+1. Select *Existing Azure Pipelines YAML file*, select the main branch and the file *lza-deployment-bicep.yaml*.
+1. Once you select the file, hit next and then click *Run* in the upper right hand corner of the *Review* tab. If you don't want to run it immediately, you can click the dropdown on the *Run* button and choose to save it.
 
 ### Note
-When you first run your pipeline, you may need to give the pipeline permission to access the service connection and the variable group. This will only occur the first time you run the pipeline. 
 
+When you first run your pipeline, you may need to give the pipeline permission to access the service connection and the variable group. This will only occur the first time you run the pipeline.

docs/design-areas/identity.md

@@ -18,6 +18,6 @@
 
 - Use system-assigned managed identities unless there is a strong requirement for using user-managed identities
 
-- Use Azure [built-in roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#web-plan-contributor) to assign least privilege permissions to resources and users. 
+- Use Azure [built-in roles](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#web-plan-contributor) to assign least privilege permissions to resources and users.
 
-- Ensure that access to production environments is limited. Ideally, no one has standing access to production environment, instead relying on automation to handle deployments and [Privileged Identity Management](https://learn.microsoft.com/azure/active-directory/privileged-identity-management/pim-configure) for emergency access. 
+- Ensure that access to production environments is limited. Ideally, no one has standing access to production environment, instead relying on automation to handle deployments and [Privileged Identity Management](https://learn.microsoft.com/azure/active-directory/privileged-identity-management/pim-configure) for emergency access.

docs/design-areas/security.md

@@ -5,9 +5,9 @@ Security is a one of the foundational design principles and also a key design ar
 ---
 ### Design Area Considerations
 
-- Cloud application security in enterprise environments is built in a layered approach. Microsoft provides recommendations for securing your application, as does the enterprise security organization governing cloud solutions. Finally, the solution developer has a responsibility to implement the appropriate security measures for the solution. 
-    - The [Container Apps security profile](https://learn.microsoft.com/security/benchmark/azure/baselines/azure-container-apps-security-baseline) from the Microsoft [Cloud Security Benchmark](https://learn.microsoft.com/en-us/security/benchmark/azure/overview) provides a good starting point
-    - The [Azure Landing Zone security documentation](https://learn.microsoft.com/azure/cloud-adoption-framework/secure/), part of the Cloud Adoption Framework, provides an additional security view on Landing Zones. 
+- Cloud application security in enterprise environments is built in a layered approach. Microsoft provides recommendations for securing your application, as does the enterprise security organization governing cloud solutions. Finally, the solution developer has a responsibility to implement the appropriate security measures for the solution.
+    - The [Container Apps security profile](https://learn.microsoft.com/security/benchmark/azure/baselines/azure-container-apps-security-baseline) from the Microsoft [Cloud Security Benchmark](https://learn.microsoft.com/security/benchmark/azure/overview) provides a good starting point
+    - The [Azure Landing Zone security documentation](https://learn.microsoft.com/azure/cloud-adoption-framework/secure/), part of the Cloud Adoption Framework, provides an additional security view on Landing Zones.
 
 - Azure Container Apps allows for _internal_ and _external_ connectivity models. This allows for connecting the Container Apps to the outside world directly or not at all. In this Landing Zone Accelerator, we recommend the _internal_ model and assume that the application will be either fully internal facing or will be published externally through a service that adds the appropriate security controls, such as Azure Application Gateway. The security architecture would then look as follows (the box with Application Gateway being optional in internal-facing scenarios):
 ![ACA Hub and Spoke architecture](../media/acaInternal/aca-internal.png)
@@ -26,8 +26,8 @@ Security is a one of the foundational design principles and also a key design ar
 
 ## References
 
-- [Container Apps security profile](https://learn.microsoft.com/security/benchmark/azure/baselines/azure-container-apps-security-baseline) 
-- [Cloud Security Benchmark](https://learn.microsoft.com/en-us/security/benchmark/azure/overview)
-- [Securing a custom VNET in Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/firewall-integration)
+- [Container Apps security profile](https://learn.microsoft.com/security/benchmark/azure/baselines/azure-container-apps-security-baseline)
+- [Cloud Security Benchmark](https://learn.microsoft.com/security/benchmark/azure/overview)
+- [Securing a custom VNET in Azure Container Apps](https://learn.microsoft.com/azure/container-apps/firewall-integration)
 - [Azure Landing Zone security documentation](https://learn.microsoft.com/azure/cloud-adoption-framework/secure/)
 

scenarios/aca-internal/bicep/main.bicep

@@ -5,10 +5,10 @@ targetScope = 'subscription'
 // ------------------
 @minLength(2)
 @maxLength(10)
-@description('The name of the workloard that is being deployed. Up to 10 characters long.')
+@description('The name of the workload that is being deployed. Up to 10 characters long.')
 param workloadName string = 'aca-lza'
 
-@description('The name of the environment (e.g. "dev", "test", "prod", "uat", "dr", "qa") Up to 8 characters long.')
+@description('The name of the environment (e.g. "dev", "test", "prod", "uat", "dr", "qa"). Up to 8 characters long.')
 @maxLength(8)
 param environment string = 'test'
 
@@ -33,7 +33,7 @@ param enableBastion bool
 param bastionSubnetAddressPrefix string
 
 // Hub Virtual Machine
-@description('The size of the virtual machine to create. See https://docs.microsoft.com/en-us/azure/virtual-machines/sizes for more information.')
+@description('The size of the virtual machine to create. See https://learn.microsoft.com/azure/virtual-machines/sizes for more information.')
 param vmSize string
 
 @description('The username to use for the virtual machine.')
@@ -78,8 +78,8 @@ param enableDaprInstrumentation bool
 @description('Enable or disable the deployment of the Hello World Sample App. If disabled, the Application Gateway will not be deployed.')
 param deployHelloWorldSample bool
 
-@description('The FQDN of the Application Gateawy. Must match the TLS Certificate.')
-param applicationGatewayFQDN string
+@description('The FQDN of the Application Gateway. Must match the TLS Certificate.')
+param applicationGatewayFqdn string
 
 @description('Enable or disable Application Gateway Certificate (PFX).')
 param enableApplicationGatewayCertificate bool
@@ -197,8 +197,8 @@ module applicationGateway 'modules/06-application-gateway/deploy.app-gateway.bic
     environment: environment
     workloadName: workloadName
     applicationGatewayCertificateKeyName: applicationGatewayCertificateKeyName
-    applicationGatewayFQDN: applicationGatewayFQDN
-    applicationGatewayPrimaryBackendEndFQDN: (deployHelloWorldSample) ? helloWorlSampleApp.outputs.helloWorldAppFQDN : '' // To fix issue when hello world is not deployed
+    applicationGatewayFqdn: applicationGatewayFqdn
+    applicationGatewayPrimaryBackendEndFqdn: (deployHelloWorldSample) ? helloWorlSampleApp.outputs.helloWorldAppFqdn : '' // To fix issue when hello world is not deployed
     applicationGatewaySubnetId: spoke.outputs.spokeApplicationGatewaySubnetId
     enableApplicationGatewayCertificate: enableApplicationGatewayCertificate
     keyVaultId: supportingServices.outputs.keyVaultId

scenarios/aca-internal/bicep/main.parameters.jsonc

@@ -2,7 +2,7 @@
   "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
   "contentVersion": "1.0.0.0",
   "parameters": {
-    // The name of the workloard that is being deployed. Up to 10 characters long. This wil be used as part of the naming convention (i.e. as defined here: https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming) 
+    // The name of the workload that is being deployed. Up to 10 characters long. This wil be used as part of the naming convention (i.e. as defined here: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming) 
     "workloadName": {
       "value": "lzaaca"
     },
@@ -75,8 +75,8 @@
     "deployHelloWorldSample": {
       "value": true
     },
-    // The FQDN of the Application Gateawy. Must match the TLS Certificate. 
-    "applicationGatewayFQDN": {
+    // The FQDN of the Application Gateway. Must match the TLS Certificate. 
+    "applicationGatewayFqdn": {
       "value": "acahello.demoapp.com"
     },
     "enableApplicationGatewayCertificate": {

scenarios/aca-internal/bicep/modules/01-hub/deploy.hub.bicep

@@ -6,10 +6,10 @@ targetScope = 'subscription'
 
 @minLength(2)
 @maxLength(10)
-@description('The name of the workloard that is being deployed. Up to 10 characters long.')
+@description('The name of the workload that is being deployed. Up to 10 characters long.')
 param workloadName string
 
-@description('The name of the environment (e.g. "dev", "test", "prod", "uat", "dr", "qa") Up to 8 characters long.')
+@description('The name of the environment (e.g. "dev", "test", "prod", "uat", "dr", "qa"). Up to 8 characters long.')
 @maxLength(8)
 param environment string
 
@@ -22,38 +22,37 @@ param hubResourceGroupName string = ''
 @description('Optional. The tags to be assigned to the created resources.')
 param tags object = {}
 
-@description('CIDR of the Hub Virtual Network.')
+@description('CIDR of the hub virtual network.')
 param vnetAddressPrefixes array
 
-// Bastion
 @description('Enable or disable the creation of the Azure Bastion.')
 param enableBastion bool
 
 @description('CIDR to use for the Azure Bastion subnet.')
 param bastionSubnetAddressPrefix string
 
-@description('The size of the virtual machine to create. See https://docs.microsoft.com/en-us/azure/virtual-machines/sizes for more information.')
+@description('The size of the jump box virtual machine to create. See https://learn.microsoft.com/azure/virtual-machines/sizes for more information.')
 param vmSize string
 
-@description('The username to use for the virtual machine.')
+@description('The username to use for the jump box.')
 param vmAdminUsername string
 
-@description('The password to use for the virtual machine.')
+@description('The password to use for the jump box.')
 @secure()
 param vmAdminPassword string
 
-@description('The SSH public key to use for the virtual machine.')
+@description('The SSH public key to use for the jump box. Only relevant for Linux.')
 @secure()
 param vmLinuxSshAuthorizedKeys string
 
-@description('The type of the virtual machine OS to create. If set to "none", no virtual machine will be created.')
-@allowed(['linux', 'windows', 'none'])
+@description('The OS of the jump box virtual machine to create. If set to "none", no jump box will be created.')
+@allowed([ 'linux', 'windows', 'none' ])
 param vmJumpboxOSType string = 'none'
 
-@description('Optional. The name of the subnet to create for the virtual machine. If set, it overrides the name generated by the template.')
+@description('Optional. The name of the subnet to create for the jump box. If set, it overrides the name generated by the template.')
 param vmSubnetName string = 'snet-jumpbox'
 
-@description('CIDR to use for the virtual machine subnet.')
+@description('CIDR to use for the jump box subnet.')
 param vmJumpBoxSubnetAddressPrefix string
 
 // ------------------
@@ -68,39 +67,40 @@ var bastionSubnetName = 'AzureBastionSubnet'
 
 // Append optional bastion subnet, if required
 var subnets = enableBastion ? concat(defaultSubnets, [
-  {
-    name: bastionSubnetName
-    properties: {
-      addressPrefix: bastionSubnetAddressPrefix
+    {
+      name: bastionSubnetName
+      properties: {
+        addressPrefix: bastionSubnetAddressPrefix
+      }
     }
-  }
-]) : defaultSubnets
+  ]) : defaultSubnets
 
 //Append optional jumpbox subnet, if required
 var vnetSubnets = vmJumpboxOSType != 'none' ? concat(subnets, [
-  {
-    name: vmSubnetName
-    properties: {
-     addressPrefix: vmJumpBoxSubnetAddressPrefix       
-    }        
-  }
-]) : subnets
+    {
+      name: vmSubnetName
+      properties: {
+        addressPrefix: vmJumpBoxSubnetAddressPrefix
+      }
+    }
+  ]) : subnets
 
 //used only to override the RG name - because it is created at the subscription level, the naming module cannot be loaded/used
 var namingRules = json(loadTextContent('../../../../shared/bicep/naming/naming-rules.jsonc'))
 var rgHubName = !empty(hubResourceGroupName) ? hubResourceGroupName : '${namingRules.resourceTypeAbbreviations.resourceGroup}-${workloadName}-hub-${environment}-${namingRules.regionAbbreviations[toLower(location)]}'
 
-
 // ------------------
-// RESOURCES"TCP"
+// RESOURCES
 // ------------------
 
+@description('The hub resource group. This would normally be already provisioned by your platform team.')
 resource hubResourceGroup 'Microsoft.Resources/resourceGroups@2021-04-01' = {
   name: rgHubName
   location: location
   tags: tags
 }
 
+@description('User-configured naming rules')
 module naming '../../../../shared/bicep/naming/naming.module.bicep' = {
   scope: hubResourceGroup
   name: take('01-sharedNamingDeployment-${deployment().name}', 64)
@@ -112,6 +112,7 @@ module naming '../../../../shared/bicep/naming/naming.module.bicep' = {
   }
 }
 
+@description('The virtual network used as the stand-in for the regional hub. This would normally be already provisioned by your platform team.')
 module vnetHub '../../../../shared/bicep/vnet.bicep' = {
   name: take('vnetHub-${deployment().name}', 64)
   scope: hubResourceGroup
@@ -124,6 +125,7 @@ module vnetHub '../../../../shared/bicep/vnet.bicep' = {
   }
 }
 
+@description('An optional Azure Bastion deployment for jump box access. This would normally be already provisioned by your platform team.')
 module bastion './modules/bastion.bicep' = if (enableBastion) {
   name: take('bastion-${deployment().name}', 64)
   scope: hubResourceGroup
@@ -137,8 +139,9 @@ module bastion './modules/bastion.bicep' = if (enableBastion) {
     bastionSubnetAddressPrefix: bastionSubnetAddressPrefix
     bastionVNetName: vnetHub.outputs.vnetName
   }
- }
+}
 
+@description('An optional Linux virtual machine deployment to act as a jump box.')
 module jumpboxLinuxVM './modules/vm/linux-vm.bicep' = if (vmJumpboxOSType == 'linux') {
   name: take('vm-linux-${deployment().name}', 64)
   scope: hubResourceGroup
@@ -158,6 +161,7 @@ module jumpboxLinuxVM './modules/vm/linux-vm.bicep' = if (vmJumpboxOSType == 'li
   }
 }
 
+@description('An optional Windows virtual machine deployment to act as a jump box.')
 module jumpboxWindowsVM './modules/vm/windows-vm.bicep' = if (vmJumpboxOSType == 'windows') {
   name: take('vm-windows-${deployment().name}', 64)
   scope: hubResourceGroup
@@ -176,13 +180,12 @@ module jumpboxWindowsVM './modules/vm/windows-vm.bicep' = if (vmJumpboxOSType ==
   }
 }
 
-
 // ------------------
 // OUTPUTS
 // ------------------
 
 @description('The resource ID of hub virtual network.')
 output hubVNetId string = vnetHub.outputs.vnetId
 
-@description('The name of the Hub resource group.')
+@description('The name of the hub resource group.')
 output resourceGroupName string = hubResourceGroup.name

scenarios/aca-internal/bicep/modules/01-hub/deploy.hub.parameters.jsonc

@@ -2,7 +2,7 @@
   "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
   "contentVersion": "1.0.0.0",
   "parameters": {
-    // The name of the workloard that is being deployed. Up to 10 characters long. This wil be used as part of the naming convention (i.e. as defined here: https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming) 
+    // The name of the workload that is being deployed. Up to 10 characters long. This wil be used as part of the naming convention (i.e. as defined here: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming) 
     "workloadName": {
       "value": "lzaaca"
     },