From 78d5c6851ef77937a8800a095dc1530743cca180 Mon Sep 17 00:00:00 2001 From: AlexanderSehr Date: Fri, 13 Jan 2023 15:34:10 +0100 Subject: [PATCH 1/4] Updated docs recommendations & structure --- docs/wiki/The library - Module design.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/wiki/The library - Module design.md b/docs/wiki/The library - Module design.md index 4257375ef4..2a05a4a2a1 100644 --- a/docs/wiki/The library - Module design.md +++ b/docs/wiki/The library - Module design.md @@ -562,13 +562,22 @@ Module test files follow these 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). -In addition, they follow these file-type-specific guidelines: +Test folder guidelines: - Each scenario should be setup in its own sub-folder (e.g. `.test/linux`) - Sub-folder names should ideally relate to the content they deploy. For example, a sub-folder `min` should be chosen for a scenario in which only the minimum set of parameters are used to deploy the module. -- 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). +- Each folder should contain at least a file `deploy.test.bicep` and optionally an additional `dependencies.bicep` file. + +Test file (`deploy.test.bicep`) guidelines: + +- 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. - Parameters - - Each file should define a parameter `serviceShort`. This parameter should be unique to this file (i.e, no two test files should share the same) as it is injected into all resource deployments, making them unique too and account for corresponding requirements. As a reference you can create a identifier by combining a substring of the resource type and test scenario (e.g., in case of a Linux Virtual Machine Deployment: `vmlin`) + - Each file should define a parameter `serviceShort`. This parameter should be unique to this file (i.e, no two test files should share the same) as it is injected into all resource deployments, making them unique too and account for corresponding requirements. + - As a reference you can create a identifier by combining a substring of the resource type and test scenario (e.g., in case of a Linux Virtual Machine Deployment: `vmlin`). + - For the substring we recommend to take the first character any and upper-case character from the resource type identifier amd combine them to one string. Following you can find a few examples for reference: + - `Microsoft.DBforPostgreSQL/flexibleServers` with a test folder `common` could be: `dfpsfscom` + - `Microsoft.Storage/storageAccounts` with a test folder `min` could be: `ssamin` + > **Note:** If the combination of the `servicesShort` with the rest of a resource name becomes too long, it may be necessary to bend the above recommendations and shorten the name. This can especially happen when deploying resources such as Virtual Machines or Storage Accounts that only allow comparatively short names. - If the module deploys a resource group level resource, the template should further have a `resourceGroupName` parameter and subsequent resource deployment. As a reference for the default name you can use `ms..-${serviceShort}-test-rg`. - Each file should also provide a `location` parameter that may default to the deployments default location - It is recommended to define all major resource names in the `deploy.test.bicep` file as it makes later maintenance easier. To implement this, make sure to pass all resource names to any referenced module. @@ -659,6 +668,10 @@ In addition, they follow these file-type-specific guidelines: +Dependency file (`dependencies.bicep`) guidelines: + +- 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). + # Telemetry ## Overview From 14582955cd3922446908ab80270de96f39211562 Mon Sep 17 00:00:00 2001 From: AlexanderSehr Date: Fri, 13 Jan 2023 15:36:38 +0100 Subject: [PATCH 2/4] Update to latest --- docs/wiki/The library - Module design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/The library - Module design.md b/docs/wiki/The library - Module design.md index 2a05a4a2a1..bb4f36d881 100644 --- a/docs/wiki/The library - Module design.md +++ b/docs/wiki/The library - Module design.md @@ -670,7 +670,7 @@ Test file (`deploy.test.bicep`) guidelines: Dependency file (`dependencies.bicep`) guidelines: -- 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). +- 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). # Telemetry From b77d3603d32f81d0534e980d8e2797d00bd2e149 Mon Sep 17 00:00:00 2001 From: AlexanderSehr Date: Fri, 13 Jan 2023 15:42:19 +0100 Subject: [PATCH 3/4] Added recommendations for dependencies --- docs/wiki/The library - Module design.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/wiki/The library - Module design.md b/docs/wiki/The library - Module design.md index bb4f36d881..d6b294dec5 100644 --- a/docs/wiki/The library - Module design.md +++ b/docs/wiki/The library - Module design.md @@ -671,6 +671,8 @@ Test file (`deploy.test.bicep`) guidelines: Dependency file (`dependencies.bicep`) guidelines: - 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). +- Note that you can reuse many of the assets implemented in other modules. For example, there are many recurring implementations for Managed Identities, Key Vaults, Virtual Network deployments, etc. + - A special case to point out is the implementation of Key Vaults that require purge protection (for example, for Customer Managed Keys). As this implies that we cannot fully clean up a test deployment, it is recommended to generate a new name for this resource upon each pipeline run using the output of the `utcNow()` function at the time. You can find a good example of how this can be implemented in the `encr` test of the Batch-BatchAccounts module. # Telemetry From ca3fc2d7f3b374843b49cfc02e556c903f5604f6 Mon Sep 17 00:00:00 2001 From: AlexanderSehr Date: Fri, 13 Jan 2023 15:43:46 +0100 Subject: [PATCH 4/4] Update to latest --- docs/wiki/The library - Module design.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/wiki/The library - Module design.md b/docs/wiki/The library - Module design.md index d6b294dec5..b7556d980b 100644 --- a/docs/wiki/The library - Module design.md +++ b/docs/wiki/The library - Module design.md @@ -581,7 +581,7 @@ Test file (`deploy.test.bicep`) guidelines: - If the module deploys a resource group level resource, the template should further have a `resourceGroupName` parameter and subsequent resource deployment. As a reference for the default name you can use `ms..-${serviceShort}-test-rg`. - Each file should also provide a `location` parameter that may default to the deployments default location - It is recommended to define all major resource names in the `deploy.test.bicep` file as it makes later maintenance easier. To implement this, make sure to pass all resource names to any referenced module. -- Further, for any test file, the usage of variables should be reduced to the absolute minimum. In other words: You should only use variables if you must use them in more than one place. The idea is to keep the test files as simple as possible +- Further, for any test file (including the `dependencies.bicep` file), the usage of variables should be reduced to the absolute minimum. In other words: You should only use variables if you must use them in more than one place. The idea is to keep the test files as simple as possible - References to dependencies should be implemented using resource references in combination with outputs. In other words: You should not hardcode any references into the module template's deployment. Instead use references such as `resourceGroupResources.outputs.managedIdentityPrincipalId` - If any diagnostic resources (e.g., a Log Analytics workspace) are required for a test scenario, you can reference the centralized `modules/.shared/dependencyConstructs/diagnostic.dependencies.bicep` template. It will also provide you with all outputs you'd need. @@ -672,7 +672,7 @@ Dependency file (`dependencies.bicep`) guidelines: - 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). - Note that you can reuse many of the assets implemented in other modules. For example, there are many recurring implementations for Managed Identities, Key Vaults, Virtual Network deployments, etc. - - A special case to point out is the implementation of Key Vaults that require purge protection (for example, for Customer Managed Keys). As this implies that we cannot fully clean up a test deployment, it is recommended to generate a new name for this resource upon each pipeline run using the output of the `utcNow()` function at the time. You can find a good example of how this can be implemented in the `encr` test of the Batch-BatchAccounts module. + - A special case to point out is the implementation of Key Vaults that require purge protection (for example, for Customer Managed Keys). As this implies that we cannot fully clean up a test deployment, it is recommended to generate a new name for this resource upon each pipeline run using the output of the `utcNow()` function at the time. You can find a good example of how this can be implemented in the `encr` test of the [Batch-BatchAccounts](https://github.com/Azure/ResourceModules/tree/main/modules/Microsoft.Batch/batchAccounts/.test/encr) module. # Telemetry