Update docs

templates/complete_multi_region/README.md

@@ -1,8 +1,28 @@
 # Azure Landing Zones Accelerator Starter Module for Terraform - Complete Multi-Region
 
-## Contributing
+This module is part of the Azure Landing Zones Accelerator solution. It is a complete multi-region implementation of the Azure Landing Zones Platform Landing Zone for Terraform.
 
-### Run the local examples
+It deploys a hub and spoke virtual network or Virtual WAN architecture across multiple regions.
+
+The module deploys the following resources:
+
+- Management group hierarchy
+- Azure Policy definitions and assignments
+- Role definitions
+- Management resources, including Log Analytics workspace and Automation account
+- Hub and spoke virtual network or Virtual WAN architecture across multiple regions
+- DDOS protection plan
+- Private DNS zones
+
+## Usage
+
+The module is intended to be used with the [Azure Landing Zones Accelerator](https://aka.ms/alz/accelerator/docs). Head over there to get started.
+
+>NOTE: The module can be used independently if needed. Example tfvars files can be found in the `examples` directory for that use case.
+
+### Running Directly
+
+#### Run the local examples
 
 Create a `terraform.tfvars` file in the root of the module directory with the following content, replacing the placeholders with the actual values:
 
@@ -13,14 +33,14 @@ subscription_id_identity     = "00000000-0000-0000-0000-000000000000"
 subscription_id_management   = "00000000-0000-0000-0000-000000000000"
 ```
 
-#### Hub and Spoke Virtual Networks Multi Region
+##### Hub and Spoke Virtual Networks Multi Region
 
 ```powershell
 terraform init
 terraform apply -var-file ./examples/config-hub-and-spoke-virtual-networks-multi-region.tfvars
 ```
 
-#### Virtual WAN Multi Region
+##### Virtual WAN Multi Region
 
 ```powershell
 terraform init

templates/complete_multi_region/modules/hub-and-spoke-vnet/variables.tf

@@ -1,5 +1,14 @@
 variable "hub_and_spoke_networks_settings" {
-  type = any
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The shared settings for the hub and spoke networks. This is where global resources are defined.
+
+The following attributes are supported:
+
+  - ddos_protection_plan: (Optional) The DDoS protection plan settings. Detailed information about the DDoS protection plan can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-ddosprotectionplan
+
+DESCRIPTION
 }
 
 variable "hub_virtual_networks" {
@@ -15,17 +24,31 @@ variable "hub_virtual_networks" {
     }))
   }))
   default     = {}
-  description = "A map of hub networks to create. Detailed information about the hub network can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-hubnetworking"
+  description = <<DESCRIPTION
+A map of hub networks to create. 
+
+The following attributes are supported:
+
+  - hub_virtual_network: The hub virtual network settings. Detailed information about the hub virtual network can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-hubnetworking
+  - virtual_network_gateways: (Optional) The virtual network gateway settings. Detailed information about the virtual network gateway can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-vnetgateway
+  - private_dns_zones: (Optional) The private DNS zone settings. Detailed information about the private DNS zone can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-network-private-link-private-dns-zones
+
+DESCRIPTION
 }
 
 variable "enable_telemetry" {
-  default     = true
   type        = bool
-  description = "Flag to enable/disable telemetry"
+  default     = true
+  description = <<DESCRIPTION
+This variable controls whether or not telemetry is enabled for the module.
+For more information see <https://aka.ms/avm/telemetryinfo>.
+If it is set to false, then no telemetry will be collected.
+DESCRIPTION
+  nullable    = false
 }
 
 variable "tags" {
-  default     = {}
   type        = map(string)
-  description = "A map of tags to add to the private DNS zones"
+  default     = null
+  description = "(Optional) Tags of the resource."
 }

templates/complete_multi_region/modules/management-avm/variables.tf

@@ -1,8 +1,18 @@
 variable "settings" {
-  type = any
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The settings for the management groups and management resources. Details of the settings will be added later.
+DESCRIPTION
 }
 
 variable "enable_telemetry" {
-  type    = bool
-  default = true
+  type        = bool
+  default     = true
+  description = <<DESCRIPTION
+This variable controls whether or not telemetry is enabled for the module.
+For more information see <https://aka.ms/avm/telemetryinfo>.
+If it is set to false, then no telemetry will be collected.
+DESCRIPTION
+  nullable    = false
 }

templates/complete_multi_region/modules/management-es/variables.tf

