Merge pull request #184402 from StephenWeatherford/sw/location-linter-rules

new location-related linter rules

Author: hmacgregor1

articles/azure-resource-manager/bicep/linter-rule-explicit-values-for-loc-params.md

@@ -0,0 +1,85 @@
+---
+title: Linter rule - use explicit values for module location parameters
+description: Linter rule - use explicit values for module location parameters
+ms.topic: conceptual
+ms.date: 1/6/2022
+---
+
+# Linter rule - use explicit values for module location parameters
+
+This rule finds module parameters that are used for resource locations and may inadvertently default to an unexpected value.
+
+## Linter rule code
+
+Use the following value in the [Bicep configuration file](bicep-config-linter.md) to customize rule settings:
+
+`explicit-values-for-loc-params`
+
+## Solution
+
+When you consume a module, any location-related parameters that have a default value should be assigned an explicit value. Location-related parameters include parameters that have a default value referencing `resourceGroup().location` or `deployment().location` and also any parameter that is referenced from a resource's location property.
+
+A parameter that defaults to a resource group's or deployment's location is convenient when a bicep file is used as a main deployment template. However, when such a default value is used in a module, it may cause unexpected behavior if the main template's resources aren't located in the same region as the resource group.
+
+### Examples
+
+The following example fails this test. Module `m1`'s parameter `location` isn't assigned an explicit value, so it will default to `resourceGroup().location`, as specified in *module1.bicep*. But using the resource group location may not be the intended behavior, since other resources in *main.bicep* might be created in a different location than the resource group's location.
+
+*main.bicep*:
+```bicep
+param location string = 'eastus'
+
+module m1 'module1.bicep' = {
+ name: 'm1'
+}
+
+resource storageaccount 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+  name: 'storageaccount'
+  location: location
+  kind: 'StorageV2'
+  sku: {
+    name: 'Standard_LRS'
+  }
+}
+```
+
+*module1.bicep*:
+```bicep
+param location string = resourceGroup().location
+    
+resource stg 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+  name: 'stg'
+  location: location
+  kind: 'StorageV2'
+  sku: {
+    name: 'Premium_LRS'
+  }
+}
+```
+
+You can fix the failure by explicitly passing in a value for the module's `location` property:
+
+*main.bicep*:
+```bicep
+param location string = 'eastus'
+
+module m1 'module1.bicep' = {
+  name: 'm1'
+  params: {
+   location: location // An explicit value will override the default value specified in module1.bicep
+  }
+}
+ 
+resource storageaccount 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+  name: 'storageaccount'
+  location: location
+  kind: 'StorageV2'
+  sku: {
+    name: 'Standard_LRS'
+  }
+}
+```
+
+## Next steps
+
+For more information about the linter, see [Use Bicep linter](./linter.md).

articles/azure-resource-manager/bicep/linter-rule-no-hardcoded-location.md

@@ -0,0 +1,95 @@
+---
+title: Linter rule - no hard-coded locations
+description: Linter rule - no hard-coded locations
+ms.topic: conceptual
+ms.date: 1/6/2022
+---
+
+# Linter rule - no hard-coded locations
+
+This rule finds uses of Azure location values that aren't parameterized.
+
+## Linter rule code
+
+Use the following value in the [Bicep configuration file](bicep-config-linter.md) to customize rule settings:
+
+`no-hardcoded-location`
+
+## Solution
+
+Template users may have limited access to regions where they can create resources. A hard-coded resource location might block users from creating a resource, thus preventing them from using the template. By providing a location parameter that defaults to the resource group location, users can use the default value when convenient but also specify a different location.
+
+Rather than using a hard-coded string or variable value, use a parameter, the string 'global', or an expression (but not `resourceGroup().location` or `deployment().location`, see [no-loc-expr-outside-params](./linter-rule-no-loc-expr-outside-params.md)). Best practice suggests that to set your resources' locations, your template should have a string parameter named `location`. This parameter may default to the resource group or deployment location (`resourceGroup().location` or `deployment().location`).
+
+The following example fails this test because the resource's `location` property uses a string literal:
+
+```bicep
+  resource stg 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+      location: 'westus'
+  }
+```
+You can fix it by creating a new `location` string parameter (which may optionally have a default value - resourceGroup().location is frequently used as a default):
+
+```bicep
+  param location string = resourceGroup().location
+  resource stg 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+      location: location
+  }
+```
+
+The following example fails this test because the resource's `location` property uses a variable with a string literal.
+
+```bicep
+  var location = 'westus'
+  resource stg 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+      location: location
+  }
+```
+
+You can fix it by turning the variable into a parameter:
+
+```bicep
+  param location string = 'westus'
+  resource stg 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+      location: location
+  }
+```
+
+The following example fails this test because a string literal is being passed in to a module parameter that is in turn used for a resource's `location` property:
+
+```bicep
+module m1 'module1.bicep' = {
+  name: 'module1'
+  params: {
+    location: 'westus'    
+  }
+}
+```
+where module1.bicep is:
+```bicep
+param location string
+
+resource storageaccount 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+  name: 'storageaccount'
+  location: location
+  kind: 'StorageV2'
+  sku: {
+    name: 'Premium_LRS'
+  }
+}
+```
+
+You can fix the failure by creating a new parameter for the value:
+```bicep
+param location string // optionally with a default value
+module m1 'module1.bicep' = {
+  name: 'module1'
+  params: {
+    location: location
+  }
+}
+```
+
+## Next steps
+
+For more information about the linter, see [Use Bicep linter](./linter.md).

