コメントとメタデータを追加してコードを文書化する

4 分

優れた Bicep コードは、"自己文書化" されています。これは、コードが分かりやすい名前付けと適切な構造を使用していて、同僚があなたのコードを読んだときに何が起こっているかをすぐに理解できることを意味します。変更を加える必要がある場合には、適切な場所を変更しているという確信を持つことができます。

しかし、状況によっては、Bicep ファイルに追加のドキュメントを追加して、特定のコードを明確にすることが必要になる場合があります。また、テンプレートがデプロイされ、Azure にリソースが作成された後は、Azure 環境にアクセスするすべてのユーザーが、各リソースがどのようなものであり、その目的は何であるかを理解できることが重要です。

このユニットでは、Bicep ファイルにコメントを追加する方法と、リソースタグを使用して Azure リソースにメタデータを追加する方法について説明します。この追加ドキュメントは、コードが行うこと、コードの記述に使用したロジック、Azure リソースの目的に関する知見を同僚に提供します。

コードにコメントを追加する

Bicep では、コードに "コメント" を追加できます。コメントは人が判読可能な、コードを文書化するテキストであり、ファイルが Azure にデプロイされるときには無視されます。

2 種類のコメントが Bicep でサポートされています。

単一行コメントは、次に示すように、2 つのスラッシュ (//) 文字で始まり、行の末尾まで続きます。

// We need to define a firewall rule to allow Azure services to access the database.

resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = {
  parent: sqlServer
  name: 'AllowAllAzureIPs'
  properties: {
    startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
    endIpAddress: '0.0.0.0'
  }
}

複数行コメントは、次に示すように、/* と */ の文字シーケンスを使用してコメントを囲み、複数の行にまたがることができます。
```
/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/
```

ヒント

コードのわかりきった明確な部分にコメントを使用することは避けてください。コメントが多すぎると、コードの読みやすさが低下します。また、将来、コードを変更したときにコメントを更新することを忘れがちです。固有のロジックと複雑な式の文書化に重点を置きます。

また、Bicep コメントを使用して、各ファイルの先頭に構造化された複数行ブロックを追加することもできます。それを "マニフェスト" と考えてください。チームは、各テンプレートとモジュールに、テンプレートの目的と内容を記述したマニフェストが必要と判断することがあります。たとえば次のようなものです。

/*
  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
*/

パラメーターファイルにコメントを追加する

パラメーターファイルを使用すると、デプロイ用のパラメーター値のセットを指定するための JSON ファイルを作成できます。パラメーター値は、Bicep テンプレートで宣言されているパラメーターと一致している必要があります。

パラメーターファイルで指定した値にも、多くの場合、文書化によるメリットがあります。ファイルを読むユーザーがすぐに理解できないようなパラメーター値を使用する場合は、パラメーターファイルにコメントを追加することをお勧めします。

たとえば、Web サイトの Bicep テンプレートに、会社の製品在庫 API にアクセスするための URL パラメーターが含まれている場合があります。これにより、倉庫におもちゃの在庫があるかどうかを Web サイトで表示できるようになります。各環境の在庫 API にアクセスするための URL はわかりにくいため、コメントの対象候補として適しています。

{
    "$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.
      }
    }
  }

ヒント

コメントを含むパラメーターファイルやその他の JSON ファイルを使用する場合は、通常、ファイル拡張子 .json ではなく .jsonc を使用する必要があります。これは、コメントが許可されていることが Visual Studio Code およびその他のツールで認識されるために役立ちます。

パラメーター、変数、出力に説明を追加する

パラメーター、変数、出力を作成するときに、@description() デコレーターを適用してその目的を説明できます。

@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

Bicep に Visual Studio Code 拡張機能を使用するとき、シンボリック名にカーソルを置くと説明が表示されるため、説明はコメントより影響力があります。また、Bicep ファイルをモジュールとして使用すると、パラメーターに適用する説明が表示されます。

リソースに説明を追加する

定義したリソースに説明を追加する場合にも役立ちます。また、@description() デコレーターをリソースに適用できます。

さらに、リソースによっては、人が判読できる説明やその他の情報をリソース自体に追加することがサポートされています。たとえば、多くの Azure Policy リソースと Azure ロールベースのアクセス制御 (RBAC) ロールの割り当てには、次のように、description プロパティが含まれます。

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  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.'
  }
}

このプロパティを使用して、各ロールの割り当てを作成した理由を説明することをお勧めします。説明はリソースのある Azure にデプロイされます。そのため、Azure 環境の RBAC 構成を監査する人は、ロール割り当ての目的をすぐに理解します。

リソースタグを適用する

Bicep ファイル内のコメントは、デプロイされたリソースのどこにも表示されません。 Bicep ファイルの文書化に役立つだけです。ただし、次のような、デプロイされた Azure リソースに関する情報を追跡する必要がある状況も多数あります。

特定のコストセンターに Azure のコストを割り当てる。
データベースおよびストレージアカウントに含まれるデータを分類して保護する方法を理解する。
リソースの管理を担当するチームまたは担当者の名前を記録する。
運用や開発など、リソースが関連付けられている環境の名前を追跡する。

リソース "タグ" を使用すると、リソースに関する重要なメタデータを保存できます。 Bicep コードでリソースタグを定義すると、デプロイ時に Azure でリソースと共にその情報が格納されます。

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

Azure PowerShell や Azure CLI などのツールを使用してリソースのタグに対してクエリを実行できます。すると Azure portal にタグが表示されます。

ストレージアカウントの Azure portal のスクリーンショット。タグの場所を示しています。

すべてのリソースに対して同じタグのセットを使用するのが一般的です。そのため、多くの場合、タグをパラメーターまたは変数として定義し、各リソースで再利用することをお勧めします。

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

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

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

コメントとメタデータを追加してコードを文書化する

コードにコメントを追加する

パラメーター ファイルにコメントを追加する

パラメーター、変数、出力に説明を追加する

リソースに説明を追加する

リソース タグを適用する

フィードバック

パラメーターファイルにコメントを追加する

リソースタグを適用する