[CI Environment] Enabled CI environment to handle DeploymentTest (bicep) files for new self-contained dependency approach

docs/wiki/The library - Module design.md

@@ -66,6 +66,7 @@ A **CARML module** consists of
 A module usually represents a single resource or a set of closely related resources. For example, a storage account and the associated lock or virtual machine and network interfaces. Modules are located in the `modules` folder.
 
 Also, each module should be implemented with all capabilities it and its children support. This includes
+
 - `Locks`
 - `Role assignments (RBAC)`
 - `Diagnostic Settings`
@@ -104,7 +105,7 @@ Use the following naming standard for module files and folders:
 - Module folders are in camelCase and their name reflects the main resource type of the Bicep module they are hosting (e.g., `storageAccounts`, `virtualMachines`).
 - Extension resource modules are placed in the `.bicep` subfolder and named `nested_<crossReferencedResourceType>.bicep`
 
-  ``` txt
+  ```txt
   Microsoft.<Provider>
   └─ <service>
       ├─ .bicep
@@ -115,17 +116,18 @@ Use the following naming standard for module files and folders:
       └─ readme.md
   ```
 
-  >**Example**: `nested_roleAssignments.bicep` in the `Microsoft.Web\sites\.bicep` folder contains the `site` resource RBAC implementation.
-  >``` txt
-  >Microsoft.Web
-  >└─ sites
+  > **Example**: `nested_roleAssignments.bicep` in the `Microsoft.Web\sites\.bicep` folder contains the `site` resource RBAC implementation.
+  >
+  > ```txt
+  > Microsoft.Web
+  > └─ sites
   >    ├─ .bicep
   >    |  └─ nested_roleAssignments.bicep
   >    ├─ .test
   >    |  └─ ...
   >    ├─ deploy.bicep
   >    └─ readme.md
-  >```
+  > ```
 
 ## Patterns
 
@@ -158,6 +160,7 @@ resource <mainResource>_lock 'Microsoft.Authorization/locks@2017-04-01' = if (!e
 ```
 
 > **Note:** How locks are passed to other resource templates depends on the type of module relationship:
+>
 > - Child and extension resources
 >   - Locks are not automatically passed down, as they are inherited by default in Azure
 >   - The reference of the child/extension template should look similar to: `lock: contains(<childExtensionObject>, 'lock') ? <childExtensionObject>.lock : ''`
@@ -181,6 +184,7 @@ The RBAC deployment has 2 elements. A module that contains the implementation, a
 <summary>Details</summary>
 
 #### 1st Element in main resource
+
 ```bicep
 @description('Optional. Array of role assignment objects that contain the \'roleDefinitionIdOrName\' and \'principalId\' to define RBAC role assignments on this resource. In the roleDefinitionIdOrName attribute, you can provide either the display name of the role definition, or its fully qualified ID in the following format: \'/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11\'.')
 param roleAssignments array = []
@@ -200,7 +204,8 @@ module <mainResource>_roleAssignments '.bicep/nested_roleAssignments.bicep' = [f
 Here, you specify the platform roles available for the main resource.
 
 The `builtInRoleNames` variable contains the list of applicable roles for the specific resource which the `nested_roleAssignments.bicep` template applies.
->**Note**: You use the helper script [Get-FormattedRBACRoles.ps1](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) to extract a formatted list of RBAC roles used in the CARML modules based on the RBAC lists in Azure.
+
+> **Note**: You use the helper script [Get-FormattedRBACRoles.ps1](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) to extract a formatted list of RBAC roles used in the CARML modules based on the RBAC lists in Azure.
 
 The element requires you to provide both the `principalIds` & `roleDefinitionOrIdName` to assign to the principal IDs. Also, the `resourceId` is target resource's resource ID that allows us to reference it as an `existing` resource. Note, the implementation of the `split` in the resource reference becomes longer the deeper you go in the child resource hierarchy.
 
@@ -318,11 +323,13 @@ resource <mainResource>_diagnosticSettings 'Microsoft.Insights/diagnosticsetting
   scope: <mainResource>
 }
 ```
+
 </details>
 
 <p>
 
 ### Private Endpoints
+
 The Private Endpoint deployment has 2 elements. A module that contains the implementation, and a module reference in the parent resource. The first one loops through the endpoints we want to create, the second one processes them.
 
 <details>
@@ -390,9 +397,12 @@ Within a bicep file, use the following conventions:
   - `resource storageAccount 'Microsoft.Storage/storageAccounts@2019-06-01'`
   - `resource virtualMachine 'Microsoft.Compute/virtualMachines@2020-06-01'`
 - Parent reference
