Skip to content

Use comments for each generated template resource#

Operational Excellence · All resources · Rule · 2021_12 · Awareness

Use descriptions for each resource in generated template(bicep, psarm, AzOps) to communicate purpose.

Description#

Generated templates can optionally include descriptions in resources. This helps other contributors understand the purpose of the resource.

Recommendation#

Specify descriptions for each resource in the template.

Examples#

Configure with Bicep#

To define Bicep template files that pass this rule:

  • Specify the @description() or @sys.description() decorator for each resource in the template.

For example:

Azure Bicep snippet
// An example container registry
@description('abc')
resource acr 'Microsoft.ContainerRegistry/registries@2021-06-01-preview' = {
  name: registryName
  location: location
  sku: {
    name: 'Premium'
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    adminUserEnabled: false
    policies: {
      quarantinePolicy: {
        status: 'enabled'
      }
      trustPolicy: {
        status: 'enabled'
        type: 'Notary'
      }
      retentionPolicy: {
        status: 'enabled'
        days: 30
      }
    }
  }
}

Comments