Rule docs quality updates (Azure#2912)

docs/en/rules/Azure.Redis.AvailabilityZone.md

@@ -1,7 +1,7 @@
 ---
 severity: Important
 pillar: Reliability
-category: Design
+category: RE:05 Regions and availability zones
 resource: Azure Cache for Redis
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Redis.AvailabilityZone/
 ---
@@ -126,9 +126,11 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cache/redis zones -->
+
 ## LINKS
 
-- [Use zone-aware services](https://learn.microsoft.com/azure/architecture/framework/resiliency/design-best-practices#use-zone-aware-services)
+- [RE:05 Regions and availability zones](https://learn.microsoft.com/azure/well-architected/reliability/regions-availability-zones)
 - [Enable zone redundancy for Azure Cache for Redis](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-how-to-zone-redundancy)
 - [High availability for Azure Cache for Redis](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-high-availability)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.cache/redis)

docs/en/rules/Azure.Redis.MaxMemoryReserved.md

@@ -2,7 +2,7 @@
 reviewed: 2023-07-08
 severity: Important
 pillar: Performance Efficiency
-category: Application capacity
+category: PE:05 Scaling and partitioning
 resource: Azure Cache for Redis
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Redis.MaxMemoryReserved/
 ---
@@ -101,9 +101,11 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cache/redis redisConfiguration -->
+
 ## LINKS
 
-- [Choose the right resources](https://learn.microsoft.com/azure/well-architected/scalability/design-capacity#choose-the-right-resources)
+- [PE:05 Scaling and partitioning](https://learn.microsoft.com/azure/well-architected/performance-efficiency/scale-partition)
 - [Choosing the right tier](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-overview#choosing-the-right-tier)
 - [Scaling and memory](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-best-practices-scale#scaling-and-memory)
 - [Memory management](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-best-practices-memory-management)

docs/en/rules/Azure.Redis.MinSKU.md

@@ -1,7 +1,7 @@
 ---
 severity: Important
 pillar: Performance Efficiency
-category: Application capacity
+category: PE:03 Selecting services
 resource: Azure Cache for Redis
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Redis.MinSKU/
 ---
@@ -98,9 +98,11 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cache/redis skuName -->
+
 ## LINKS
 
-- [Choose the right resources](https://learn.microsoft.com/azure/well-architected/scalability/design-capacity#choose-the-right-resources)
+- [PE:03 Selecting services](https://learn.microsoft.com/azure/well-architected/performance-efficiency/select-services)
 - [Choosing the right tier](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-overview#choosing-the-right-tier)
 - [Scaling and memory](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-best-practices-scale#scaling-and-memory)
 - [Memory management](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-best-practices-memory-management)

docs/en/rules/Azure.Redis.MinTLS.md

@@ -96,6 +96,8 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cache/redis minimumTlsVersion -->
+
 ### Configure with Azure CLI
 
 To deploy caches that pass this rule:

docs/en/rules/Azure.Redis.NonSslPort.md

@@ -96,6 +96,8 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cache/redis enableNonSslPort -->
+
 ## LINKS
 
 - [Data encryption in Azure](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-encryption#data-in-transit)

docs/en/rules/Azure.Redis.PublicNetworkAccess.md

@@ -106,6 +106,8 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = {
 }
 ```
 
+<!-- external:avm avm/res/cache/redis publicNetworkAccess -->
+
 ## LINKS
 
 - [Azure services for securing network connectivity](https://learn.microsoft.com/azure/well-architected/security/design-network-connectivity)

docs/en/rules/Azure.VNET.UseNSGs.md

@@ -148,7 +148,7 @@ Set-AzVirtualNetworkSubnetConfig -Name '<subnet>' -VirtualNetwork $vnet -Address
 
 ## NOTES
 
-If you identify a false postive for an Azure service that does not support NSGs,
+If you identify a false positive for an Azure service that does not support NSGs,
 please [open an issue](https://github.com/Azure/PSRule.Rules.Azure/issues/new) to help us improve this rule.
 
 To exclude subnets that are specific to your environment, use the `AZURE_VNET_SUBNET_EXCLUDED_FROM_NSG` configuration option.

docs/en/rules/Azure.VNG.ERLegacySKU.md

@@ -1,7 +1,7 @@
 ---
-severity: Important
-pillar: Operational Excellence
-category: Deployment
+severity: Critical
+pillar: Reliability
+category: RE:04 Target metrics
 resource: Virtual Network Gateway
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VNG.ERLegacySKU/
 ---
@@ -18,13 +18,14 @@ When deploying a ER gateway a number of options are available including SKU/ siz
 The gateway SKU affects the reliance and performance of the underlying gateway instances.
 Previously the following SKUs were available however have been depreciated.
 
-- Basic
+- `Basic`
 
 ## RECOMMENDATION
 
 Consider redeploying ER gateways using new SKUs to improve reliability and performance of gateways.
 
 ## LINKS
 
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Estimated performances by gateway SKU](https://learn.microsoft.com/azure/expressroute/expressroute-about-virtual-network-gateways#aggthroughput)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.network/virtualnetworkgateways)

docs/en/rules/Azure.VNG.VPNActiveActive.md

@@ -28,6 +28,90 @@ Gateways configured to use an Active-Active configuration:
 
 Consider using Active-Active VPN gateways to reduce connectivity downtime during HA failover.
 
+## EXAMPLES
+
+### Configure with Azure template
+
+To configure VPN gateways that pass this rule:
+
+- Set `properties.activeActive` to `true`.
+
+For example:
+
+```json
+{
+  "type": "Microsoft.Network/virtualNetworkGateways",
+  "apiVersion": "2023-11-01",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "properties": {
+    "gatewayType": "Vpn",
+    "ipConfigurations": [
+      {
+        "name": "default",
+        "properties": {
+          "privateIPAllocationMethod": "Dynamic",
+          "subnet": {
+            "id": "[parameters('subnetId')]"
+          },
+          "publicIPAddress": {
+            "id": "[parameters('pipId')]"
+          }
+        }
+      }
+    ],
+    "activeActive": true,
+    "vpnType": "RouteBased",
+    "vpnGatewayGeneration": "Generation2",
+    "sku": {
+      "name": "VpnGw1AZ",
+      "tier": "VpnGw1AZ"
+    }
+  }
+}
+```
+
+### Configure with Bicep
+
+To configure VPN gateways that pass this rule:
+
+- Set `properties.activeActive` to `true`.
+
+For example:
+
+```bicep
+resource vng 'Microsoft.Network/virtualNetworkGateways@2023-11-01' = {
+  name: name
+  location: location
+  properties: {
+    gatewayType: 'Vpn'
+    ipConfigurations: [
+      {
+        name: 'default'
+        properties: {
+          privateIPAllocationMethod: 'Dynamic'
+          subnet: {
+            id: subnetId
+          }
+          publicIPAddress: {
+            id: pipId
+          }
+        }
+      }
+    ]
+    activeActive: true
+    vpnType: 'RouteBased'
+    vpnGatewayGeneration: 'Generation2'
+    sku: {
+      name: 'VpnGw1AZ'
+      tier: 'VpnGw1AZ'
+    }
+  }
+}
+```
+
+<!-- external:avm avm/res/network/virtual-network-gateway activeActive -->
+
 ## NOTES
 
 Azure provisions a single instance for Basic (legacy) VPN gateways.

docs/en/rules/Azure.VNG.VPNAvailabilityZoneSKU.md

@@ -16,11 +16,11 @@ Use availability zone SKU for virtual network gateways deployed with VPN gateway
 
 VPN gateways can be deployed in Availability Zones with the following SKUs:
 
-- VpnGw1AZ
-- VpnGw2AZ
-- VpnGw3AZ
-- VpnGw4AZ
-- VpnGw5AZ
+- `VpnGw1AZ`
+- `VpnGw2AZ`
+- `VpnGw3AZ`
+- `VpnGw4AZ`
+- `VpnGw5AZ`
 
 This brings resiliency, scalability, and higher availability to VPN gateways.
 Deploying VPN gateways in Azure Availability Zones physically and logically separates gateways within a region, while protecting your on-premises network connectivity to Azure from zone-level failures.
@@ -33,22 +33,22 @@ Consider deploying VPN gateways with an availability zone SKU to improve reliabi
 
 ### Configure with Azure template
 
-To configure an AZ SKU for a VPN gateway:
+To configure VPN gateways that pass this rule:
 
-- Set `properties.gatewayType` to `'Vpn'`
+- Set `properties.gatewayType` to `Vpn`.
 - Set `properties.sku.name` and `properties.sku.tier` to one of the following AZ SKUs:
-  - `'VpnGw1AZ'`
-  - `'VpnGw2AZ'`
-  - `'VpnGw3AZ'`
-  - `'VpnGw4AZ'`
-  - `'VpnGw5AZ'`
+  - `VpnGw1AZ`
+  - `VpnGw2AZ`
+  - `VpnGw3AZ`
+  - `VpnGw4AZ`
+  - `VpnGw5AZ`
 
 For example:
 
 ```json
 {
   "type": "Microsoft.Network/virtualNetworkGateways",
-  "apiVersion": "2023-06-01",
+  "apiVersion": "2023-11-01",
   "name": "[parameters('name')]",
   "location": "[parameters('location')]",
   "properties": {
@@ -67,6 +67,7 @@ For example:
         }
       }
     ],
+    "activeActive": true,
     "vpnType": "RouteBased",
     "vpnGatewayGeneration": "Generation2",
     "sku": {
@@ -79,20 +80,20 @@ For example:
 
 ### Configure with Bicep
 
-To configure an AZ SKU for a VPN gateway:
+To configure VPN gateways that pass this rule:
 
-- Set `properties.gatewayType` to `'Vpn'`
+- Set `properties.gatewayType` to `Vpn`.
 - Set `properties.sku.name` and `properties.sku.tier` to one of the following AZ SKUs:
-  - `'VpnGw1AZ'`
-  - `'VpnGw2AZ'`
-  - `'VpnGw3AZ'`
-  - `'VpnGw4AZ'`
-  - `'VpnGw5AZ'`
+  - `VpnGw1AZ`
+  - `VpnGw2AZ`
+  - `VpnGw3AZ`
+  - `VpnGw4AZ`
+  - `VpnGw5AZ`
 
 For example:
 
 ```bicep
-resource vng 'Microsoft.Network/virtualNetworkGateways@2023-06-01' = {
+resource vng 'Microsoft.Network/virtualNetworkGateways@2023-11-01' = {
   name: name
   location: location
   properties: {
@@ -111,6 +112,7 @@ resource vng 'Microsoft.Network/virtualNetworkGateways@2023-06-01' = {
         }
       }
     ]
+    activeActive: true
     vpnType: 'RouteBased'
     vpnGatewayGeneration: 'Generation2'
     sku: {
@@ -119,9 +121,10 @@ resource vng 'Microsoft.Network/virtualNetworkGateways@2023-06-01' = {
     }
   }
 }
-
 ```
 
+<!-- external:avm avm/res/network/virtual-network-gateway skuName -->
+
 ## NOTES
 
 VPN gateway availability zones are managed via Public IP addresses, and are flagged separately under the `Azure.PublicIP.AvailabilityZone` rule.