+
   - If working on a child resource, refrain from string concatenation and instead, use the parent reference via the `existing` keyword.
   - The way this is implemented differs slightly the lower you go in the hierarchy. Note the following examples:
+
     - 1st level child resource (example _storageAccount/blobService_)
+
       ```bicep
       resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' existing = {
         name: storageAccountName
@@ -404,7 +414,9 @@ Within a bicep file, use the following conventions:
         properties: {...}
       }
       ```
+
     - 2nd level child resource (example _storageAccount/blobService/container_)
+
       ```bicep
       resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' existing = {
         name: storageAccountName
@@ -420,7 +432,9 @@ Within a bicep file, use the following conventions:
         properties: {...}
       }
       ```
+
     - 3rd level child resource (example _storageAccount/blobService/container/immutabilityPolicies_)
+
       ```bicep
       resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' existing = {
         name: storageAccountName
@@ -440,11 +454,12 @@ Within a bicep file, use the following conventions:
         properties: {...}
       }
       ```
+
 ## Modules
 
-  - Module symbolic names are in camel_Snake_Case, following the schema `<mainResourceType>_<referencedResourceType>` e.g., `storageAccount_fileServices`, `virtualMachine_nic`, `resourceGroup_roleAssignments`.
-  - Modules enable you to reuse code from a Bicep file in other Bicep files. As such, they're normally leveraged for deploying child resources (e.g., file services in a storage account), cross referenced resources (e.g., network interface in a virtual machine) or extension resources (e.g., role assignment in a resource group).
-  - When a module requires to deploy a resource whose resource type is outside of the main module's provider namespace, the module of this additional resource is referenced locally. For example, when extending the Key Vault module with Private Endpoints, instead of including in the Key Vault module an ad hoc implementation of a Private Endpoint, the Key Vault directly references the Private Endpoint module (i.e., `module privateEndpoint 'https://github.com/Azure/ResourceModules/blob/main/Microsoft.Network/privateEndpoints/deploy.bicep'`). Major benefits of this implementation are less code duplication, more consistency throughout the module library and allowing the consumer to leverage the full interface provided by the referenced module.
+- Module symbolic names are in camel*Snake_Case, following the schema `<mainResourceType>*<referencedResourceType>`e.g.,`storageAccount_fileServices`, `virtualMachine_nic`, `resourceGroup_roleAssignments`.
+- Modules enable you to reuse code from a Bicep file in other Bicep files. As such, they're normally leveraged for deploying child resources (e.g., file services in a storage account), cross referenced resources (e.g., network interface in a virtual machine) or extension resources (e.g., role assignment in a resource group).
+- When a module requires to deploy a resource whose resource type is outside of the main module's provider namespace, the module of this additional resource is referenced locally. For example, when extending the Key Vault module with Private Endpoints, instead of including in the Key Vault module an ad hoc implementation of a Private Endpoint, the Key Vault directly references the Private Endpoint module (i.e., `module privateEndpoint 'https://github.com/Azure/ResourceModules/blob/main/Microsoft.Network/privateEndpoints/deploy.bicep'`). Major benefits of this implementation are less code duplication, more consistency throughout the module library and allowing the consumer to leverage the full interface provided by the referenced module.
   > **Note**: Cross-referencing modules from the local repository creates a dependency for the modules applying this technique on the referenced modules being part of the local repository. Reusing the example from above, the Key Vault module has a dependency on the referenced Private Endpoint module, meaning that the repository from which the Key Vault module is deployed also requires the Private Endpoint module to be present. For this reason, we provide a utility to check for any local module references in a given path. This can be useful to determine which module folders you'd need if you don't want to keep the entire library. For further information on how to use the tool, please refer to the tool-specific [documentation](./Getting%20started%20-%20Get%20module%20cross-references).
 
 ### Deployment names