@@ -1,8 +1,18 @@
 variable "settings" {
-  type = any
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The settings for the management groups and management resources. Details of the settings can be found in the module documentation at https://registry.terraform.io/modules/Azure/caf-enterprise-scale
+DESCRIPTION
 }
 
 variable "enable_telemetry" {
-  type    = bool
-  default = true
+  type        = bool
+  default     = true
+  description = <<DESCRIPTION
+This variable controls whether or not telemetry is enabled for the module.
+For more information see <https://aka.ms/avm/telemetryinfo>.
+If it is set to false, then no telemetry will be collected.
+DESCRIPTION
+  nullable    = false
 }

templates/complete_multi_region/modules/virtual-wan/variables.tf

@@ -1,5 +1,16 @@
 variable "virtual_wan_settings" {
-  type = any
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The shared settings for the Virtual WAN. This is where global resources are defined.
+
+The following attributes are supported:
+
+  - ddos_protection_plan: (Optional) The DDoS protection plan settings. Detailed information about the DDoS protection plan can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-ddosprotectionplan
+  
+The Virtual WAN module attributes are also supported. Detailed information about the Virtual WAN module variables can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualwan
+
+DESCRIPTION
 }
 
 variable "virtual_hubs" {
@@ -29,17 +40,45 @@ variable "virtual_hubs" {
   }))
 
   default     = {}
-  description = "A map of virtual hubs to create. Detailed information about the virtual hub can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualhub"
+  description = <<DESCRIPTION
+A map of virtual hubs to create.
+
+The following attributes are supported:
+
+  - hub: The virtual hub settings. Detailed information about the virtual hub can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualhub
+  - firewall: (Optional) The firewall settings. Detailed information about the firewall can be found in the Virtual WAN module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualhub
+  - firewall_policy: (Optional) The firewall policy settings. Detailed information about the firewall policy can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-firewall-policy
+  - private_dns_zones: (Optional) The private DNS zone settings. Detailed information about the private DNS zone can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-network-private-link-private-dns-zones
+    - resource_group_name: The resource group name where the private DNS zone will be created
+    - is_primary: (Optional) Flag to indicate if the private DNS zone is primary. If set to true, only the regional DNS zones will be created
+    - networking: The networking settings for the private DNS zone. This is required for Virtual WAN since private DNS zones cannot be linked to a virtual hub.
+      - virtual_network: The virtual network settings for the private DNS zone
+        - name: The name of the virtual network
+        - address_space: The address space of the virtual network
+        - resource_group_name: The resource group name where the virtual network is located
+        - private_dns_resolver_subnet: The private DNS resolver subnet settings
+          - name: The name of the subnet
+          - address_prefix: The address prefix of the subnet
+      - private_dns_resolver: The private DNS resolver settings for the private DNS zone. This is required for Virtual WAN since private DNS zones cannot be linked to a virtual hub.
+        - name: The name of the private DNS resolver
+        - resource_group_name: The resource group name where the private DNS resolver is located
+
+DESCRIPTION
 }
 
 variable "enable_telemetry" {
   type        = bool
   default     = true
-  description = "Flag to enable/disable telemetry"
+  description = <<DESCRIPTION
+This variable controls whether or not telemetry is enabled for the module.
+For more information see <https://aka.ms/avm/telemetryinfo>.
+If it is set to false, then no telemetry will be collected.
+DESCRIPTION
+  nullable    = false
 }
 
 variable "tags" {
-  default     = {}
   type        = map(string)
-  description = "A map of tags to add to the private DNS zones"
+  default     = null
+  description = "(Optional) Tags of the resource."
 }

templates/complete_multi_region/variables-connectivity.tf

@@ -1,6 +1,6 @@
 variable "connectivity_type" {
   type        = string
-  description = "The type of connectivity to use for the private DNS zones"
+  description = "The type of network connectivity technology to use for the private DNS zones"
   default     = "hub_and_spoke_vnet"
   validation {
     condition     = contains(values(local.const.connectivity), var.connectivity_type)
@@ -13,5 +13,13 @@ variable "connectivity_resource_groups" {
     name     = string
     location = string
   }))
-  description = "A map of resource groups to create"
+  description = <<DESCRIPTION
+A map of resource groups to create. These must be created before the connectivity module is applied.
+
+The following attributes are supported:
+
+  - name: The name of the resource group
+  - location: The location of the resource group
+
+DESCRIPTION
 }

templates/complete_multi_region/variables-hub-and-spoke-vnet.tf

