Documentare il codice aggiungendo commenti e metadati delle risorse

• 4 minuti

Il codice Bicep è autodocumentato. Ciò significa che usa una denominazione chiara e una buona struttura in modo che, quando i colleghi leggono il codice, possano comprendere rapidamente cosa accade. Se devono apportare modifiche, possono farlo con la certezza di intervenire nei punti giusti.

In alcune situazioni, tuttavia, potrebbe essere necessario chiarire un determinato codice integrando una documentazione aggiuntiva nei file Bicep. Inoltre, dopo la distribuzione del modello e la creazione delle risorse in Azure, è importante che chiunque analizzi l'ambiente Azure comprenda la natura e lo scopo di ogni risorsa.

In questa unità verrà illustrato come aggiungere commenti ai file Bicep e come usare i tag delle risorse per aggiungere metadati alle risorse di Azure. Questa documentazione aggiuntiva offre ai colleghi informazioni dettagliate sulle operazioni del codice, sulla logica usata per scrivere il codice e sullo scopo delle risorse di Azure.

Aggiungere commenti al codice

Bicep consente di aggiungere commenti al codice. I commenti sono testo leggibile che documenta il codice, ma viene ignorato quando il file viene distribuito in Azure.

Bicep supporta due tipi di commenti:

• I commenti a riga singola iniziano con una sequenza di caratteri barra doppia (//) e continuano fino alla fine della riga, come illustrato di seguito:

  // We need to define a firewall rule to allow Azure services to access the database.
  
  resource firewallRule 'Microsoft.Sql/servers/firewallRules@2014-04-01' = {
    parent: sqlServer
    name: 'AllowAllAzureIPs'
    properties: {
      startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
      endIpAddress: '0.0.0.0'
    }
  }
  

• I commenti a più righe usano le sequenze di caratteri /* e */ per racchiudere il commento e possono estendersi su più righe, come illustrato di seguito:

  /*
    This Bicep file was developed by the web team.
    It deploys the resources we need for our toy company's website.
  */
  

È anche possibile usare i commenti di Bicep per aggiungere un blocco strutturato su più righe all'inizio di ogni file, che può essere considerato un manifesto. Il team potrebbe decidere che ogni modello e modulo debba avere un manifesto che descriva lo scopo e il contenuto del modello, come in questo esempio:

/*
  SYNOPSIS: Module for provisioning Azure SQL server and database.
  DESCRIPTION: This module provisions an Azure SQL server and a database, and configures the server to accept connections from within Azure.
  VERSION: 1.0.0
  OWNER TEAM: Website
*/

Aggiungere commenti ai file dei parametri

I file di parametri consentono di creare un file JSON per specificare un set di valori di parametro per la distribuzione. È necessario che i valori dei parametri corrispondano ai parametri dichiarati nel modello Bicep.

Spesso è utile documentare anche i valori specificati nei file dei parametri. È consigliabile aggiungere commenti ai file di parametri quando si lavora con valori di parametri che potrebbero non essere immediatamente chiari a chi legge il file.

Il modello Bicep del sito Web, ad esempio, potrebbe includere un parametro per l'URL di accesso all'API delle scorte di prodotti dell'azienda in modo che il sito Web possa visualizzare se i giocattoli sono disponibili in magazzino. Gli URL per accedere all'API delle scorte per ogni ambiente non sono facili da comprendere, quindi sono perfetti per un commento:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "productStockCheckApiUrl": {
        "value": "https://x73.mytoycompany.com/e4/j7" // This is the URL to the product stock API in the development environment.
      }
    }
  }

Aggiungere descrizioni ai parametri, alle variabili e agli output

Quando si crea un parametro, una variabile o un output, è possibile applicare l'elemento Decorator @description() per spiegarne lo scopo:

@description('The Azure region into which the resources should be deployed.')
param location string = resourceGroup().location

@description('Indicates whether the web application firewall policy should be enabled.')
var enableWafPolicy = (environmentType == 'prod')

@description('The default host name of the App Service app.')
output hostName string = app.properties.defaultHostName

Le descrizioni sono più potenti dei commenti perché, quando un utente usa l'estensione Visual Studio Code per Bicep, le descrizioni vengono visualizzate ogni volta che qualcuno passa il mouse su un nome simbolico. Inoltre, quando un utente usa il file Bicep come modulo, visualizza le descrizioni applicate ai parametri.

Aggiungere descrizioni alle risorse

Può anche essere utile aggiungere descrizioni alle risorse definite. È anche possibile applicare l'elemento Decorator @description() alle risorse.

Inoltre, alcune risorse supportano l'aggiunta di descrizioni o di altre informazioni leggibili nella risorsa stessa. Ad esempio, molte risorse di Criteri di Azure e le assegnazioni di ruolo del controllo degli accessi in base al ruolo di Azure includono una proprietà descrizione simile alla seguente:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2020-04-01-preview' = {
  scope: storageAccount
  name: guid(roleDefinitionId, resourceGroup().id)
  properties: {
    principalType: 'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
    description: 'Contributor access on the storage account is required to enable the application to create blob containers and upload blobs.'
  }
}

È consigliabile usare questa proprietà per spiegare perché è stata creata ogni assegnazione di ruolo. La descrizione viene distribuita in Azure con la risorsa, quindi chiunque controlla la configurazione degli accessi in base al ruolo dell'ambiente di Azure comprenderà immediatamente lo scopo dell'assegnazione di ruolo.

Applicare tag alle risorse

I commenti nel file Bicep non vengono visualizzati ovunque nelle risorse distribuite. Sono disponibili solo per poter documentare i file Bicep. In molte situazioni è tuttavia necessario tenere traccia delle informazioni sulle risorse di Azure distribuite, tra cui:

• Allocare i costi di Azure a centri di costo specifici.
• Comprendere come classificare e proteggere i dati contenuti nei database e negli account di archiviazione.
• Registrare il nome del team o della persona responsabile della gestione della risorsa.
• Tenere traccia del nome dell'ambiente a cui è correlata la risorsa, ad esempio produzione o sviluppo.

I tag delle risorse consentono di archiviare metadati importanti sulle risorse. Si definiscono i tag delle risorse nel codice Bicep e Azure archivia le informazioni con la risorsa quando viene distribuita:

resource storageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageAccountName
  location: location
  tags: {
    CostCenter: 'Marketing'
    DataClassification: 'Public'
    Owner: 'WebsiteTeam'
    Environment: 'Production'
  }
  sku: {
    name: storageAccountSkuName
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

È possibile eseguire una query sui tag di una risorsa usando strumenti come Azure PowerShell e l'interfaccia della riga di comando di Azure ed è possibile visualizzare i tag nel portale di Azure:

Poiché è normale usare lo stesso set di tag per tutte le risorse, spesso è consigliabile definire i tag come parametri o variabili e quindi riutilizzarli in ogni risorsa:

param tags object = {
  CostCenter: 'Marketing'
  DataClassification: 'Public'
  Owner: 'WebsiteTeam'
  Environment: 'Production'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  tags: tags
}

resource appServiceApp 'Microsoft.Web/sites@2020-06-01' = {
  tags: tags
}