Various Updates - AVM Offsite - Days 1 & 2 & 3 (#73)

Co-authored-by: Alexander Sehr <[email protected]> Co-authored-by: Mate Barabas <[email protected]> Co-authored-by: PankajMeshramCSA <[email protected]> Co-authored-by: Matt White <[email protected]>
Azure · Sep 20, 2023 · 637543a · 637543a
1 parent 44be196
commit 637543a
Show file tree

Hide file tree

Showing 33 changed files with 922 additions and 526 deletions.
diff --git a/docs/content/concepts/what-why-how.md b/docs/content/concepts/what-why-how.md
@@ -19,7 +19,7 @@ Azure Verified Modules (AVM), as "One Microsoft", we want to provide and define
 
 {{< hint type=tip icon=gdoc_heart title="Mission Statement" >}}
 
-Our mission is to deliver a comprehensive Azure Verified Modules library in multiple IaC languages, serving as the trusted Microsoft source of truth. Supported by Microsoft, AVM will accelerate deployment time for Azure resources and architectural patterns, empowering every person and organization on the planet on their IaC journey.
+Our mission is to deliver a comprehensive Azure Verified Modules library in multiple IaC languages, following the principles of the well-architected framework, serving as the trusted Microsoft source of truth. Supported by Microsoft, AVM will accelerate deployment time for Azure resources and architectural patterns, empowering every person and organization on the planet on their IaC journey.
 
 {{< /hint >}}
 

diff --git a/docs/content/contributing/bicep/_index.md b/docs/content/contributing/bicep/_index.md
@@ -114,7 +114,12 @@ Each Bicep AVM module that lives within the [`Azure/bicep-registry-modules`](htt
 │   │       │
 │   │       ├───modules
 │   │       └───tests
+│   │           ├───unit (optional)
 │   │           └───e2e
+│   │               ├───defaults
+│   │               ├───waf-aligned
+│   │               └───max
+│   │
 │   └───res
 │       └───compute
 │           └───virtual-machine
@@ -125,7 +130,11 @@ Each Bicep AVM module that lives within the [`Azure/bicep-registry-modules`](htt
 │               │
 │               ├───modules
 │               └───tests
+│                   ├───unit (optional)
 │                   └───e2e
+│                       ├───defaults
+│                       ├───waf-aligned
+│                       └───max
 ├───other repo dirs...
 └───other repo files...
 ```
@@ -258,6 +267,22 @@ Before opening a Pull Request to the Bicep Public Registry, ensure your module i
 
 For example, to meet [SNFR2](/Azure-Verified-Modules/specs/shared/#id-snfr2---category-testing---e2e-testing), ensure the updated module is deployable against a testing Azure subscription and compliant with the intended configuration.
 
+### Testing Diagnostic Settings
+
+To test the numerous diagnostic settings targets (Log Analytics Workspace, Storage Account, Event Hub, etc.) the AVM core team have provided a dependencies `.bicep` file to help create all these pre-requisite targets that will be needed during test runs.
+
+{{< expand "Diagnostic Settings Dependencies - Bicep File" "expand/collapse" >}}
+
+{{< include file="/static/includes/diagnostic.dependencies.bicep" language="bicep" options="linenos=false" >}}
+
+{{< /expand >}}
+
+{{< hint type=note >}}
+
+Also note there are a number of additional scripts and utilities available [here](https://github.com/Azure/bicep-registry-modules/blob/main/avm/utilities/e2e-template-assets/diagnostic.dependencies.bicep) that may be of use to module owners/contributors.
+
+{{< /hint >}}
+
 <br>
 
 ## Publishing to the Registry

diff --git a/docs/content/contributing/process.md b/docs/content/contributing/process.md
@@ -13,26 +13,34 @@ This page will provide an overview of the contribution process for AVM modules.
 
 {{< mermaid class="text-center" >}}
 flowchart TD
-    A[Module Proposal Created] -->|GitHub Issue/Form Submitted| B{AVM Core Team Triage}
-    B -->|Module Approved for Creation| C[["Module Owner(s) Identified & assigned to GitHub issue/proposal" ]]
+    ModuleIdea[Consumer has an idea for a new AVM Module] -->CheckIndex(Check <a href='/Azure-Verified-Modules/indexes/'>AVM Module Indexes</a>)
+    CheckIndex -->IndexExistenceCheck{Does the module already <br> exist in an active/orphaned <br> state in respective index?}
+    IndexExistenceCheck -->|No|A
+    IndexExistenceCheck -->|Yes|EndExistenceCheck(Review existing/proposed AVM module)
+    EndExistenceCheck -->OrphanedCheck{Is the module <a href='/Azure-Verified-Modules/specs/shared/module-lifecycle/#orphaned-avm-modules'>orphaned</a>?}
+    OrphanedCheck -->|No|ContactOwner[Contact module owner,<br> via GitHub issues on the related <br>repo, to discuss enhancements/<br>bugs/opportunities to contribute etc.]
+    OrphanedCheck -->|Yes|OrphanOwnerYes(Locate the <a href='https://aka.ms/avm/orphanedmodules'>related issue</a> <br> and comment on:<br> - A feature/enhancement suggestion <br> - Indicating you wish to become the owner)
+    OrphanOwnerYes -->B
+    A[[<a href='https://aka.ms/avm/moduleproposal'>Create Module Proposal</a>]] -->|GitHub Issue/Form Submitted| B{<a href='/Azure-Verified-Modules/contributing/process/#avm-core-team-triage-explained'>AVM Core Team Triage</a>}
+    B -->|Module Approved for Creation| C[["Module Owner(s) Identified  & <br> assigned to GitHub issue/proposal" ]]
     B -->|Module Rejected| D(Issue closed with reasoning)
-    C -->E[[Module index CSV files updated by AVM Core Team]]
-    E -->E1[[Repo/Directory Created Following Contribution Guide]]
-    E1 -->F("Module Developed by Owner(s) & their Contributors")
-    F -->G[[Self & AVM Module Tests]]
-    G -->|Tests Fail|I(Modules/Tests Fixed To Make Them Pass)
+    C -->E[[<a href='/Azure-Verified-Modules/indexes/'>Module index</a> CSV files <br> updated by AVM Core Team]]
+    E -->E1[[Repo/Directory Created <br> Following <a href='/Azure-Verified-Modules/contributing/'>Contribution Guide</a>]]
+    E1 -->F("Module Developed by <br> Owner(s) & their Contributors")
+    F -->G[[Module & AVM Compliance Tests]]
+    G -->|Tests Fail|I(Modules/Tests Fixed <br> To Make Them Pass)
     I -->F
     G -->|Tests Pass|J[[Pre-Release v0.1.0 created]]
-    J -->K[[Publish to IaC Registry]]
+    J -->K[[Publish to Bicep/Terraform Registry]]
     K -->L(Take Feedback from v0.1.0 Consumers)
-    L -->M{Anything to be resolved before v1.0.0 release?}
-    M -->|Yes|FixPreV1("Module Feedback Incorporated by Owner(s) & their Contributors")
+    L -->M{Anything to be resolved <br> before 1.0.0 release?}
+    M -->|Yes|FixPreV1("Module Feedback Incorporated by <br> Owner(s) & their Contributors")
     FixPreV1 -->PreV1Tests[[Self & AVM Module Tests]]
-    PreV1Tests -->|Tests Fail|PreV1TestsFix(Modules/Tests Fixed To Make Them Pass)
+    PreV1Tests -->|Tests Fail|PreV1TestsFix(Modules/Tests Fixed <br> To Make Them Pass)
     PreV1TestsFix -->N
-    M -->|No|N[[Publish v1.0.0 Release]]
+    M -->|No|N[[Publish 1.0.0 Release]]
     N -->O[[Publish to IaC Registry]]
-    O -->P[[Module BAU Starts]]
+    O -->P[[<a href='/Azure-Verified-Modules/help-support/module-support/'>Module BAU Starts</a>]]
 {{< /mermaid >}}
 
 ### "AVM Core Team Triage" Explained
@@ -94,3 +102,30 @@ The AVM Core Team
 13. Bicep Only:
     - Update `Azure/bicep-registry-modules` [CODEOWNERS file](https://github.com/Azure/bicep-registry-modules/blob/main/.github/CODEOWNERS)
 14. Once module is developed and `v0.1.0` has been published to the relevant registry, move the issue into "Done" column in [AVM - Modules Triage](https://aka.ms/avm/moduletriage) GitHub Project
+15. Update the AVM Module Indexes CSV files with the correct `ModuleStatus`
+
+## Module Owner Has Issue/Is Blocked/Has A Request
+
+In the event that a module owner has an issue or is blocked due to specific AVM missing guidance, test environments, permission requirements, etc. they should follow the below steps:
+
+{{< hint type=tip >}}
+
+Common issues/blockers/asks/request are:
+
+- Subscription level features
+- Resource Provider Registration
+- Preview Services Enablement
+- Entra ID (formerly Azure Active Directory) configuration (SPN creation, etc.)
+
+{{< /hint >}}
+
+1. Create a [GitHub Issue](https://github.com/Azure/Azure-Verified-Modules/issues/new/choose)
+2. Discuss the issue/blocker with the AVM core team
+3. Agree upon action/resolution/closure
+4. Implement agreed upon action/resolution/closure
+
+{{< hint type=note >}}
+
+Please note for module specific issues, these should be logged in the module's source repository, not the AVM repository.
+
+{{< /hint >}}
diff --git a/docs/content/contributing/terraform/_index.md b/docs/content/contributing/terraform/_index.md
@@ -75,6 +75,12 @@ This repo will be created by the Module Owners and the AVM Core team collaborati
 
 <br>
 
+### Repository Labels
+
+As per [SNFR23](/Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels) the repositories created by module owners **MUST** have and use the pre-defined GitHub labels.
+
+To apply these labels to the repository review the PowerShell script `Set-AvmGitHubLabels.ps1` that is provided in [SNFR23](/Azure-Verified-Modules/specs/shared/#id-snfr23---category-contributionsupport---github-repo-labels).
+
 ## Template Repository
 
 We have created a [template repository](https://github.com/Azure/terraform-azurerm-avm-template) to help you get started.
@@ -90,9 +96,12 @@ See [this link (internal only)](https://dev.azure.com/CSUSolEng/Azure%20Verified
 Below is the directory and file structure expected for each AVM Terraform repository/module.
 See template repo [here](https://github.com/Azure/terraform-azurerm-avm-template).
 
-- `tests/` - (for unit tests and additional E2E/integration if required - e.g. tflint etc.)
+- `tests/` - (for unit tests and additional tests if required - e.g. tflint etc.)
+  - `unit/` - (optional, may use further sub-directories if required)
 - `modules/` - (for sub-modules only if used)
 - `examples/` - (all examples must deploy without successfully without requiring input - these are customer facing)
+  - `defaults` - (minimum/required parameters/variables only, heavy reliance on the default values for other parameters/variables)
+  - `<other folders for examples as required>`
 - `/...` - (Module files that live in the root of module directory)
   - `_header.md` - (required for documentation generation)
   - `_footer.md` - (required for documentation generation)
@@ -156,3 +165,51 @@ Do not include the `v` prefix in the `module_version` value.
   }
 }
 ```
+
+## Eventual Consistency
+
+When creating modules, it is important to understand that the Azure Resource Manager (ARM) API is sometimes eventually consistent.
+This means that when you create a resource, it may not be available immediately.
+A good example of this is data plane role assignments.
+When you create such a role assignment, it may take some time for the role assignment to be available.
+We can use an optional `time_sleep` resource to wait for the role assignment to be available before creating resources that depend on it.
+
+```hcl
+# In variables.tf...
+variable "wait_for_rbac_before_foo_operations" {
+  type = object({
+    create  = optional(string, "30s")
+    destroy = optional(string, "0s")
+  })
+  default     = {}
+  description = <<DESCRIPTION
+This variable controls the amount of time to wait before performing foo operations.
+It only applies when `var.role_assignments` and `var.foo` are both set.
+This is useful when you are creating role assignments on the bar resource and immediately creating foo resources in it.
+The default is 30 seconds for create and 0 seconds for destroy.
+DESCRIPTION
+}
+
+# In main.tf...
+resource "time_sleep" "wait_for_rbac_before_foo_operations" {
+  count = length(var.role_assignments) > 0 && length(var.foo) > 0 ? 1 : 0
+  depends_on = [
+    azurerm_role_assignment.this
+  ]
+  create_duration  = var.wait_for_rbac_before_foo_operations.create
+  destroy_duration = var.wait_for_rbac_before_foo_operations.destroy
+
+  # This ensures that the sleep is re-created when the role assignments change.
+  triggers = {
+    role_assignments = jsonencode(var.role_assignments)
+  }
+}
+
+resource "azurerm_foo" "this" {
+  for_each = var.foo
+  depends_on = [
+    time_sleep.wait_for_rbac_before_foo_operations
+  ]
+  # ...
+}
+```
diff --git a/docs/content/faq/_index.md b/docs/content/faq/_index.md
@@ -119,3 +119,9 @@ In short, no. Existing Landing Zone Accelerators ([Platform](https://aka.ms/alz/
 However, over time if new features or functionality are required by Landing Zone Accelerators, that team **SHOULD** consider migrating/refactoring that part of their code base to be constructed with the relevant AVM module if available.
 
 If the relevant AVM module isn't available to use to assist the Landing Zone Accelerator, then a new [AVM module proposal](https://aka.ms/avm/moduleproposal) should be made, and if desired, the Landing Zone Accelerator team may decide to own this proposed module 👍
+
+## Does/will AVM cover Microsoft 365, Azure DevOps, GitHub, etc.?
+
+Whilst the principles and practices of AVM are largely applicable to other clouds and services such as, Microsoft 365 & Azure DevOps, the AVM program (today) only covers Azure cloud resources and architectures.
+
+However, if you think this program, or a similar one, should exist to cover these other Microsoft Cloud offerings, please give a 👍 or leave a comment on this [GitHub Issue #71](https://github.com/Azure/Azure-Verified-Modules/issues/71) in the AVM repository.
diff --git a/docs/content/help-support/telemetry.md b/docs/content/help-support/telemetry.md
@@ -21,7 +21,7 @@ See [View deployment history with Azure Resource Manager](https://learn.microsof
 
 ## Technical Details
 
-As detailed in [SFR3](/Azure-Verified-Modules/specs/shared/#id-sfr3---category-telemetry---deploymentusage-telemetry) each AVM module contains a `avmTelemetry` deployment, which creates a deployment such as `46d3xbcp.res.compute-virtualmachine.v1-2-3.eum3` (fir Bicep) or `46d3xgtf.res.compute-virtualmachine.v1-2-3.eum3` (for Terraform).
+As detailed in [SFR3](/Azure-Verified-Modules/specs/shared/#id-sfr3---category-telemetry---deploymentusage-telemetry) each AVM module contains a `avmTelemetry` deployment, which creates a deployment such as `46d3xbcp.res.compute-virtualmachine.1-2-3.eum3` (fir Bicep) or `46d3xgtf.res.compute-virtualmachine.1-2-3.eum3` (for Terraform).
 
 <br>
 

diff --git a/docs/content/specs/bicep/_index.md b/docs/content/specs/bicep/_index.md
@@ -150,7 +150,16 @@ This script/tool is currently being developed by the AVM team and will be made a
 
 {{< /hint >}}
 
-Bicep modules documentation **MUST** be automatically generated via the provided script/tooling from the AVM team.
+Bicep modules documentation **MUST** be automatically generated via the provided script/tooling from the AVM team, providing the following headings:
+
+- Title
+- Description
+- Navigation
+- Resource Types
+- Usage Examples
+- Parameters
+- Outputs
+- Cross-referenced modules
 
 <br>
 
@@ -247,7 +256,7 @@ Review the [Bicep Contribution Guide's 'RBAC Role Definition Name Mapping' secti
 
 #### ID: BCPNFR8 - Category: Composition - Code Styling - lower camelCasing
 
-Module owners **MUST** use [lower camelCasing](https://wikipedia.org/wiki/Camel_case) for naming the following:
+Module owners **SHOULD** use [lower camelCasing](https://wikipedia.org/wiki/Camel_case) for naming the following:
 
 - Parameters
 - Variables
@@ -263,3 +272,45 @@ For example: `camelCasingExample` (lowercase first word (entirely), with capital
 ---
 
 <br>
+
+#### ID: BCPNFR9 - Category: Testing - Expected Test Directories
+
+Module owners **MUST** create the `defaults`, `waf-aligned` folders within their `/tests/e2e/` directory in their module source code and `SHOULD` create a `max` folder also. Each folder will be used as described for various test cases.
+
+- **MUST** - `defaults` == minimum/required parameters/variables only, heavy reliance on the default values for other parameters/variables
+- **MUST** - `waf-aligned` == showing all parameters/variables for the module to be as WAF compliant as possible
+- **SHOULD** - `<other folders for examples as required>` == all the possible parameters/variables set, some will be mutually exclusive for example. If a module can deploy varying styles of the same resource, e.g. VMs can be Linux or Windows, the names above should be used as suffixes in the directory name to denote the style, e.g. for a VM we would expect to see:
+  - `/tests/e2e/defaults.linux/main.test.bicep`
+  - `/tests/e2e/waf-aligned.linux/main.test.bicep`
+  - `/tests/e2e/defaults.windows/main.test.bicep`
+  - `/tests/e2e/waf-aligned.windows/main.test.bicep`
+
+<br>
+
+---
+
+<br>
+
+#### ID: BCPNFR10 - Category: Testing - Test Bicep File Naming
+
+Module owners **MUST** name their test `.bicep` files in the `/tests/e2e/<defaults/waf-aligned/max/etc.>` directories: `main.test.bicep` as the test framework (CI) relies upon this name.
+
+<br>
+
+---
+
+<br>
+
+#### ID: BCPNFR11 - Category: Testing - Test Tooling
+
+Module owners **MUST** use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.
+
+- [PSRule for Azure](https://azure.github.io/PSRule.Rules.Azure/)
+- [Pester](https://pester.dev/)
+  - Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Pester for your own tests.
+
+<br>
+
+---
+
+<br>
-Original file line number
+Diff line change
@@ Expand Up @@
     ## Technical Details
-    As detailed in [SFR3](/Azure-Verified-Modules/specs/shared/#id-sfr3---category-telemetry---deploymentusage-telemetry) each AVM module contains a `avmTelemetry` deployment, which creates a deployment such as `46d3xbcp.res.compute-virtualmachine.v1-2-3.eum3` (fir Bicep) or `46d3xgtf.res.compute-virtualmachine.v1-2-3.eum3` (for Terraform).
+    As detailed in [SFR3](/Azure-Verified-Modules/specs/shared/#id-sfr3---category-telemetry---deploymentusage-telemetry) each AVM module contains a `avmTelemetry` deployment, which creates a deployment such as `46d3xbcp.res.compute-virtualmachine.1-2-3.eum3` (fir Bicep) or `46d3xgtf.res.compute-virtualmachine.1-2-3.eum3` (for Terraform).
     <br>
@@ Expand Down @@