Bicep に関するベストプラクティス

[アーティクル]
06/23/2023

この記事では、Bicep ファイルの開発時に従うべき手法を推奨します。これらの手法により、Bicep ファイルを簡単に理解して使用できるようになります。

トレーニングリソース

Bicepのベストプラクティスを段階的なガイダンスで学びたい方は、「コラボレーションのための Bicep コードの構築」を参照してください。

パラメーター

パラメーター宣言では、適切な名前付けを使用します。良い名前を付けると、テンプレートが読みやすく、理解しやすくなります。明確でわかりやすい名前を使用し、一貫性のある名前の付け方をしてください。
テンプレートが使用するパラメーターについては、慎重に検討してください。デプロイによって変わる設定には、パラメーターを使ってみてください。デプロイによって変わらない設定には、変数やハードコードされた値を使用できます。
使用する既定値には注意してください。既定値はすべてのユーザーが安全にデプロイできるものにします。たとえば、テスト環境にテンプレートを展開する人が不必要に大きなコストを負担しないように、低コストな価格レベルと SKU を使用することを検討します。
@allowed デコレーターの使用はできるだけ控えてください。このデコレーターを広く使用すると、有効なデプロイがブロックされる可能性があります。 Azure サービスによって SKU とサイズが追加されると、許可リストが最新の状態でなくなる可能性があります。たとえば、Premium v3 SKU だけを許可することは運用環境では意味がありますが、運用環境以外では同じテンプレートを使用できなくなります。
パラメーターの説明を提供することをお勧めします。役に立つ説明を記述するように心がけ、テンプレートでパラメーター値をどのように扱う必要があるかについて重要な情報があれば提供してください。

// コメントを使用して、Bicep ファイル内にメモを追加することもできます。
パラメーター宣言は、テンプレートファイルのどこにでも書くことができますが、通常は Bicep のコードを読みやすくするために、ファイルの先頭に書くのが良いでしょう。
名前付けを制御するパラメーターには最小と最大の文字数を指定することをお勧めします。これらの制限により、後でデプロイ中にエラーが発生するのを防ぐことができます。

Bicep パラメーターの詳細については、「Bicep のパラメーター」を参照してください。

変数

変数を定義する場合、データ型は不要です。変数は解決値から型を推論します。
Bicep 関数を使用すると、変数を作成できます。
Bicep ファイルに変数が定義された後で、変数の名前を使用して値を参照します。

Bicep 変数の詳細については、「Bicep の変数」を参照してください。

名前

名前にはローワーキャメルケース (最初の単語の先頭が小文字) を使用します (例: myVariableName または myResource)。
uniqueString() 関数は、一意のリソース名を作成する場合に便利です。同じパラメーターを指定すると、毎回同じ文字列が返されます。リソースグループ ID を渡すことは、同じリソースグループに対するどのデプロイでも文字列が同じであり、異なるリソースグループまたはサブスクリプションにデプロイする場合は文字列が異なることを意味します。
次の例のように、テンプレート式を使用してリソース名を作成することをお勧めします:
```
param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'
```
テンプレート式を使用してリソース名を作成すると、次のような利点があります:
- uniqueString() により生成される文字列は意味がありません。テンプレート式を使用して、プロジェクト名や環境名の短い記述子やランダムコンポーネントなどの意味のある情報を含む名前を作成し、名前を一意にする可能性を高めるのに役立ちます。
- uniqueString() 関数では、グローバルに一意の名前は保証されません。リソース名にテキストを追加すると、既存のリソース名を再利用する可能性が低くなります。
- uniqueString() 関数によって、数字で始まる文字列が作成される場合があります。一部の Azure リソース (ストレージアカウントなど) では、数字で始まる名前を使用することはできません。この要件により、文字列補間を使用してリソース名を作成することをお勧めします。一意の文字列にプレフィックスを追加できます。
- 多くの種類の Azure リソースで、使用できる文字と名前の長さのルールが決まっています。テンプレートにリソース名の作成を埋め込むと、そのテンプレートを使用するすべてのユーザーが、これらの規則自体に従うことを覚えている必要はありません。
シンボリック名に name を使用しないでください。シンボリック名はリソースの名前ではなくリソースを表します。たとえば、次の構文ではなく、
```
resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
```
次のコマンドを使用します。
```
resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
```
サフィックスを使用して変数とパラメーターを区別しないでください。

リソース定義

複雑な式をリソースプロパティに直接埋め込む代わりに、変数を使用して式を格納します。この方法により、Bicep ファイルが読みやすく、理解しやすくなります。ロジックを使用してリソース定義が煩雑にならないようにします。
リソースの動作について推測するのではなく、リソースのプロパティを出力として使用してみてください。たとえば、App Service アプリへの URL の出力が必要な場合は、URL の文字列を自分で作成するのではなく、アプリの defaultHostname プロパティを使用します。環境によっては、これらの前提条件が適切でない場合や、リソースの動作が変化する場合があります。リソースには独自のプロパティを指定する方が安全です。
リソースごとに最新の API バージョンを使用することをお勧めします。 Azure サービスの新機能は、新しい API バージョンでしか利用できない場合があります。
可能であれば、Bicep ファイルで reference と resourceId 関数を使用しないようにしてください。シンボリック名を使用して、Bicep 内の任意のリソースにアクセスできます。たとえば、シンボリック名 toyDesignDocumentsStorageAccount を使用してストレージアカウントを定義する場合は、式 toyDesignDocumentsStorageAccount.id を使用してそのリソース ID にアクセスできます。シンボリック名を使用することで、リソース間に暗黙的な依存関係が作成されます。
明示的な依存関係よりも暗黙的な依存関係を優先的に使用してください。 dependsOn リソースプロパティを使用すると、リソース間の明示的な依存関係を宣言できますが、通常であれば、他のリソースのシンボリック名を使用すればそのリソースを使用できます。このアプローチによって、2 つのリソース間に暗黙の依存関係が作成され、Bicep で関係自体を管理できるようになります。
リソースが Bicep ファイルにデプロイされていない場合でも、existing キーワードを使用してリソースへのシンボリック参照を取得することができます。

子リソース

入れ子の階層が深くなりすぎないようにしてください。入れ子の階層が深すぎると、Bicep コードが読みにくくなり、操作も難しくなります。
子リソースのリソース名を作成しなでください。 Bicep がリソース間の関係を理解する場合に提供される利点が失われます。代わりに parent プロパティまたは入れ子を使用します。

出力

機密データについては出力を作成しないでください。出力値には、デプロイ履歴にアクセスできる人なら誰でもアクセスできます。こういったものは、シークレットの処理には適していません。
出力を介してプロパティ値を渡すのではなく、既存のキーワードを使用して、既存のリソースのプロパティを検索します。キーについても、出力を介して渡す代わりに、このようにして他のリソースから検索することをお勧めします。常に最新のデータが得られます。

Bicep の出力の詳細については、「Bicep の出力」を参照してください。

テナントスコープ

テナントスコープでポリシーまたはロールの割り当てを作成することはできません。ただし、組織全体でアクセスを付与またはポリシーを適用する必要がある場合は、ルート管理グループにこれらのリソースをデプロイできます。

次のステップ

Bicep の概要については、Bicep のクイックスタートに関する記事を参照してください。
Bicep ファイルの構成要素については、「Bicep ファイルの構造と構文について」を参照してください。

Bicep に関するベスト プラクティス

トレーニング リソース