@@ -469,7 +484,9 @@ While exceptions might be needed, the following guidance should be followed as m
     ...
   }]
   ```
+
   > **Example**: for the `roleAssignment` deployment in the Key Vault `secrets` template
+  >
   > ```
   >   module secret_roleAssignments '.bicep/nested_roleAssignments.bicep' = [for (roleAssignment, index) in roleAssignments: {
   >     name: '${deployment().name}-Rbac-${index}'
@@ -480,7 +497,9 @@ While exceptions might be needed, the following guidance should be followed as m
   ```
   '${uniqueString(deployment().name, location)}-<topLevelResourceType>-<referencedResourceType>'
   ```
+
   > **Example**: for the `tableServices` deployment inside the `storageAccount` template
+  >
   > ```
   > name: '${uniqueString(deployment().name, location)}-Storage-TableServices'
   > ```
@@ -490,7 +509,9 @@ While exceptions might be needed, the following guidance should be followed as m
   ```
   '${deployment().name}-<referencedResourceType>[-${index}]'
   ```
+
   > **Example**: for the `tables` deployment in the `tableServices` template
+  >
   > ```
   > name: '${deployment().name}-Table-${index}'
   > ```
@@ -512,6 +533,7 @@ While exceptions might be needed, the following guidance should be followed as m
 
 Each module must come with a ReadMe Markdown file that outlines what the module contains and 'how' it can be used.
 Its primary components are in order:
+
 - A title with a reference to the primary resource in Start Case followed by the primary resource namespace e.g., <code>Key Vaults `[Microsoft.KeyVault/vaults]`</code>.
 - A short description
 - A **Resource types** section with a table that outlines all resources that can be deployed as part of the module.
@@ -521,23 +543,27 @@ Its primary components are in order:
 - A **Template references** section listing relevant resources [Azure resource reference](https://docs.microsoft.com/en-us/azure/templates).
 
 Note the following recommendations:
+
 - Refer to [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme) for creating from scratch or updating the module ReadMe Markdown file.
 - It is not recommended to describe how to use child resources in the parent readme file (for example, 'How to define a \[container] entry for the \[storage account]'). Instead, it is recommended to reference the child resource's ReadMe (for example, 'container/readme.md').
 
 # Module test files
 
 Module test files in CARML are implemented in
+
 - a classic way leveraging the common `deploymentParameters.json` schema for ARM deployments or
 - using comprehensive `.bicep` test files that not only test the module's template in a certain scenario, but also deploy any required dependency for it. All classic test files will be migrated to this module following the issue [1583](https://github.com/Azure/ResourceModules/issues/1583).
 
-As parameters are usually specific to their corresponding template, we only have a few general recommendations:
+In either case, we follow the following, general guidelines:
+
 - A module should have as many module test files as it needs to evaluate all parts of the module's functionality.
 - Sensitive data should not be stored inside the module test file but rather be injected by the use of tokens, as described in the [Token replacement](./The%20CI%20environment%20-%20Token%20replacement) section, or via a [Key Vault reference](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/key-vault-parameter?tabs=azure-cli#reference-secrets-with-static-id).
 
 - JSON Parameter File specific
   - Parameter file names should ideally relate to the content they deploy. For example, a parameter file `min.parameters.json` should be chosen for a parameter file that contains only the minimum set of parameters to deploy the module.
   - Likewise, the `name` parameter we have in most modules should give some indication of the file it was deployed with. For example, a `min.parameters.json` parameter file for the virtual network module may have a `name` property with the value `sxx-az-vnet-min-001` where `min` relates to the prefix of the parameter file itself.
 - Bicep File specific
+
   - Each scenario should be setup in its own sub-folder (e.g. `.test/linux`)
   - Each folder should contain at least a file `deploy.test.bicep` and optionally an additional `dependencies.bicep` file. The `deploy.test.bicep` file should deploy any immediate dependencies (e.g. a resource group, if required) and invoke the module's main template while providing all parameters for a given test scenario. The `dependencies.bicep` should optionally be used if any additional dependencies must be deployed into a nested scope (e.g. into a deployed resource group).
   - Parameters
@@ -627,13 +653,15 @@ As parameters are usually specific to their corresponding template, we only have
       }
     }
     ```
+
     </details>
 
 # Telemetry
 
-Each module in CARML contains a `defaultTelemetry` deployment  `'pid-<GUID>-${uniqueString(deployment().name)}'`, resulting in deployments such as `'pid-<GUID>-nx2c3rnlt2wru'`.
+Each module in CARML contains a `defaultTelemetry` deployment `'pid-<GUID>-${uniqueString(deployment().name)}'`, resulting in deployments such as `'pid-<GUID>-nx2c3rnlt2wru'`.
 
 > **Note:** Though implemented at each level in a module hierarchy (e.g., storage account & blobServices), the deployment will only happen for the top-level module in a deployment, but not for its children. To illustrate this better, see the following examples:
+>
 > - Deployment of the KeyVault module and 2 Secrets: Results in 1 `PID` deployment for the KeyVault (and none for the secrets)
 > - Deployment of the Secret module: Results in 1 `PID` deployment for the Secret
 
@@ -642,6 +670,7 @@ This resource enables the CARML product team to query the number of deployments
 When using CARML's CI environment you can enable/disable this deployment by switching the `enableDefaultTelemetry` setting in the `settings.yml` file in the repository's root. This value is automatically injected into each individual deployment that is performed as part of the environment's pipeline.
 
 When consuming the modules outside of CARML's pipelines you can either
+
 - Set the parameter to a default value of `'false'`
 - Set the parameter to false when deploying a module