From 2749b72f48639695a16a97626f33da94e76318a2 Mon Sep 17 00:00:00 2001 From: Bernie White Date: Wed, 5 Jun 2024 00:20:07 +1000 Subject: [PATCH] Rule docs quality updates (#2912) --- docs/en/rules/Azure.Redis.AvailabilityZone.md | 6 +- .../en/rules/Azure.Redis.MaxMemoryReserved.md | 6 +- docs/en/rules/Azure.Redis.MinSKU.md | 6 +- docs/en/rules/Azure.Redis.MinTLS.md | 2 + docs/en/rules/Azure.Redis.NonSslPort.md | 2 + .../rules/Azure.Redis.PublicNetworkAccess.md | 2 + docs/en/rules/Azure.VNET.UseNSGs.md | 2 +- docs/en/rules/Azure.VNG.ERLegacySKU.md | 9 +- docs/en/rules/Azure.VNG.VPNActiveActive.md | 84 ++++++++++++ .../rules/Azure.VNG.VPNAvailabilityZoneSKU.md | 47 +++---- docs/en/rules/Azure.VNG.VPNLegacySKU.md | 122 +++++++++++++++++- docs/examples-vng.bicep | 3 +- docs/examples-vng.json | 7 +- .../rules/Azure.VNG.Rule.ps1 | 2 +- .../rules/Azure.VNG.Rule.yaml | 2 +- 15 files changed, 257 insertions(+), 45 deletions(-) diff --git a/docs/en/rules/Azure.Redis.AvailabilityZone.md b/docs/en/rules/Azure.Redis.AvailabilityZone.md index a270810a19..dbf28cd235 100644 --- a/docs/en/rules/Azure.Redis.AvailabilityZone.md +++ b/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' = { } ``` + + ## 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) diff --git a/docs/en/rules/Azure.Redis.MaxMemoryReserved.md b/docs/en/rules/Azure.Redis.MaxMemoryReserved.md index d7f1c7c352..1e47d8fcfd 100644 --- a/docs/en/rules/Azure.Redis.MaxMemoryReserved.md +++ b/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' = { } ``` + + ## 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) diff --git a/docs/en/rules/Azure.Redis.MinSKU.md b/docs/en/rules/Azure.Redis.MinSKU.md index 4743cdbc2d..447818c7b5 100644 --- a/docs/en/rules/Azure.Redis.MinSKU.md +++ b/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' = { } ``` + + ## 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) diff --git a/docs/en/rules/Azure.Redis.MinTLS.md b/docs/en/rules/Azure.Redis.MinTLS.md index ecb1dcd01a..38393a4bc0 100644 --- a/docs/en/rules/Azure.Redis.MinTLS.md +++ b/docs/en/rules/Azure.Redis.MinTLS.md @@ -96,6 +96,8 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = { } ``` + + ### Configure with Azure CLI To deploy caches that pass this rule: diff --git a/docs/en/rules/Azure.Redis.NonSslPort.md b/docs/en/rules/Azure.Redis.NonSslPort.md index 2ed6cc964b..bf86041d3e 100644 --- a/docs/en/rules/Azure.Redis.NonSslPort.md +++ b/docs/en/rules/Azure.Redis.NonSslPort.md @@ -96,6 +96,8 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = { } ``` + + ## LINKS - [Data encryption in Azure](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-encryption#data-in-transit) diff --git a/docs/en/rules/Azure.Redis.PublicNetworkAccess.md b/docs/en/rules/Azure.Redis.PublicNetworkAccess.md index 4b5930599c..06838e9e5f 100644 --- a/docs/en/rules/Azure.Redis.PublicNetworkAccess.md +++ b/docs/en/rules/Azure.Redis.PublicNetworkAccess.md @@ -106,6 +106,8 @@ resource cache 'Microsoft.Cache/redis@2023-04-01' = { } ``` + + ## LINKS - [Azure services for securing network connectivity](https://learn.microsoft.com/azure/well-architected/security/design-network-connectivity) diff --git a/docs/en/rules/Azure.VNET.UseNSGs.md b/docs/en/rules/Azure.VNET.UseNSGs.md index 350dfe1ee0..5ff6cf07f0 100644 --- a/docs/en/rules/Azure.VNET.UseNSGs.md +++ b/docs/en/rules/Azure.VNET.UseNSGs.md @@ -148,7 +148,7 @@ Set-AzVirtualNetworkSubnetConfig -Name '' -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. diff --git a/docs/en/rules/Azure.VNG.ERLegacySKU.md b/docs/en/rules/Azure.VNG.ERLegacySKU.md index d562c43a4b..5a51df2175 100644 --- a/docs/en/rules/Azure.VNG.ERLegacySKU.md +++ b/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,7 +18,7 @@ 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 @@ -26,5 +26,6 @@ Consider redeploying ER gateways using new SKUs to improve reliability and perfo ## 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) diff --git a/docs/en/rules/Azure.VNG.VPNActiveActive.md b/docs/en/rules/Azure.VNG.VPNActiveActive.md index 4c3ba671fc..8b5ba154c4 100644 --- a/docs/en/rules/Azure.VNG.VPNActiveActive.md +++ b/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' + } + } +} +``` + + + ## NOTES Azure provisions a single instance for Basic (legacy) VPN gateways. diff --git a/docs/en/rules/Azure.VNG.VPNAvailabilityZoneSKU.md b/docs/en/rules/Azure.VNG.VPNAvailabilityZoneSKU.md index ca8a56ad72..5acceb2885 100644 --- a/docs/en/rules/Azure.VNG.VPNAvailabilityZoneSKU.md +++ b/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' = { } } } - ``` + + ## NOTES VPN gateway availability zones are managed via Public IP addresses, and are flagged separately under the `Azure.PublicIP.AvailabilityZone` rule. diff --git a/docs/en/rules/Azure.VNG.VPNLegacySKU.md b/docs/en/rules/Azure.VNG.VPNLegacySKU.md index 33200abd56..567b9ec2f0 100644 --- a/docs/en/rules/Azure.VNG.VPNLegacySKU.md +++ b/docs/en/rules/Azure.VNG.VPNLegacySKU.md @@ -1,7 +1,8 @@ --- -severity: Important -pillar: Operational Excellence -category: Deployment +reviewed: 2024-06-04 +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.VPNLegacySKU/ --- @@ -18,15 +19,124 @@ When deploying a VPN gateway a number of options are available including SKU/ si The gateway SKU affects the reliance and performance of the underlying gateway instances. Previously the following SKUs were available however have been depreciated. -- Basic -- Standard -- HighPerformance +- `Basic` +- `Standard` +- `HighPerformance` + +The Standard and High Performance SKUs will be deprecated on September 30, 2025. ## RECOMMENDATION Consider redeploying VPN gateways using new SKUs to improve reliability and performance of gateways. +## EXAMPLES + +### Configure with Azure template + +To configure VPN gateways that pass this rule: + +- Set `properties.gatewayType` to `Vpn`. +- Set `properties.sku.name` and `properties.sku.tier` to one of the following SKUs: + - `VpnGw1` + - `VpnGw1AZ` + - `VpnGw2` + - `VpnGw2AZ` + - `VpnGw3` + - `VpnGw3AZ` + - `VpnGw4` + - `VpnGw4AZ` + - `VpnGw5` + - `VpnGw5AZ` + +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.gatewayType` to `Vpn`. +- Set `properties.sku.name` and `properties.sku.tier` to one of the following SKUs: + - `VpnGw1` + - `VpnGw1AZ` + - `VpnGw2` + - `VpnGw2AZ` + - `VpnGw3` + - `VpnGw3AZ` + - `VpnGw4` + - `VpnGw4AZ` + - `VpnGw5` + - `VpnGw5AZ` + +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' + } + } +} +``` + + + ## LINKS +- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics) - [Change to the new gateway SKUs](https://learn.microsoft.com/azure/vpn-gateway/vpn-gateway-about-skus-legacy#change) - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.network/virtualnetworkgateways) diff --git a/docs/examples-vng.bicep b/docs/examples-vng.bicep index 2d476c561b..6b0faf293e 100644 --- a/docs/examples-vng.bicep +++ b/docs/examples-vng.bicep @@ -16,7 +16,7 @@ param subnetId string param pipId string // An example Virtual Network Gateway with availability zone aware SKU. -resource vng 'Microsoft.Network/virtualNetworkGateways@2023-06-01' = { +resource vng 'Microsoft.Network/virtualNetworkGateways@2023-11-01' = { name: name location: location properties: { @@ -35,6 +35,7 @@ resource vng 'Microsoft.Network/virtualNetworkGateways@2023-06-01' = { } } ] + activeActive: true vpnType: 'RouteBased' vpnGatewayGeneration: 'Generation2' sku: { diff --git a/docs/examples-vng.json b/docs/examples-vng.json index 08319f39fc..bc1dfb4a4c 100644 --- a/docs/examples-vng.json +++ b/docs/examples-vng.json @@ -4,8 +4,8 @@ "metadata": { "_generator": { "name": "bicep", - "version": "0.24.24.22086", - "templateHash": "6204832215938608293" + "version": "0.27.1.19265", + "templateHash": "17685739923265585206" } }, "parameters": { @@ -38,7 +38,7 @@ "resources": [ { "type": "Microsoft.Network/virtualNetworkGateways", - "apiVersion": "2023-06-01", + "apiVersion": "2023-11-01", "name": "[parameters('name')]", "location": "[parameters('location')]", "properties": { @@ -57,6 +57,7 @@ } } ], + "activeActive": true, "vpnType": "RouteBased", "vpnGatewayGeneration": "Generation2", "sku": { diff --git a/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.ps1 b/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.ps1 index 699b9148bf..3f122d9951 100644 --- a/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.ps1 +++ b/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.ps1 @@ -8,7 +8,7 @@ #region Rules # Synopsis: Migrate from legacy ExpressRoute gateway SKUs -Rule 'Azure.VNG.ERLegacySKU' -Ref 'AZR-000271' -Type 'Microsoft.Network/virtualNetworkGateways' -With 'Azure.VNG.ERGateway' -Tag @{ release = 'GA'; ruleSet = '2020_06'; 'Azure.WAF/pillar' = 'Operational Excellence'; } { +Rule 'Azure.VNG.ERLegacySKU' -Ref 'AZR-000271' -Type 'Microsoft.Network/virtualNetworkGateways' -With 'Azure.VNG.ERGateway' -Tag @{ release = 'GA'; ruleSet = '2020_06'; 'Azure.WAF/pillar' = 'Reliability'; } { Within 'Properties.sku.name' -Not 'Basic'; } diff --git a/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.yaml b/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.yaml index b0646c2cb4..bf9d16d659 100644 --- a/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.yaml +++ b/src/PSRule.Rules.Azure/rules/Azure.VNG.Rule.yaml @@ -18,7 +18,7 @@ metadata: tags: release: GA ruleSet: 2020_06 - Azure.WAF/pillar: Operational Excellence + Azure.WAF/pillar: Reliability spec: type: - Microsoft.Network/virtualNetworkGateways