@@ -1,6 +1,14 @@
 variable "hub_and_spoke_vnet_settings" {
-  type    = any
-  default = {}
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The shared settings for the hub and spoke networks. This is where global resources are defined.
+
+The following attributes are supported:
+
+  - ddos_protection_plan: (Optional) The DDoS protection plan settings. Detailed information about the DDoS protection plan can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-ddosprotectionplan
+
+DESCRIPTION
 }
 
 variable "hub_and_spoke_vnet_virtual_networks" {
@@ -12,6 +20,15 @@ variable "hub_and_spoke_vnet_virtual_networks" {
     }))
     private_dns_zones = optional(any)
   }))
-  description = "A map of hub networks to create. Detailed information about the hub network can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-hubnetworking"
   default     = {}
+  description = <<DESCRIPTION
+A map of hub networks to create. 
+
+The following attributes are supported:
+
+  - hub_virtual_network: The hub virtual network settings. Detailed information about the hub virtual network can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-hubnetworking
+  - virtual_network_gateways: (Optional) The virtual network gateway settings. Detailed information about the virtual network gateway can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-vnetgateway
+  - private_dns_zones: (Optional) The private DNS zone settings. Detailed information about the private DNS zone can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-network-private-link-private-dns-zones
+
+DESCRIPTION
 }

templates/complete_multi_region/variables-management.tf

@@ -5,11 +5,17 @@ variable "management_use_avm" {
 }
 
 variable "management_settings_avm" {
-  type    = any
-  default = {}
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The settings for the management groups and management resources. Details of the settings will be added later.
+DESCRIPTION
 }
 
 variable "management_settings_es" {
-  type    = any
-  default = {}
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The settings for the management groups and management resources. Details of the settings can be found in the module documentation at https://registry.terraform.io/modules/Azure/caf-enterprise-scale
+DESCRIPTION
 }

templates/complete_multi_region/variables-virtual-wan.tf

@@ -1,6 +1,16 @@
 variable "virtual_wan_settings" {
-  type    = any
-  default = {}
+  type        = any
+  default     = {}
+  description = <<DESCRIPTION
+The shared settings for the Virtual WAN. This is where global resources are defined.
+
+The following attributes are supported:
+
+  - ddos_protection_plan: (Optional) The DDoS protection plan settings. Detailed information about the DDoS protection plan can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-ddosprotectionplan
+  
+The Virtual WAN module attributes are also supported. Detailed information about the Virtual WAN module variables can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualwan
+
+DESCRIPTION
 }
 
 variable "virtual_wan_virtual_hubs" {
@@ -10,5 +20,28 @@ variable "virtual_wan_virtual_hubs" {
     private_dns_zones = optional(any)
   }))
   default     = {}
-  description = "A map of virtual hubs to create. Detailed information about the virtual hub can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualhub"
+  description = <<DESCRIPTION
+A map of virtual hubs to create.
+
+The following attributes are supported:
+
+  - hub: The virtual hub settings. Detailed information about the virtual hub can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualhub
+  - firewall: (Optional) The firewall settings. Detailed information about the firewall can be found in the Virtual WAN module's README: https://registry.terraform.io/modules/Azure/avm-ptn-virtualhub
+  - firewall_policy: (Optional) The firewall policy settings. Detailed information about the firewall policy can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-firewall-policy
+  - private_dns_zones: (Optional) The private DNS zone settings. Detailed information about the private DNS zone can be found in the module's README: https://registry.terraform.io/modules/Azure/avm-ptn-network-private-link-private-dns-zones
+    - resource_group_name: The resource group name where the private DNS zone will be created
+    - is_primary: (Optional) Flag to indicate if the private DNS zone is primary. If set to true, only the regional DNS zones will be created
+    - networking: The networking settings for the private DNS zone. This is required for Virtual WAN since private DNS zones cannot be linked to a virtual hub.
+      - virtual_network: The virtual network settings for the private DNS zone
+        - name: The name of the virtual network
+        - address_space: The address space of the virtual network
+        - resource_group_name: The resource group name where the virtual network is located
+        - private_dns_resolver_subnet: The private DNS resolver subnet settings
+          - name: The name of the subnet
+          - address_prefix: The address prefix of the subnet
+      - private_dns_resolver: The private DNS resolver settings for the private DNS zone. This is required for Virtual WAN since private DNS zones cannot be linked to a virtual hub.
+        - name: The name of the private DNS resolver
+        - resource_group_name: The resource group name where the private DNS resolver is located
+
+DESCRIPTION
 }

templates/complete_multi_region/yaml.tf

@@ -1,3 +1,6 @@
+# NOTE: This file is for development puposese only. It is used in the generation of documentation and examples. 
+# When deployed with the ALZ Accelerator PowerShell module, this file is removed.
+
 locals {
   yaml_file_header = <<YAML
 # This file contains templated variables to avoid repeating the same hard-coded values.