SE の雑記

SQL Server の情報をメインに Microsoft 製品の勉強内容を日々投稿

Bicep の Tips (2024/07 版)

leave a comment

直近で Bicep を使用する機会があったのですが、その際に得られた知見についてまとめておきたいと思います。

Bicep と書いていますが、ARM でも共通する内容となるかと思います。

2024/07/29 追記

本投稿について X でコメントをいただいていたので、そちらを追記させていただきました。

 

ドキュメント / 学習用コンテンツ

Bicep のドキュメント

Bicep を使用する際には、次のドキュメントが公式のドキュメントとなり、最初にこのドキュメントを確認することになります。

ベストプラクティスについても、次のドキュメントで公開されていますので、このドキュメントにも目を通しておくとよいのではないでしょうか。

 

リソースの定義

Bicep で展開可能なリソースや、Bicep のフォーマットについては次のドキュメントから確認することができます。

 

リソース名

Bicep で展開するリソースの命名規則については次のドキュメントが参考にする機会が多いのではないでしょうか。

実際には、要件に応じてこの命名規則に当てはまらないこともあるかと思います。
リソース名についてはプロパティに直接指定するのではなくパラメーター化しておくことで後で変更も容易となりますので、最初はこの命名規則を参考にして作成を進めておき、命名規則が固まった段階でパラメーターを変更するのでもよいかと思います。

 

ラーニングパス

Bicep のラーニングパスも提供がされており、体系的な学習をする場合はこのコンテンツが役に立ちます。

Bicep に関する Learn モジュール で情報がまとめられていますが、次のようなラーニングパスが公開されています。

 

GitHub のリポジトリ

Bicep は GitHub で https://github.com/Azure/bicep でリポジトリが公開されています。

何か問題が発生した場合は、このリポジトリで事例が無いかの確認 / フィードバックを実施することで問題の解決につながる可能性があります。

 

サンプル

Bicep は Microsoft からサンプルの公開が行われており、作成する際にはこのサンプルが参考となります。

Bicep のドキュメントツリー内に次のようなサンプルが公開されており、このツリーからサンプルを確認することができます。

前述の リソースの定義 でもサンプルが記載されていますのでこのドキュメントからも確認することができます。

GitHub でも次のリポジトリでサンプルが公開されており、ここで公開されているファイルも参考となります。

 

開発ツール

Bicep の作成は、Visual Sutidio / Visual Studio Code を使用することができますが、Visual Studio Code のほうが手軽に使用することができるのではないでしょうか。

開発ツールを使わずに Bicep を作成するということは困難極まりないので、開発ツールが使えない状態で Bicep を作成するという話になった段階で Bicep の使用はあきらめたほうが良いかと思います。

Visual Studio Code であれば、次のドキュメントを参照することで環境を整えることができます。

以降の内容は Visual Studio Code を対象として記載しています。

 

Visual Studio Code の Bicep 拡張機能

Visual Studio Code の Bicep 拡張機能では、様々な機能が提供されています。

bicep / bicepparam ファイルを右クリックすると次のようなメニューが表示されますので使用可能な機能はここからも確認することができます。

image

現状 Experimental 機能となっていますが、Deployment Pane の機能は良く使用しています。

この機能を使用すると Bicep の展開だけでなく、検証や What-If の実行についても GUI で実行することができ、結果もフォーマットされた状態で確認することができます。

image

エラーが発生した場合、Visual Studio Code の出力結果だけでなく、次の画像のような Azure Portal のデプロイから情報の参照が必要となるケースもありますが、Visual Studio Code 上で成形された形で Bicep の展開状況が確認できるのは便利かと思います。

image

 

リソース スニペットによる入力支援

Visual Studio Code で導入する Bicep 拡張機能では、定義済みのリソース スニペットが提供されており、いくつかのリソースについてはスニペットから選択するだけでテンプレートとなる Bicep を使用することができます。

image

提供されている定義済みのリソーススニペットについては、SnippetTemplates がベースの定義となっていますので、どのようなスニペットが公開されているかは、ここから確認することができます。

リソーススニペットで生成される定義については、使用している API バージョンが低いものが指定されているケースがありますので、最新の API を使用する必要がある場合などはスニペットで作成された Bicep に対して API バージョンの手動変更が必要なこともあります。

 

GitHub Copilot の利用

GitHub Copilot を使用することで Bicep を作成する際の生産性が向上します。

チャットでの利用でもよいかとは思いますが、私は「Ctrl+i」でインラインでしていることが多いです。

