From 9489f1c4a959d5feea1f0020f8509e133eb1bf4a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 20 Mar 2024 12:49:15 +0100 Subject: [PATCH] Create rule S6893: Use a constant value for the apiVersion (#3778) --- rules/S6378/azureresourcemanager/rule.adoc | 2 +- .../metadata.json | 9 +- rules/S6893/azureresourcemanager/rule.adoc | 110 ++++++++++++++++++ rules/S6893/kubernetes/rule.adoc | 69 ----------- 4 files changed, 116 insertions(+), 74 deletions(-) rename rules/S6893/{kubernetes => azureresourcemanager}/metadata.json (65%) create mode 100644 rules/S6893/azureresourcemanager/rule.adoc delete mode 100644 rules/S6893/kubernetes/rule.adoc diff --git a/rules/S6378/azureresourcemanager/rule.adoc b/rules/S6378/azureresourcemanager/rule.adoc index f8ff86cf280..98d915babc0 100644 --- a/rules/S6378/azureresourcemanager/rule.adoc +++ b/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" } ] } diff --git a/rules/S6893/kubernetes/metadata.json b/rules/S6893/azureresourcemanager/metadata.json similarity index 65% rename from rules/S6893/kubernetes/metadata.json rename to rules/S6893/azureresourcemanager/metadata.json index 97128662607..6bb95191018 100644 --- a/rules/S6893/kubernetes/metadata.json +++ b/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" } } diff --git a/rules/S6893/azureresourcemanager/rule.adoc b/rules/S6893/azureresourcemanager/rule.adoc new file mode 100644 index 00000000000..e1aba1b7527 --- /dev/null +++ b/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[] diff --git a/rules/S6893/kubernetes/rule.adoc b/rules/S6893/kubernetes/rule.adoc deleted file mode 100644 index 6453696612f..00000000000 --- a/rules/S6893/kubernetes/rule.adoc +++ /dev/null @@ -1,69 +0,0 @@ -This rule raises an issue when template directives do not have a whitespace after the opening brace and before the closing brace. It's based on best practices in Helm and emphasizes the importance of maintaining this whitespace for better readability and understanding of the code. - -== Why is this an issue? -The absence of whitespace in template directives in Helm can lead to several issues: - -**Readability**: Code is read more often than it is written. When template directives are tightly packed without whitespaces, it can be challenging to distinguish between the braces and the content inside. This can slow down the process of understanding the code, especially for those who are new to the codebase. - -**Maintainability**: Hard-to-read code is also hard to maintain. If a developer struggles to understand what a piece of code does due to poor formatting, they may introduce bugs when they try to modify it. - -In summary, not having a whitespace after the opening brace and before the closing brace in template directives can make the code harder to read, understand, and maintain. - - -== How to fix it in Helm -To fix this issue, add a whitespace after the opening brace and before the closing brace in template directives. Also, ensure there is a whitespace after opening chomping braces `{{-` and before closing chomping braces `-}}`. - -=== Code examples - -==== Noncompliant code example - -[source,text,diff-id=1,diff-type=noncompliant] ----- -apiVersion: v1 -kind: Pod -metadata: - name: {{.Values.podName}} # Noncompliant -spec: - containers: - - name: {{-.Values.containerName-}} # Noncompliant ----- - -==== Compliant solution - -[source,text,diff-id=1,diff-type=compliant] ----- -apiVersion: v1 -kind: Pod -metadata: - name: {{ .Values.podName }} -spec: - containers: - - name: {{- .Values.containerName -}} ----- - - -== Resources -=== Documentation -* Helm Best Practices - https://helm.sh/docs/chart_best_practices/templates/#formatting-templates[Formatting Templates] -* Go Documentation - https://pkg.go.dev/text/template?utm_source=godoc#hdr-Text_and_spaces[Text and spaces] - -ifdef::env-github,rspecator-view[] - -''' -== Implementation Specification -(visible only on this page) - -=== Message - -If possible try to display a specific message tailored to the issue. - -* Add a whitespace after `{{` in the template directive. -* Add a whitespace before `}}` in the template directive. -* Add a whitespace after `{{-` in the template directive. -* Add a whitespace before `}}-` in the template directive. - - -=== Highlighting - -* Highlight the template directive that does not have a whitespace after opening braces `{{`, `{{-` and/ or before closing braces `}}`, `-}}` -endif::env-github,rspecator-view[]