モジュールにパラメーターと出力を追加する

7 分

作成する各モジュールには明確な目的があります。モジュールを、コントラクトがあるものと見なすことができます。一連のパラメーターを受け取り、一連のリソースを作成します。また、親テンプレートに出力を返すこともあります。モジュールを使用するユーザーは、その動作について心配する必要はありません。期待した動作が行われます。

モジュールを計画するときは、次の点を考慮してください。

モジュールの目的を果たすために知る必要のある情報。
モジュールの利用者が提供する必要のある情報。
モジュールの利用者が出力としてアクセスする必要のある情報。

モジュールのパラメーター

モジュールが受け取るパラメーターについて検討します。また、各パラメーターをオプションにするか、それとも必須にするかを検討します。

テンプレートのパラメーターを作成するときには、可能な限り既定のパラメーターを追加することをお勧めします。独自の既定のパラメーターを使用する可能性がある親テンプレートによってモジュールが使用されるため、モジュールでは、既定のパラメーターを追加することが必ずしも重要というわけではありません。両方のファイルに同様のパラメーターがあり、その両方に既定値があると、テンプレートのユーザーにとって、どちらの既定値が適用されるのかを判断したり、一貫性を維持したりするのが難しくなります。たいていの場合、既定値を親テンプレートに残し、モジュールからは削除するのが賢明です。

また、リソースの SKU および他の重要な構成設定を制御するパラメーターの管理方法についても検討する必要があります。スタンドアロンの Bicep テンプレートを作成する場合は、テンプレートにビジネスルールを埋め込むのが一般的です。たとえば、"運用環境をデプロイする場合、ストレージアカウントで GRS 層を使う必要がある" などです。ただし、モジュールの使用には、いくつかの課題が伴うことがあります。

再利用可能で柔軟である必要があるモジュールを構築する場合は、親テンプレートごとにビジネスルールが異なる可能性があるため、一般的なモジュールにビジネスルールを埋め込むのはそれほど意味がない可能性があることに注意してください。親テンプレートでビジネスルールを定義してから、パラメーターを使用してモジュール構成を明示的に渡すことを検討してください。

一方、特定のニーズに合ったリソースを組織で簡単にデプロイできるようにするためにモジュールを作成する場合は、それにビジネスルールを組み込むことで、親テンプレートを簡略化することは合理的です。

モジュールにパラメーターを含める場合は、@description 属性を使用して、わかりやすい説明を追加してください。

@description('The name of the storage account to deploy.')
param storageAccountName string

使用条件

Bicep のようなコードを使ってインフラストラクチャをデプロイする際の目標の 1 つは、同じ作業を繰り返したり、同じまたは似た目的のテンプレートを複数作成したりしないで済むようにすることです。 Bicep の機能は、さまざまな状況に対応できる再利用可能なモジュールを作成するための強力なツールボックスとなります。モジュール、式、既定のパラメーター値、条件などの機能を組み合わせて、必要な柔軟性を備えた再利用可能なコードを構築できます。

たとえば、Azure Cosmos DB アカウントをデプロイするモジュールを作成するとします。運用環境にデプロイする場合は、ログが Log Analytics ワークスペースに送信されるようにアカウントを構成する必要があります。 Log Analytics に送信されるようにログを構成するには、diagnosticSettings リソースを定義します。

要件を満たすために、このリソース定義に条件を追加することができます。また、既定値を追加して、ワークスペース ID パラメーターを省略可能に設定することができます。

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

このモジュールを Bicep テンプレートに含めるときには、ワークスペース ID を設定することで、Azure Cosmos DB アカウントログが Log Analytics に送信されるように簡単に構成できます。また、デプロイする環境でログが不要な場合は、パラメーターを省略します。既定値が設定されています。このモジュールには、適切な処理を実行して要件を満たすのに必要なロジックがカプセル化されます。

ヒント

if ステートメントが true または false のどちらに評価されるシナリオでもテンプレートが有効であるか、テストしてください。

モジュールの出力

モジュールでは、出力を定義できます。親テンプレートで使用する必要がある情報を得るために、出力を作成することができます。たとえば、モジュールでストレージアカウントが定義されている場合に、親テンプレートでそれにアクセスできるよう、ストレージアカウントの名前の出力を作成することを検討します。

警告

シークレット値の出力は使用しないでください。出力は、デプロイ履歴の一部としてログに記録されるため、セキュリティで保護された値には適していません。代わりに、次のいずれかの方法を検討できます。

リソースの名前を提供する出力を使用します。次に、親テンプレートでその名前の existing リソースを作成し、セキュリティで保護された値を動的に検索します。
値を Azure Key Vault のシークレットに書き込みます。親テンプレートで、Vault にあるシークレットを必要なときに読み取らせます。

親テンプレートでは、変数にモジュール出力を使用したり、他のリソース定義のプロパティを使用したり、変数とプロパティを出力そのものとして公開したりできます。複数の Bicep ファイルにわたって出力を公開および使用すると、チームで共有し、複数のデプロイにわたって再利用することができる、一連の再利用可能な Bicep モジュールを作成できます。また、@description 属性を使用して、わかりやすい説明を出力に追加することをお勧めします。

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

ヒント

Bicep テンプレートによって作成される設定を保存および管理し、それにアクセスするために、専用サービスを使用することもできます。 Key Vault は、セキュリティで保護された値を保管するために設計されています。 Azure App Configuration は、他の (セキュリティで保護されていない) 値を保管するために設計されています。

モジュールをつなぎ合わせる

複数のモジュールを組み合わせた、親 Bicep ファイルを作成することがよくあります。たとえば、専用仮想ネットワークを使用する仮想マシンをデプロイするための、新しい Bicep テンプレートを構築するとします。仮想ネットワークを定義するモジュールを作成できます。次に、そのモジュールからの出力として仮想ネットワークのサブネットリソース ID を取得し、それを仮想マシンモジュールへの入力として使用することができます。

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

この例では、モジュール間の参照でシンボリック名を使用します。このリファレンスは、モジュール間の関係を Bicep で自動認識するために役立ちます。

Bicep で依存関係の存在が認識され、モジュールが順番にデプロイされます。

Bicep によって virtualNetwork モジュールの内容がすべてデプロイされます。
このデプロイが成功すると、Bicep で subnetResourceId 出力値にアクセスされ、それがパラメーターとして virtualMachine モジュールに渡されます。
Bicep によって virtualMachine モジュールの内容がすべてデプロイされます。

Note

あるモジュールへの依存がある場合、Bicep でそのモジュールのデプロイ全体が完了するまで待機します。モジュールを計画するときには、この点に留意する必要があります。デプロイに時間がかかるリソースを定義したモジュールを作成した場合、そのモジュール全体のデプロイが完了するまで、そのモジュールに依存する他のリソースは待機します。

モジュールにパラメーターと出力を追加する

モジュールのパラメーター

使用条件

モジュールの出力

モジュールをつなぎ合わせる

フィードバック