次のように作成したいリソースの作成を GitHub Copilot に質問すると、ベースとなる Bicep を自動的に生成してくれます。

image

直接質問する以外にも、入力補完により作成を支援してくれますので、作成する際にはこの機能も役立ちます。

image

存在していない設定を提案してくることも稀にありますが、一般的なリソースを作成するのであれば問題ないように思えました。

 

What-If による変更のレビューを行う場合の考慮点

Bicep では What-If 操作により、現状のリソースの状態に対して Bicep ファイルの展開の影響についての、変更のレビューを行うことができます。

これは、コマンドや上述の Visual Studio Code の拡張機能から行うことができるのですが What-If 操作による比較を行うことを想定している場合には事前に考慮が必要となります。

例としては次のような Bicep の展開を行ってみます。

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'st${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource blob 'Microsoft.Storage/storageAccounts/blobServices@2023-04-01' = {
  name: 'default'
  parent: storage
}

 

ストレージアカウントと BLOB を指定したシンプルなものですが、この Bicep ファイルを展開した後に、リソースの設定は変更せずに What-If を実行すると差分が検知されます。

image

image

Bicep ファイルには明示的に指定していませんが、展開されたリソースでは自動的に設定されている項目については、What-If で差分として検知されてしまうケースがあります。

Azure ストレージの ストレージ保持 は ライフサイクル管理ポリシー に移行されているため、現在は指定する必要は無くなっているのですが、展開されたリソースではデフォルト値が指定されており、それが差分として認識されています。

そのため What-If で差分が出ないようにするためには、blobServices の定義を次のようにする必要があります。

resource blob 'Microsoft.Storage/storageAccounts/blobServices@2023-04-01' = {
  name: 'default'
  parent: storage
  properties: {
    deleteRetentionPolicy:{
      allowPermanentDelete: false
      days: 7
      enabled: true
    }
    containerDeleteRetentionPolicy: {
      days: 7
      enabled: true
    }
  }
}

 

この Bicep ファイルを使用した場合は What-If により変更なしとして認識されます。

image

What-If は便利な機能ではあるのですが、完全に変更は無しとして認識されるようにするためには、Bicep ファイルに明示的に定義をしておかないと差分が認識されてしまうことがあります。

What-If を通常の運用で定期的に実行する予定があるのであれば、最初から差分を認識されない Bicep ファイルを記載しておく必要があります。

 

Azure Portal を活用した Bicep の作成支援

Bicep を作成する際、作成済みのリソースや、Azure Portal で実施した操作を参考にして、Bicep を作成したいケースがあります。その際には次のような機能 / 操作を活用することができます。

Bicep ではなく、ARM テンプレートを表示する機能となりますが、ARM テンプレートの内容は Bicep を作成する際にも参考となります。

 

ARM テンプレートを Bicep に変換

ARM テンプレートを Bicep に変換する機能が提供されています。

変換の精度が高いかは微妙な気もしており、変換をするのであれば、Bicep を最初から記載したほうが速いケースのほうが多いケースがあります。

既存の ARM テンプレートが存在している場合や後述の ARM テンプレートを確認するための機能で確認したテンプレートを直接変換するということもできます。

 

Azure Portal でリソースを作成する際にARM テンプレート表示を使用

Azure Portal でリソースを作成する際に、作成の直前で次のようなテンプレートを表示するリンク (以下の画像であれば「オートメーション テンプレートの表示」) が提供されていることがあります。

image

この機能を使用すると、作成しようとしているリソースの ARM テンプレートを確認できますので、その内容を Bicep の設定に活用することができます。

 

リソースグループのデプロイから ARM テンプレートを表示

Azure Portal から展開したリソースはリソースグループの「デプロイ」からテンプレートを表示することができます。

image

リソース展開後に変更する設定については、確認することはできませんが、リソースの作成についてはこの内容から確認することができます。

 

テンプレートのエクスポートを利用

リソースによっては、テンプレートのエクスポートを行うことができます。

image

すべての設定がエクスポートできるわけではありませんが、この機能を使用して ARM テンプレートを表示してエクスポートすることができます。エクスポートした ARM テンプレートを前述に記載した変換を使用して Bicep に変換するということも可能です。

Azure Data Factory のようなリソースについては、ARM テンプレートのエクスポートが Studio の内部に含まれていることもあります。

image

 

Azure リソースエクスプローラーを利用

ARM テンプレートはリソースエクスプローラーを使用して表示することもできます。

image

ここから確認したいリソースの情報を確認することもできます。

 

ブラウザの開発者ツールを使用する

