Rule doc improvements (#3140)

Azure · Oct 22, 2024 · 5d582bb · 5d582bb
1 parent d6947c9
commit 5d582bb
Show file tree

Hide file tree

Showing 9 changed files with 44 additions and 39 deletions.
diff --git a/docs/en/rules/Azure.PublicIP.StandardSKU.md b/docs/en/rules/Azure.PublicIP.StandardSKU.md
@@ -1,25 +1,23 @@
 ---
-reviewed: 2023-09-10
+reviewed: 2024-10-21
 severity: Important
 pillar: Reliability
-category: Requirements
+category: RE:04 Target metrics
 resource: Public IP address
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.PublicIP.StandardSKU/
 ---
 
-# Public IP addresses should use Standard SKU
+# Public IP address uses basic SKU
 
 ## SYNOPSIS
 
-Public IP addresses should be deployed with Standard SKU for production workloads.
+The basic SKU is being retired on 30 September 2025, and does not include several reliability and security features.
 
 ## DESCRIPTION
 
 Public IP addresses allow Internet resources to communicate inbound to Azure resources.
 Currently two SKUs are supported: Basic and Standard.
 
-However, the Basic SKU for Public IP addresses will be retired on September 30, 2025.
-
 The Standard SKU additionally offers security and redundancy improvements over the Basic SKU.
 Including:
 
@@ -47,7 +45,7 @@ For example:
 ```json
 {
   "type": "Microsoft.Network/publicIPAddresses",
-  "apiVersion": "2023-05-01",
+  "apiVersion": "2024-01-01",
   "name": "[parameters('name')]",
   "location": "[parameters('location')]",
   "sku": {
@@ -78,7 +76,7 @@ For example:
 For example:
 
 ```bicep
-resource pip 'Microsoft.Network/publicIPAddresses@2023-05-01' = {
+resource pip 'Microsoft.Network/publicIPAddresses@2024-01-01' = {
   name: name
   location: location
   sku: {
@@ -98,9 +96,11 @@ resource pip 'Microsoft.Network/publicIPAddresses@2023-05-01' = {
 }
 ```
 
+<!-- external:avm avm/res/network/public-ip-address skuName -->
+
 ## LINKS
 
-- [Meet application platform requirements](https://learn.microsoft.com/azure/well-architected/resiliency/design-requirements#meet-application-platform-requirements)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Standard Public IP addresses](https://learn.microsoft.com/azure/virtual-network/ip-services/public-ip-addresses#sku)
 - [Load Balancer and Availability Zones](https://learn.microsoft.com/azure/load-balancer/load-balancer-standard-availability-zones)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.network/publicipaddresses)
diff --git a/docs/en/rules/Azure.Storage.ContainerSoftDelete.md b/docs/en/rules/Azure.Storage.ContainerSoftDelete.md
@@ -2,7 +2,7 @@
 reviewed: 2023-09-02
 severity: Important
 pillar: Reliability
-category: Data management
+category: RE:04 Target metrics
 resource: Storage Account
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Storage.ContainerSoftDelete/
 ---
@@ -153,7 +153,7 @@ Storage accounts with:
 
 ## LINKS
 
-- [Data management for reliability](https://learn.microsoft.com/azure/well-architected/resiliency/data-management)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Storage Accounts and reliability](https://learn.microsoft.com/azure/well-architected/services/storage/storage-accounts/reliability)
 - [Soft delete for containers](https://learn.microsoft.com/azure/storage/blobs/soft-delete-container-overview)
 - [Enable and manage soft delete for containers](https://learn.microsoft.com/azure/storage/blobs/soft-delete-container-enable)

diff --git a/docs/en/rules/Azure.Storage.FileShareSoftDelete.md b/docs/en/rules/Azure.Storage.FileShareSoftDelete.md
@@ -2,7 +2,7 @@
 reviewed: 2023-09-02
 severity: Important
 pillar: Reliability
-category: Data Management
+category: RE:04 Target metrics
 resource: Storage Account
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Storage.FileShareSoftDelete/
 ---
@@ -79,14 +79,16 @@ resource fileServices 'Microsoft.Storage/storageAccounts/fileServices@2023-01-01
 }
 ```
 
+<!-- external:avm avm/res/storage/storage-account fileServices -->
+
 ## Notes
 
 Cloud Shell storage with the tag `ms-resource-usage = 'azure-cloud-shell'` is excluded.
 Storage accounts used for Cloud Shell are not intended to store data.
 
 ## Links
 
-- [Data management for reliability](https://learn.microsoft.com/azure/well-architected/resiliency/data-management)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Storage Accounts and reliability](https://learn.microsoft.com/azure/well-architected/services/storage/storage-accounts/reliability)
 - [Enable soft delete on Azure file shares](https://learn.microsoft.com/azure/storage/files/storage-files-prevent-file-share-deletion)
 - [About Azure file share backup](https://learn.microsoft.com/azure/backup/azure-file-share-backup-overview)

diff --git a/docs/en/rules/Azure.Storage.SoftDelete.md b/docs/en/rules/Azure.Storage.SoftDelete.md
@@ -2,7 +2,7 @@
 reviewed: 2023-09-02
 severity: Important
 pillar: Reliability
-category: Data management
+category: RE:04 Target metrics
 resource: Storage Account
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Storage.SoftDelete/
 ms-content-id: 9927b427-e694-4485-9abf-61545e63956e
@@ -129,6 +129,8 @@ resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-01-01'
 }
 ```
 
+<!-- external:avm avm/res/storage/storage-account blobServices -->
+
 ### Configure with Azure CLI
 
 ```bash
@@ -153,7 +155,7 @@ Storage accounts with:
 
 ## LINKS
 
-- [Data management for reliability](https://learn.microsoft.com/azure/well-architected/resiliency/data-management)
+- [RE:04 Target metrics](https://learn.microsoft.com/azure/well-architected/reliability/metrics)
 - [Storage Accounts and reliability](https://learn.microsoft.com/azure/well-architected/services/storage/storage-accounts/reliability)
 - [Soft delete for Azure Storage blobs](https://learn.microsoft.com/azure/storage/blobs/soft-delete-blob-overview)
 - [Blob storage features available in Azure Data Lake Storage Gen2](https://learn.microsoft.com/azure/storage/blobs/storage-feature-support-in-storage-accounts)

diff --git a/docs/en/rules/Azure.Storage.UseReplication.md b/docs/en/rules/Azure.Storage.UseReplication.md
@@ -1,20 +1,21 @@
 ---
 severity: Important
 pillar: Reliability
-category: Requirements
+category: RE:05 Regions and availability zones
 resource: Storage Account
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Storage.UseReplication/
 ---
 
-# Use geo-replicated or zone-replicated storage
+# Storage Account is available in a single zone
 
 ## SYNOPSIS
 
-Storage Accounts not using geo-replicated storage (GRS) or zone-redundant (ZRS) may be at risk.
+Storage Accounts using the LRS SKU are only replicated within a single zone.
 
 ## DESCRIPTION
 
-Storage Accounts can be configured with several different durability options.
+Storage Accounts can be configured with several different durability options that replicate data between regions/ zones.
+
 Azure provides a number of geo-replicated options including;
 Geo-redundant storage and geo-zone-redundant storage.
 Geo-zone-redundant storage is only available in supported regions.
@@ -32,7 +33,7 @@ The following geo-replicated and zone-replicated options are available within Az
 
 ## RECOMMENDATION
 
-Consider using GRS for storage accounts that contain data.
+Consider using a zone-redundant or geo-replicated SKU for storage accounts that contain data.
 
 ## EXAMPLES
 
@@ -48,7 +49,7 @@ For example:
 ```json
 {
   "type": "Microsoft.Storage/storageAccounts",
-  "apiVersion": "2023-01-01",
+  "apiVersion": "2023-05-01",
   "name": "[parameters('name')]",
   "location": "[parameters('location')]",
   "sku": {
@@ -78,7 +79,7 @@ To deploy Storage Accounts that pass this rule:
 For example:
 
 ```bicep
-resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
+resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
   name: name
   location: location
   sku: {
@@ -114,6 +115,6 @@ Storage Accounts with the following tags are automatically excluded from this ru
 
 ## LINKS
 
-- [Meet application platform requirements](https://learn.microsoft.com/azure/well-architected/resiliency/design-requirements#meet-application-platform-requirements)
+- [RE:05 Regions and availability zones](https://learn.microsoft.com/azure/well-architected/reliability/regions-availability-zones)
 - [Azure Storage redundancy](https://learn.microsoft.com/azure/storage/common/storage-redundancy)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.storage/storageaccounts)
diff --git a/docs/examples/resources/public-ip.bicep b/docs/examples/resources/public-ip.bicep
@@ -12,7 +12,7 @@ param name string
 param location string = resourceGroup().location
 
 // An example zone redundant public IP address
-resource pip 'Microsoft.Network/publicIPAddresses@2023-05-01' = {
+resource pip 'Microsoft.Network/publicIPAddresses@2024-01-01' = {
   name: name
   location: location
   sku: {

diff --git a/docs/examples/resources/public-ip.json b/docs/examples/resources/public-ip.json
@@ -4,8 +4,8 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.23.1.45101",
-      "templateHash": "12243310267082646460"
+      "version": "0.30.23.60470",
+      "templateHash": "14966441605848938223"
     }
   },
   "parameters": {
@@ -28,7 +28,7 @@
   "resources": [
     {
       "type": "Microsoft.Network/publicIPAddresses",
-      "apiVersion": "2023-05-01",
+      "apiVersion": "2024-01-01",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "sku": {

diff --git a/docs/examples/resources/storage.bicep b/docs/examples/resources/storage.bicep
@@ -16,7 +16,7 @@ var containerName = 'data'
 var shareName = 'group'
 
 // Define a Storage Account with common security settings.
-resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
+resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
   name: name
   location: location
   sku: {
@@ -36,7 +36,7 @@ resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
 }
 
 // Configure blob services with soft-delete enabled.
-resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-01-01' = {
+resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = {
   parent: storageAccount
   name: 'default'
   properties: {
@@ -52,7 +52,7 @@ resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-01-01'
 }
 
 // Create a storage container.
-resource container 'Microsoft.Storage/storageAccounts/blobServices/containers@2023-01-01' = {
+resource container 'Microsoft.Storage/storageAccounts/blobServices/containers@2023-05-01' = {
   parent: blobService
   name: containerName
   properties: {
@@ -61,7 +61,7 @@ resource container 'Microsoft.Storage/storageAccounts/blobServices/containers@20
 }
 
 // Configure file services.
-resource fileServices 'Microsoft.Storage/storageAccounts/fileServices@2023-01-01' = {
+resource fileServices 'Microsoft.Storage/storageAccounts/fileServices@2023-05-01' = {
   parent: storageAccount
   name: 'default'
   properties: {
@@ -73,7 +73,7 @@ resource fileServices 'Microsoft.Storage/storageAccounts/fileServices@2023-01-01
 }
 
 // Create a file share.
-resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-01-01' = {
+resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-05-01' = {
   parent: fileServices
   name: shareName
   properties: {

diff --git a/docs/examples/resources/storage.json b/docs/examples/resources/storage.json
@@ -4,8 +4,8 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.25.53.49325",
-      "templateHash": "6095867228458030395"
+      "version": "0.30.23.60470",
+      "templateHash": "12565367391351048463"
     }
   },
   "parameters": {
@@ -30,7 +30,7 @@
   "resources": [
     {
       "type": "Microsoft.Storage/storageAccounts",
-      "apiVersion": "2023-01-01",
+      "apiVersion": "2023-05-01",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "sku": {
@@ -50,7 +50,7 @@
     },
     {
       "type": "Microsoft.Storage/storageAccounts/blobServices",
-      "apiVersion": "2023-01-01",
+      "apiVersion": "2023-05-01",
       "name": "[format('{0}/{1}', parameters('name'), 'default')]",
       "properties": {
         "deleteRetentionPolicy": {
@@ -68,7 +68,7 @@
     },
     {
       "type": "Microsoft.Storage/storageAccounts/blobServices/containers",
-      "apiVersion": "2023-01-01",
+      "apiVersion": "2023-05-01",
       "name": "[format('{0}/{1}/{2}', parameters('name'), 'default', variables('containerName'))]",
       "properties": {
         "publicAccess": "None"
@@ -79,7 +79,7 @@
     },
     {
       "type": "Microsoft.Storage/storageAccounts/fileServices",
-      "apiVersion": "2023-01-01",
+      "apiVersion": "2023-05-01",
       "name": "[format('{0}/{1}', parameters('name'), 'default')]",
       "properties": {
         "shareDeleteRetentionPolicy": {
@@ -93,7 +93,7 @@
     },
     {
       "type": "Microsoft.Storage/storageAccounts/fileServices/shares",
-      "apiVersion": "2023-01-01",
+      "apiVersion": "2023-05-01",
       "name": "[format('{0}/{1}/{2}', parameters('name'), 'default', variables('shareName'))]",
       "properties": {
         "accessTier": "TransactionOptimized"