WAF documentation improvements #2570 (#2750)

* WAF documentation improvements #2570 * Fix
Azure · Mar 11, 2024 · eba9677 · eba9677
1 parent de51696
commit eba9677
Show file tree

Hide file tree

Showing 10 changed files with 41 additions and 24 deletions.
diff --git a/BaselineToc.Doc.ps1 b/BaselineToc.Doc.ps1
@@ -28,7 +28,8 @@ Document 'baseline' -If { $PSDocs.TargetObject.Name -ne 'Azure.MCSB.v1' } {
     Write-Verbose -Message "[Baseline] -- Found $ruleCount rules.";
 
     Section 'Rules' -If { $ruleCount -gt 0 } {
-        "The following rules are included within the ``$baselineName`` baseline. This baseline includes a total of $ruleCount rules.";
+        "The following rules are included within the ``$baselineName`` baseline.";
+        "This baseline includes a total of $ruleCount rules.";
         $rules | Table -Property @{ Name = 'Name'; Expression = {
             "[$($_.Name)](../rules/$($_.Name).md)"
         }}, Synopsis, @{ Name = 'Severity'; Expression = {
@@ -66,7 +67,8 @@ Document 'Azure.MCSB.Baseline' -If { $PSDocs.TargetObject.Name -eq 'Azure.MCSB.v
     Write-Verbose -Message "[Baseline] -- Found $ruleCount rules.";
 
     Section 'Controls' -If { $ruleCount -gt 0 } {
-        "The following rules are included within the ``$baselineName`` baseline. This baseline includes a total of $ruleCount rules.";
+        "The following rules are included within the ``$baselineName`` baseline.";
+        "This baseline includes a total of $ruleCount rules.";
         $rules | Table -Property @{ Name = 'Name'; Expression = {
             "[$($_.Name)](../rules/$($_.Name).md)"
         }}, Synopsis, @{ Name = 'Severity'; Expression = {

diff --git a/docs/en/rules/Azure.ACR.Retention.md b/docs/en/rules/Azure.ACR.Retention.md
@@ -1,7 +1,7 @@
 ---
 severity: Important
 pillar: Cost Optimization
-category: Resource usage
+category: CO:10 Data costs
 resource: Container Registry
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.ACR.Retention/
 ---
@@ -40,7 +40,7 @@ For example:
 ```json
 {
   "type": "Microsoft.ContainerRegistry/registries",
-  "apiVersion": "2023-01-01-preview",
+  "apiVersion": "2023-11-01-preview",
   "name": "[parameters('registryName')]",
   "location": "[parameters('location')]",
   "sku": {
@@ -81,7 +81,7 @@ To deploy Container Registries that pass this rule:
 For example:
 
 ```bicep
-resource acr 'Microsoft.ContainerRegistry/registries@2023-01-01-preview' = {
+resource acr 'Microsoft.ContainerRegistry/registries@2023-11-01-preview' = {
   name: registryName
   location: location
   sku: {
@@ -119,7 +119,8 @@ Retention policies for Azure Container Registry is currently in preview.
 
 ## LINKS
 
-- [Scalable storage](https://docs.microsoft.com/azure/container-registry/container-registry-storage#scalable-storage)
-- [Set a retention policy for untagged manifests](https://docs.microsoft.com/azure/container-registry/container-registry-retention-policy)
-- [Lock a container image in an Azure container registry](https://docs.microsoft.com/azure/container-registry/container-registry-image-lock)
+- [CO:10 Data costs](https://learn.microsoft.com/azure/well-architected/cost-optimization/optimize-data-costs)
+- [Set a retention policy for untagged manifests](https://learn.microsoft.com/azure/container-registry/container-registry-retention-policy)
+- [Lock a container image in an Azure container registry](https://learn.microsoft.com/azure/container-registry/container-registry-image-lock)
+- [Scalable storage](https://learn.microsoft.com/azure/container-registry/container-registry-storage#scalable-storage)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.containerregistry/registries)
diff --git a/docs/en/rules/Azure.ADX.Usage.md b/docs/en/rules/Azure.ADX.Usage.md
@@ -20,7 +20,7 @@ To store data in an ADX cluster, you must first create a database.
 Clusters without any databases are considered unused and can be removed to reduce costs and management overhead.
 
 Additionally, ADX clusters on a paid tier can stopped.
-Stopping an ADX cluster deallocates and removes compute resources.
+Stopping an ADX cluster de-allocates and removes compute resources.
 While in the stopped state, compute charges are not incurred.
 Any data stored in the cluster is persisted while the cluster is stopped.
 

diff --git a/docs/en/rules/Azure.VM.DiskAttached.md b/docs/en/rules/Azure.VM.DiskAttached.md
@@ -1,7 +1,8 @@
 ---
+reviewed: 2024-03-11
 severity: Important
 pillar: Cost Optimization
-category: Resource usage
+category: CO:07 Component costs
 resource: Virtual Machine
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.DiskAttached/
 ms-content-id: 23a06a0e-7965-4d43-8e29-bb9ac6eeffcc
@@ -22,6 +23,11 @@ Unattached managed disks still consume storage and are charged on their size.
 
 Consider removing managed disks that are no longer required to reduce complexity and costs.
 
+## NOTES
+
+This rule applies when analyzing resources deployed (in-flight) to Azure.
+
 ## LINKS
 
+- [CO:07 Component costs](https://learn.microsoft.com/azure/well-architected/cost-optimization/optimize-component-costs)
 - [Managed Disk pricing](https://azure.microsoft.com/pricing/details/managed-disks/)
diff --git a/docs/en/rules/Azure.VM.PromoSku.md b/docs/en/rules/Azure.VM.PromoSku.md
@@ -1,7 +1,8 @@
 ---
+reviewed: 2024-03-11
 severity: Awareness
 pillar: Cost Optimization
-category: Pricing and billing model
+category: CO:05 Rate optimization
 resource: Virtual Machine
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.PromoSku/
 ---
@@ -15,7 +16,8 @@ Virtual machines (VMs) should not use expired promotional SKU.
 ## DESCRIPTION
 
 Some VM sizes may offer promotional rates that can be used by deploying VMs with a designated SKU.
-Promotional rates expire, and while this does not cause interruption to running VMs, the rate that VMs are billed at returns to the original price.
+Promotional rates expire, and while this does not cause interruption to running VMs,
+the rate that VMs are billed at returns to the original price.
 
 Promo SKUs are not eligible for savings from reserved instances.
 Expired promo SKUs may confuse billing reconciliation when the promotional period expires.
@@ -25,9 +27,9 @@ VMs should not use expired promo SKU.
 ## RECOMMENDATION
 
 Consider moving from promotional SKUs to SKUs eligible for reserved instances for VMs with an extended life cycle.
-Consider moving from promotional SKUs to the regular SKU once the promotional period has expired.
+Alternatively, consider moving from promotional SKUs to the regular SKU once the promotional period has expired.
 
 ## LINKS
 
-- [Design review checklist for Cost Optimization](https://learn.microsoft.com/azure/well-architected/cost-optimization/checklist)
+- [CO:05 Rate optimization](https://learn.microsoft.com/azure/well-architected/cost-optimization/get-best-rates)
 - [Virtual Machine pricing](https://azure.microsoft.com/pricing/details/virtual-machines/linux/)
diff --git a/docs/en/rules/Azure.VM.ShouldNotBeStopped.md b/docs/en/rules/Azure.VM.ShouldNotBeStopped.md
@@ -1,7 +1,8 @@
 ---
+reviewed: 2024-03-11
 severity: Important
 pillar: Cost Optimization
-category: Resource usage
+category: CO:07 Component costs
 resource: Virtual Machine
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.ShouldNotBeStopped/
 ---
@@ -14,13 +15,18 @@ Azure VMs should be running or in a deallocated state.
 
 ## DESCRIPTION
 
-Azure Virtual Machines in a stopped state are still billed hourly for compute usage. Therefor VMs should generally be in a deallocated or running state.
+Azure Virtual Machines in a stopped state are still billed hourly for compute usage.
+Therefor VMs should generally be in a deallocated or running state.
 
 ## RECOMMENDATION
 
-Consider fully deallocating VMs instead of stopping VMs to reduce cost.
+Consider fully de-allocating VMs instead of stopping VMs to reduce cost.
+
+## NOTES
+
+This rule applies when analyzing resources deployed (in-flight) to Azure.
 
 ## LINKS
 
-- [Shut down underutilized instances](https://learn.microsoft.com/azure/architecture/framework/cost/optimize-vm#shut-down-underutilized-instances)
+- [CO:07 Component costs](https://learn.microsoft.com/azure/well-architected/cost-optimization/optimize-component-costs)
 - [States and billing status of Azure Virtual Machines](https://learn.microsoft.com/azure/virtual-machines/states-billing)
diff --git a/docs/examples-acr.bicep b/docs/examples-acr.bicep
@@ -12,7 +12,7 @@ param name string
 param location string = resourceGroup().location
 
 // An example container registry deployed with Premium SKU.
-resource registry 'Microsoft.ContainerRegistry/registries@2023-08-01-preview' = {
+resource registry 'Microsoft.ContainerRegistry/registries@2023-11-01-preview' = {
   name: name
   location: location
   sku: {

diff --git a/docs/examples-acr.json b/docs/examples-acr.json
@@ -4,8 +4,8 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.24.24.22086",
-      "templateHash": "762310929453665015"
+      "version": "0.25.53.49325",
+      "templateHash": "18407530808560387725"
     }
   },
   "parameters": {
@@ -28,7 +28,7 @@
   "resources": [
     {
       "type": "Microsoft.ContainerRegistry/registries",
-      "apiVersion": "2023-08-01-preview",
+      "apiVersion": "2023-11-01-preview",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "sku": {

diff --git a/src/PSRule.Rules.Azure/rules/Azure.VM.Rule.ps1 b/src/PSRule.Rules.Azure/rules/Azure.VM.Rule.ps1
@@ -117,7 +117,7 @@ Rule 'Azure.VM.ComputerName' -Ref 'AZR-000249' -Type 'Microsoft.Compute/virtualM
 #region Managed Disks
 
 # Synopsis: Managed disks should be attached to virtual machines
-Rule 'Azure.VM.DiskAttached' -Ref 'AZR-000250' -Type 'Microsoft.Compute/disks' -If { ($TargetObject.ResourceName -notlike '*-ASRReplica') -and (IsExport) } -Tag @{ release = 'GA'; ruleSet = '2020_06'; 'Azure.WAF/pillar' = 'Security'; } -Labels @{ 'Azure.MCSB.v1/control' = 'DP-4' } {
+Rule 'Azure.VM.DiskAttached' -Ref 'AZR-000250' -Type 'Microsoft.Compute/disks' -If { ($TargetObject.ResourceName -notlike '*-ASRReplica') -and (IsExport) } -Tag @{ release = 'GA'; ruleSet = '2020_06'; 'Azure.WAF/pillar' = 'Cost Optimization'; } {
     # Disks should be attached unless they are used by ASR, which are not attached until fail over
     # Disks for VMs that are off are marked as Reserved
     Within 'properties.diskState' 'Attached', 'Reserved' -Reason $LocalizedData.ResourceNotAssociated

diff --git a/tests/PSRule.Rules.Azure.Tests/Azure.VM.Tests.ps1 b/tests/PSRule.Rules.Azure.Tests/Azure.VM.Tests.ps1
@@ -562,7 +562,7 @@ Describe 'Azure.VM' -Tag 'VM' {
             $ruleResult.Length | Should -Be 1;
             $ruleResult.TargetName | Should -BeIn 'vm-F';
 
-            $ruleResult[0].Recommendation | Should -BeExactly "Consider fully deallocating VMs instead of stopping VMs to reduce cost.";
+            $ruleResult[0].Recommendation | Should -BeExactly "Consider fully de-allocating VMs instead of stopping VMs to reduce cost.";
 
             # Pass
             $ruleResult = @($filteredResult | Where-Object { $_.Outcome -eq 'Pass'});