articles/azure-resource-manager/bicep/linter-rule-no-loc-expr-outside-params.md

@@ -0,0 +1,56 @@
+---
+title: Linter rule - no location expressions outside of parameter default values
+description: Linter rule - no location expressions outside of parameter default values
+ms.topic: conceptual
+ms.date: 1/6/2022
+---
+
+# Linter rule - no location expressions outside of parameter default values
+
+This rule finds `resourceGroup().location` or `deployment().location` used outside of a parameter default value.
+
+## Linter rule code
+
+Use the following value in the [Bicep configuration file](bicep-config-linter.md) to customize rule settings:
+
+`no-loc-expr-outside-params`
+
+## Solution
+
+`resourceGroup().location` and `deployment().location` should only be used as the default value of a parameter.
+
+Template users may have limited access to regions where they can create resources. The expressions `resourceGroup().location` or `deployment().location` could block users if the resource group or deployment was created in a region the user can't access, thus preventing them from using the template.
+
+Best practice suggests that to set your resources' locations, your template should have a string parameter named `location`. If you default the `location` parameter to `resourceGroup().location` or `deployment().location` instead of using these functions elsewhere in the template, users of the template can use the default value when convenient but also specify a different location when needed.
+
+```bicep
+resource storageaccount 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+  location: resourceGroup().location
+}
+```
+
+You can fix the failure by creating a `location` property that defaults to `resourceGroup().location` and use this new parameter instead:
+
+```bicep
+param location string = resourceGroup().location
+
+resource storageaccount 'Microsoft.Storage/storageAccounts@2021-02-01' = {
+  location: location
+}
+```
+
+The following example fails this test because `location` is using `resourceGroup().location` but isn't a parameter:
+
+```bicep
+  var location = resourceGroup().location
+```
+
+You can fix the failure by turning the variable into a parameter:
+
+```bicep
+  param location string  = resourceGroup().location
+```
+
+## Next steps
+
+For more information about the linter, see [Use Bicep linter](./linter.md).

articles/azure-resource-manager/bicep/toc.yml

@@ -182,6 +182,10 @@
         href: linter-rule-max-variables.md
       - name: No hardcoded environment URLs
         href: linter-rule-no-hardcoded-environment-urls.md
+      - name: No hard-coded locations
+        href: linter-rule-no-hardcoded-location.md
+      - name: No location expressions outside of parameter default values
+        href: linter-rule-no-loc-expr-outside-params.md
       - name: No unnecessary dependsOn entries
         href: linter-rule-no-unnecessary-dependson.md
       - name: No unused parameters
@@ -196,6 +200,8 @@
         href: linter-rule-secure-parameter-default.md
       - name: Simplify interpolation
         href: linter-rule-simplify-interpolation.md
+      - name: Use explicit values for module location parameters
+        href: linter-rule-explicit-values-for-loc-params.md
       - name: Use protectedSettings for commandToExecute secrets
         href: linter-rule-use-protectedsettings-for-commandtoexecute-secrets.md
       - name: Use stable VM image