diff --git a/rules/S6956/azureresourcemanager/metadata.json b/rules/S6956/azureresourcemanager/metadata.json index 03d52650a68..15ae22b2aec 100644 --- a/rules/S6956/azureresourcemanager/metadata.json +++ b/rules/S6956/azureresourcemanager/metadata.json @@ -1,5 +1,5 @@ { - "title": "FIXME", + "title": "The properties and elements inside a template should appear in the recommended order", "type": "CODE_SMELL", "status": "ready", "remediation": { @@ -7,8 +7,9 @@ "constantCost": "5min" }, "tags": [ + "convention" ], - "defaultSeverity": "Major", + "defaultSeverity": "Minor", "ruleSpecification": "RSPEC-6956", "sqKey": "S6956", "scope": "All", @@ -16,9 +17,7 @@ "quickfix": "unknown", "code": { "impacts": { - "MAINTAINABILITY": "HIGH", - "RELIABILITY": "MEDIUM", - "SECURITY": "LOW" + "MAINTAINABILITY": "LOW" }, "attribute": "CONVENTIONAL" } diff --git a/rules/S6956/azureresourcemanager/rule.adoc b/rules/S6956/azureresourcemanager/rule.adoc index 4bd440f87a8..b7051b7e8b6 100644 --- a/rules/S6956/azureresourcemanager/rule.adoc +++ b/rules/S6956/azureresourcemanager/rule.adoc @@ -1,44 +1,151 @@ -FIXME: add a description +== Why is this an issue? -// If you want to factorize the description uncomment the following line and create the file. -//include::../description.adoc[] +According to the best practices defined by Azure, a consistent order of properties and elements in a templates is recommended. +This makes it easier to read and understand the template. -== Why is this an issue? +Not following this convention has no technical impact, +but will reduce the template's readability because most developers are used to the standard order. -FIXME: remove the unused optional headers (that are commented out) +Sorting the resources according to deployment order is recommended as well, as this will convey the intent of the orchestration. -//=== What is the potential impact? +== How to fix it in ARM Templates -== How to fix it -//== How to fix it in FRAMEWORK NAME +*Recommended order of the top-level template properties*: -=== Code examples +[source,json] +---- +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/...", + "contentVersion": "1.0.0.0", + "apiProfile": "...", + "parameters": {}, + "functions": {}, + "variables": {}, + "resources": [], + "outputs": {} +} +---- -==== Noncompliant code example +*Recommended order of the resource properties*: -[source,text,diff-id=1,diff-type=noncompliant] +[source,json] ---- -FIXME +{ + "resources": [ + { + "comments": "if any", + "condition": true, + "scope": "% parent scope %", + "type": "Microsoft.Compute/virtualMachines", + "apiVersion": "2023-09-01", + "name": "resourceName", + "location": "[parameters('location')]", + "zones": [], + "sku": {}, + "kind": "", + "scale": "", + "plan": {}, + "identity": {}, + "copy": { + "name": "vmLoop", + "count": "[parameters('numberOfVMs')]" + }, + "dependsOn": [ + "nicLoop" + ], + "tags": {}, + "properties": {} + } + ] +} ---- -==== Compliant solution +Any other properties or elements not listed here should be placed before the `properties` object for the resource. -[source,text,diff-id=1,diff-type=compliant] +== How to fix it in Bicep + +*Recommended order of the top-level template properties*: + +[source,bicep] ---- -FIXME +targetScope '...' +metadata '...' +param '...' +var '...' +resource // (existing resources collected together) +resource/module // (new resources) +output '...' ---- -//=== How does this work? +*Recommended order of the resource properties*: + +[source,bicep] +---- +@description +@batchSize +resource resourceName + parent + scope + name + location/extendedLocation + zones + sku + kind + scale + plan + identity + dependsOn + tags + properties +---- + +Any other decorated not listed here should be placed before the `resource` object and after the other decorators. +Any other properties or elements not listed here should be placed before the `properties` object for the resource. + +== Resources +=== Documentation + +* Azure quickstart templates best practices - https://github.com/Azure/azure-quickstart-templates/blob/master/1-CONTRIBUTION-GUIDE/best-practices.md#sort-order-of-properties[Sort order of properties] +* Microsoft Azure - Understand the structure and syntax of ARM templates - https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax#template-format[Template Format] +* Microsoft Azure - Understand the structure and syntax of Bicep files - https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax#template-format[Bicep Format] + +ifdef::env-github,rspecator-view[] + +''' +== Implementation Specification +(visible only on this page) + +=== Message + +In case of wrong order of top-level elements: + +* Primary Issue Message: Reorder the properties and elements to match the recommended order. +This `` object should be located after the `` object. +* Secondary Issue Message: This `` object should be located after the `` object. + +In case of wrong order in a resource: + +* Primary Issue Message: Reorder the properties and elements inside the resource to match the recommended order. +This `` object should be located after the `` object. +* Secondary Issue Message: This `` object should be located after the `` object. + + + +=== Highlighting + +In general, we want to highlight all the keys of elements that are in the wrong order. + +For wrong order in top-level elements: + +* The first wrongly ordered element should be highlighted as primary issue and the others as secondary locations. -//=== Pitfalls +For wrong order in a resource: -//=== Going the extra mile +* The name of the resource / key of the resource should be highlighted as a primary issues. +All the wrongly ordered elements should be highlighted as secondary locations. +''' +== Comments And Links +(visible only on this page) -//== Resources -//=== Documentation -//=== Articles & blog posts -//=== Conference presentations -//=== Standards -//=== External coding guidelines -//=== Benchmarks +endif::env-github,rspecator-view[] diff --git a/rules/S6956/metadata.json b/rules/S6956/metadata.json index 2c63c085104..0db3279e44b 100644 --- a/rules/S6956/metadata.json +++ b/rules/S6956/metadata.json @@ -1,2 +1,3 @@ { + }