Create rule S6893: Use a constant value for the apiVersion (#3778)

rules/S6378/azureresourcemanager/rule.adoc

@@ -17,7 +17,7 @@ Using ARM templates:
         {
             "type": "Microsoft.ApiManagement/service",
             "apiVersion": "2022-09-01-preview",
-            "name": "apiManagementService",
+            "name": "apiManagementService"
         }
     ]
 }

rules/S6893/kubernetes/metadata.json → rules/S6893/azureresourcemanager/metadata.json

@@ -1,10 +1,10 @@
 {
-  "title": "Ensure whitespace in-between braces in template directives",
+  "title": "Use a constant value for the apiVersion",
   "type": "CODE_SMELL",
   "status": "ready",
   "remediation": {
     "func": "Constant\/Issue",
-    "constantCost": "1min"
+    "constantCost": "2min"
   },
   "tags": [
   ],
@@ -16,8 +16,9 @@
   "quickfix": "unknown",
   "code": {
     "impacts": {
-      "MAINTAINABILITY": "MEDIUM"
+      "MAINTAINABILITY": "MEDIUM",
+      "RELIABILITY": "MEDIUM"
     },
-    "attribute": "FORMATTED"
+    "attribute": "LOGICAL"
   }
 }

rules/S6893/azureresourcemanager/rule.adoc

@@ -0,0 +1,110 @@
+
+The `apiVersion` of a resource is used to determine the configurable properties and values for the resource.
+Setting it as a parameter or variable is not recommended, as it can lead to unexpected behaviors and deployment failures.
+
+== Why is this an issue?
+
+In Azure, different API versions of a resource can have different properties and values.
+
+Using a variable or parameter for the `apiVersion` for a resource is not an optimal way to always stay up to date with
+the latest version.
+This can lead to unexpected behaviors like deployment failures,
+when the API version you set for a resource doesn't match the properties in your template.
+
+
+== How to fix it in ARM Templates
+
+To avoid these issues, it is recommended to set the `apiVersion` to a constant value for the resource type.
+
+When creating a new template, we suggest you use the latest API version for a resource type.
+
+To determine which version to use, you can refer to the template reference of the official documentation linked below.
+Make sure to choose a version that supports all the features you need.
+
+When your template works as expected, we recommend you continue using the same API version.
+Using the same API version means you don't have to worry about breaking changes that might be introduced in later versions.
+
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,json,diff-id=1,diff-type=noncompliant]
+----
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "parameters": {
+    "customApiVersion": {
+      "type": "string"
+    }
+  },
+  "resources": [
+    {
+      "apiVersion": "[parameters('customApiVersion')]",
+      "type": "Microsoft.Compute/virtualMachines",
+      "name": "nonCompliantResource",
+      "location": "[resourceGroup().location]"
+    }
+  ]
+}
+----
+
+[source,json]
+----
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "variables": {
+    "customApiVersion": "[first(providers(‘Microsoft.Compute’,’virtualMachines’).apiVersions)]"
+  },
+  "resources": [
+    {
+      "apiVersion": "[variables('customApiVersion')]",
+      "type": "Microsoft.Compute/virtualMachines",
+      "name": "nonCompliantResource",
+      "location": "[resourceGroup().location]"
+    }
+  ]
+}
+----
+
+
+==== Compliant solution
+
+[source,json,diff-id=1,diff-type=compliant]
+----
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "resources": [
+    {
+      "apiVersion": "2023-09-01",
+      "type": "Microsoft.Compute/virtualMachines",
+      "name": "compliantResource",
+      "location": "[resourceGroup().location]"
+    }
+  ]
+}
+----
+
+== Resources
+=== Documentation
+
+* https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/best-practices#api-version[ARM template best practices: API version]
+* https://learn.microsoft.com/en-us/azure/templates/[Resource Template Reference]
+
+ifdef::env-github,rspecator-view[]
+
+'''
+== Implementation Specification
+(visible only on this page)
+
+=== Message
+
+Use a constant value for the `apiVersion` of this resource.
+
+
+=== Highlighting
+
+* Highlight `apiVersion` of a resource where a parameter or variable is used.
+
+
+endif::env-github,rspecator-view[]