設定項目については、ブラウザの開発者ツールを使用した状態で、確認したい設定を開くことで、レスポンスから設定内容を確認することができます。

image

設定した内容を Bicep のテンプレートで表現するにはどのようにすればよいかについては、この内容を参考にすることができます。

 

Bicep で指定できない設定

リソースの作成は Bicep で実施できるが、リソースの一部の設定が Bicep で操作できないというケースがあります。(私が確認できた範囲では「ストレージアカウントの静的な Web サイトの有効化」「Key Vault の証明書の操作」といった内容がありました)

このような設定を Bicep で操作する際には、デプロイスクリプトの利用を検討する必要があります。

Bicep では操作できないが、Azure PowerShell / Az CLI であれば操作できるというような設定についてはデプロイ スクリプトを使用することで対応できるケースがあります。

デプロイ スクリプトは Azure Container Instance (ACI) が起動され実行されています。

現状、ACI は 信頼された Azure サービス に含まれていないため、セキュリティで保護されたネットワークからのみアクセスが許可された Azure リソースに対してデプロイ スクリプトにより操作を行う場合には、一時的にネットワークセキュリティの緩和が必要となるケースがありますので、デプロイ スクリプトでアクセス可能なリソースについては注意しておく必要があります。

 

外部ファイル等の利用

ファイル関数の利用

Bicep のファイル関数 を使用することで、外部ファイルの内容を Bicep 内でオブジェクトとして使用することができますので、bicepparam 以外のフォーマットのファイルをパラメーター等として使用するということも可能です。

  • 例: 一部の設定は YAML で定義しておき、YAML の知識があれば操作できるようにしておきたいのであれば、loadYamlContent で YAML ファイルを読み込み Bicep のパラメーターとして使用することもできます。

 

パラメーター ファイル関数 / リソース関数の利用

Bicep では、Key Vault や環境変数から値を取得する方法がパラメーター ファイル関数 / リソース関数として提供されています。

機密性の高い情報についてはこれらの関数の利用を検討してもよいかもしれません。

 

プライベート レジストリの利用

モジュールの再利用をする際には、Azure Container Registry を使用したプライベートレジストリの利用を検討してもよいかもしれません。

横断的にモジュールを使用することは中々難しいかもしれませんが、タグでモジュールを管理することもできますので、Bicep を更新し名がら使い続ける際にも便利なのではないでしょうか。

 

リファクタリングの必要性の検討

Bicep で複数のリソース作成 / モジュール化を進めていると次のような内容の見直しを行ったほうが効率的なことがあります。

  • 変数 / パラメーター名の命名ルールの統一化
  • 設定を共通化することによる再利用や可読性の向上
    • 設定内容は、array や object の変数 / パラメーターを指定することもできますので、共通する設定を変数化しておくことで共通化することができます。
  • パラメーター / 出力 (output) の array / object 化
    • 最初は、string を使用して単一設定でパラメーターの受け取り / 出力を行っていたが、後述のリソースの作成で必要となるパラメーターが多くなったため、複数の設定を一つのパラメーターでやり取りしたほうが効率的となるケースがあります。
  • for / foreach / if の活用によるリソース展開の共通化
    • 同一の種類で複数のリソースを作成する際に、個別にリソース作成をしていたが、for / foreach / if を使用したことで共通化できるケースがあります。
  • パラメーター ファイル (bicepparam) への切り出し
    • Bicep はパラメーター ファイル をサポートしていますのでユーザーが変更する可能性のある項目についてはパラメーターファイルへ切りだしておくと再利用性が向上しま
  • コメントの補強
    • Bicep はファイル内にコメントを記載しておけるのも ARM テンプレートと比較してメリットの一つとなっていますので、設定の意図についてはコメントを残しておいたほうが良いです。
    • 特にデプロイスクリプトを利用する場合は、なぜ Bicep の定義ではなくデプロイスクリプトで実装したのかはノウハウの一つとなりますのでコメントは充実させておいたほうが良いかと。
  • べき等性をもって実行されているか
    • Bicep は反復可能結果をもってべき等である実行が行われることが 利点 の一つとして上げられています。
    • そのため、実行は 1 回ではなく複数回実行してエラーが発生しないことを確認しておくのも重要となります。

 

ある程度 Bicep の作成が進んできたら、リファクタリングができるかどうかを一度確認したほうが良いのではと思っています。

Share

Written by Masayuki.Ozawa

7月 27th, 2024 at 11:23 pm

Posted in Azure,Bicep

Tagged with ,

«
»

Leave a Reply