Azure Bicepとは？インストールからbicep build・デプロイまでの実務手順

Bicepは、Azureのリソースを宣言的に記述してデプロイするためのIaC（Infrastructure as Code）言語です。英語の biceps が上腕二頭筋を指すため検索結果には筋トレ関連が混ざります。混同は日本語ドキュメントの中でも起きていて、Microsoft Learn日本語版の「Bicep とは」ページは機械翻訳（ms.translationtype: MT）のため、コード例のタブ見出しが「二頭筋」と訳されたまま公開されています（2026年8月2日時点）。この記事で扱うのは筋肉ではなく、Azure向けのほうです。インストール時につまずきやすい仕様、bicep buildとパラメーターファイルの版要件、既存リソースのコード化、モジュール運用までを公式ドキュメントとリリース情報にあたって整理します。

まとめ：Azure Bicep導入で先に押さえる要点

結論から並べます。Bicep CLIの最新版は v0.46.1（2026年7月30日公開）で、ほぼ毎月更新されています。Azure CLIを使うなら明示的なインストールは不要です。ただし自動で入るインスタンスはPATHに追加されないため、コマンドはaz bicep versionの形で叩きます。

デプロイ時にbicep buildを手動実行する必要もありません。パラメーターを外出しする.bicepparamにはBicep CLI 0.18.4以降・Azure CLI 2.47.0以降という版要件があります。既存リソースのコード化はaz group exportとbicep decompileの組み合わせで、変換結果は手直し前提です。モジュールは自作より先にAzure Verified Modules（AVM）の公開レジストリを見てください。以下、手順と落とし穴を順に説明します。

Bicepの位置づけと、ARMテンプレート・Terraformとの関係

BicepはAzure Resource Manager（ARM）テンプレートのJSONに代わる記述言語です。書いたコードはARM JSONへトランスパイルされ、ARMに送られてデプロイされます。ランタイムはARMのままなので、Bicepを導入しても既存のARMテンプレート資産はそのまま動きます。公式FAQの説明は「Bicep は、新しい言語ではなく、既存の Azure Resource Manager テンプレート (ARM テンプレート) 言語のリビジョンと考えることができます」です。

最小構成のBicepファイルと、状態ファイルを持たない設計

Bicepのファイルは、パラメーター宣言とリソース宣言の組み合わせで書きます。公式ドキュメントが挙げるストレージアカウントの最小例が、そのまま構文の全体像になります。

param location string = resourceGroup().location
param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

リソース型とAPIバージョンを@で連結し、シンボリック名（この例ではstorageAccount）で他の宣言から参照します。JSONのような角かっこ式は登場しません。実務上の利点は2点です。ひとつは状態ファイル（state）を持たないこと。状態はAzure側が保持するため、tfstate相当のファイルを共有・ロックする運用が要りません。もうひとつはDay 0対応で、プレビュー段階のリソースでもARMが受け付けるならBicepから宣言できます。

費用はかかりません。Microsoft Learnの概要ページに「Bicep は無料であるため、Premium 機能の料金は発生しません」と記載され、GitHubリポジトリのREADMEも「100% free to use」としています。Microsoftのサポート対象になったのはバージョン0.3以降です。ARM JSONとの設計思想の違いや可読性の比較はARMテンプレートとBicep DSLの関係性と設計思想の違いで詳しく扱っているため、本記事では実装手順に集中します。

Terraformからの乗り換えを検討すべきでない条件

ここは立場を明確にします。すでにTerraformでAzureを運用しているなら、Bicepへ移行する理由は基本的にありません。Microsoft自身がFAQで「Terraform を使い慣れている場合は、切り替える理由はありません」と書いています。AWSやGoogle Cloudも同じコードベースで管理したい場合はなおさらで、公式FAQは「現時点では、Azure を超えて Bicep を拡張する予定はありません」としています。Terraform側の基盤の選択肢はHCP Terraformとは？旧Terraform Cloud（名称変更）の機能・料金とHCPでの位置づけを解説にまとめました。逆に、Azureだけを対象にしてARM JSONに苦しんでいるなら、Bicepは素直な選択肢になります。

Bicep CLIのインストール経路と、版を固定する方法

用途別に決まるインストール経路（VS Code・Azure CLI・手動）

公式ドキュメントは、作業内容ごとに推奨経路を分けています。Bicepファイルを書くならVS CodeとBicep拡張機能で、この場合Bicep CLIは拡張機能が自動で用意します。デプロイまで行うならAzure CLIが自動、Azure PowerShellは手動インストールです。拡張機能を入れると.bicepファイルを開いたときに右下の言語モードがBicepへ変わり、リソースのオートコンプリートと型検証が効きます。この型検証がARM JSON手書きとの体感差の中心なので、CLIだけ入れて終わりにしないでください。

Azure CLI同梱の自動インストールとPATHに入らない仕様

Azure CLIを使う場合、必要なものは揃っています。Azure CLI 2.20.0以降がインストールされていれば、Bicepを必要とするコマンドの実行時にBicep CLIが自動で導入されます。明示的に入れるなら次のコマンドです。

az bicep install
az bicep version

注意点はここです。Azure CLIがインストールするのはBicep CLIの自己完結型インスタンスで、公式ドキュメントは「Azure CLI は、Bicep CLI を PATH に追加しません」と明記しています。手動インストール版と競合しない設計である一方、シェルでbicep --versionを叩いても見つからないという結果になります。Azure CLI経由で入れたなら、コマンドは常にaz bicep ...の形で実行してください。

手動インストールが必須になるケースとOS別の手順

Azure PowerShellでデプロイする場合は自動インストールが効きません。公式ドキュメントは「Azure CLI によってインストールされた Bicep CLI の自己完結型インスタンスは、PowerShell コマンドでは使用できません。Bicep CLI を手動でインストールしていない場合、Azure PowerShell のデプロイは失敗します」と警告しています。Azure PowerShell自体も5.6.0以降が要ります。Windowsならパッケージマネージャーが手早く済みます。

winget install -e --id Microsoft.Bicep
choco install bicep

macOSはHomebrewのbrew tap azure/bicepとbrew install bicep、Linuxはbicep-linux-x64バイナリをPATHの通った場所へ配置します。Alpineのような軽量ディストリビューションではbicep-linux-musl-x64を選びます。macOSのGatekeeper例外は0.16.X以降のリリース版では不要です。なお、Rosetta 2やQEMUなどのエミュレーション環境での安定性は保証されないと公式に注記されています。ARM64のマシンではネイティブビルドを選んでください。

特定バージョンの固定とエアギャップ環境への配置

CIで毎回最新版が降ってくると、リンタールールの追加で警告が増え、ビルドログの差分が読みにくくなります。実際、v0.46.1では未使用の型宣言を指摘するno-unused-typesルールが追加されました。既定は警告レベルなのでビルドは通りますが、リンタールールをエラーへ引き上げている環境では失敗に変わります。版を固定するなら、利用可能なバージョンを一覧してから指定してインストールします。

az bicep list-versions
az bicep install --version v0.46.1
az bicep install --target-platform osx-arm64
az bicep upgrade

Apple SiliconやARM64のLinuxでプラットフォーム検出がうまく働かない場合は、--target-platformで明示します。指定できる値はlinux-arm64、linux-musl-x64、linux-x64、osx-arm64、osx-x64、win-arm64、win-x64です。

外部ネットワークに出られないエアギャップ環境ではbicep installとbicep upgradeが動きません。リリースページから取得したバイナリを、Azure CLIが管理する$HOME/.azure/bin（Windowsは%UserProfile%/.azure/bin）へbicepという名前で置きます。この環境でAzure PipelinesのAzure CLIタスクを使うなら、タスクのuseGlobalConfigをtrueにしてください（既定値はfalse）。

bicep buildの使いどころとパラメーターファイルの版要件

手動ビルドが要る場面と出力先の指定

デプロイのたびにbicep buildを実行する必要はありません。デプロイコマンドが内部で変換を行います。手動で走らせるのは、生成されるARM JSONを確認したいときや、JSONを成果物としてリポジトリに残す運用をしているときです。

bicep build main.bicep
bicep build main.bicep --outfile dist/azuredeploy.json
bicep build main.bicep --stdout

ユーザー定義型・ユーザー定義関数・コンパイル時インポート・実験的機能のいずれかを使うと、言語バージョン2.0のコード生成が自動で有効になります。生成されたJSONを別ツールで扱っている場合は、この切り替わりが差分として現れる点に注意してください。外部レジストリのモジュールを参照しているとbuildは自動でrestoreを呼びます。オフラインで走らせたいときは--no-restore（Bicep CLI 0.4.X以降）を付けますが、キャッシュに無いモジュールがあるとビルドは失敗します。

.bicepparamの版要件とusing・extendsの書き分け

パラメーターを外出しする方法は、ネイティブの.bicepparamと従来のJSONパラメーターファイルの2通りです。.bicepparamには版要件があり、下回ると単純に認識されません。

ファイル先頭のusingが対象のBicepファイルを指し示します。1つのBicepファイルに対し、環境ごとの.bicepparamを複数用意するのが基本形です。特定のファイルに紐づけないならusing noneを使います。共通値を基底ファイルへ寄せるならextendsですが、継承できるのはパラメーター代入だけで、基底側の変数・ユーザー定義型は派生ファイルへ公開されません。extendsは1ファイルにつき1本までです。値には式や環境変数も指定できます。

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param intFromEnv = int(readEnvironmentVariable('INSTANCE_COUNT'))

既存のBicepファイルからパラメーターファイルの雛形を作るにはbicep generate-params main.bicep --output-format bicepparam --include-params allを使います。JSON形式との相互変換はbuild-paramsとdecompile-paramsが担当します。

パスワードをパラメーターファイルに書かない代替手段

パラメーターファイルの値は平文で保存されます。公式ドキュメントもパスワードなどの機密値をここに書かないよう警告しています。機密値はKey Vaultに置き、Bicep側からgetSecret関数で取得する形にしてください。CI/CDのパイプラインでリポジトリに.bicepparamをコミットする運用なら、この分離は必須です。

az deployment group createによるデプロイと事前確認

bicepparamを渡すデプロイコマンドの書き方

リソースグループへのデプロイは1コマンドで完結します。テンプレートファイルを直接指定する形が基本です。

az login
az deployment group create --resource-group my-rg --template-file ./main.bicep

.bicepparamを使う場合、そのファイル内のusingが対象Bicepファイルを指しているため、--template-fileの指定自体を省けます。この書き方はAzure CLI 2.53.0以降とBicep CLI 0.22.X以降が条件です。

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

ローカルのパラメーターファイルとインライン指定は併用でき、重複した場合はインラインの値が優先されます。外部URIで参照できるのはJSONパラメーターファイルだけで、外部.bicepparamは未サポートです。外部ファイル指定時はインラインの値がすべて無視される点にも注意してください。アプリケーションのコードとインフラをまとめて扱いたい場合は、テンプレート駆動のAzure Developer CLI（azd）とは？特徴とAzure CLIとの違いを解説も検討対象になります。

what-ifによる差分確認と、完全モードを選ばない理由

本番環境へ流す前にaz deployment group what-ifで差分を出します。実際のAzureの状態とテンプレートを突き合わせ、作成・変更・削除されるリソースを列挙するコマンドです。既定のデプロイモードは増分（Incremental）で、テンプレートに書かれていない既存リソースには手を付けません。

ここで、古い記事の記述をそのまま真似しないでください。テンプレートに無いリソースを削除する完全モード（--mode Complete）について、Microsoftは「Complete mode is not recommended」と警告し、「complete mode will be gradually deprecated」＝段階的に非推奨化すると明記しています。削除を伴う運用が必要なら、後継のデプロイメントスタック（az stack group create）を使う指示になっています。増分モードにも落とし穴があり、テンプレートに書かなかったプロパティは「変更されない」のではなく既定値へリセットされます。既存リソースを再デプロイするときは、既定値でない値をすべて書き切ってください。

既存Azureリソースのコード化手順とdecompileの限界

az group exportからdecompileまでの流れ

手動で作ってしまったリソースをコードへ寄せる場合、リソースグループのARMテンプレートを書き出してから逆コンパイルします。

az group export --name "your_resource_group_name" > main.json
az bicep decompile --file main.json

同名のmain.bicepが既にあるときは--forceで上書きします。Azureポータルからのテンプレートエクスポートや、VS CodeでARM JSONを貼り付けると自動でBicepへ変換される機能（既定で有効）も同じ用途に使えます。個別のリソースだけなら、VS Codeの拡張機能から既存リソースを取り込んで宣言を生成する方法が手早く済みます。

変換後に必ず直す箇所

decompileの出力をそのままデプロイしてはいけません。公式ドキュメントは「JSON ARMテンプレートからBicepへのマッピングが保証されていません」「正確な変換が不可能であればデコンパイルが失敗する可能性があります」と明記しています。公式が挙げる修正箇所は次の3点です。

• パラメーター名のピリオドはアンダースコアへ機械的に置換される（Security.Authentication.AAD.TenantがSecurity_Authentication_AAD_Tenantになる）ため、参照側の更新が要る
• 変数名やシンボル名が変換器の命名規則のまま残るので、VS Codeのシンボル名変更（F2）で意味の通る名前へまとめて直す
• 警告・エラーが残ることがあり、ベストプラクティスに沿った書き換えが別途必要になる

JSONからBicepへ変換しbuildでJSONへ戻すと、元とは異なる構文になる場合があります。デプロイ結果は同じですが、変換は片道の作業として扱うのが無難です。

モジュール分割とAzure Verified Modulesの利用

公開レジストリを優先する判断基準

ストレージアカウントや仮想ネットワークのような定番リソースは、Microsoftが検証済みのモジュールを公開しています。Azure Verified Modules（AVM）はbicep-registry-modulesリポジトリで開発され、パブリックレジストリのbr/publicエイリアスから参照できます。バージョンはモジュールごとに独立していて、ストレージアカウント用モジュールは2026年8月時点で0.33.0が最新です。

module storage 'br/public:avm/res/storage/storage-account:0.33.0' = {
  name: 'storageDeploy'
  params: {
    name: 'stexample001'
  }
}

タグは固定で書きます。公開レジストリが発行するのはバージョンタグだけで、参照したバージョンがローカルキャッシュへ取り込まれます。キャッシュは既存があると更新されないため、同じタグで内容が変わった場合はaz bicep restore --file main.bicep --forceで取り直します。

社内向けモジュールをACRへ発行する場合の注意

組織固有のモジュールはAzure Container Registryへ発行して共有します。発行にはレジストリへの適切なアクセス権が必要です。

az bicep publish --file storage.bicep \
  --target "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" \
  --documentation-uri https://www.contoso.com/exampleregistry.html

既存タグへ発行しようとするとエラーになり、上書きするには--forceの明示が要ります。内容を変えたらタグのバージョンを上げる運用にしてください。オプション名は--documentation-uriで、旧表記の--documentationUriは非推奨として将来削除される予定です。publishはbicepconfig.jsonのエイリアスを解決しないため、ターゲットには完全なパスを書きます。レジストリ自体の料金や運用はAzure Container Registry（ACR）とは？仕組み・料金プランとACR Tasks・ECR/GHCRとの違いを実装者目線で解説を参照してください。

snapshotとconsoleで手戻りを減らす検証手順

ローカル完結のsnapshotとクラウド照合のwhat-ifの使い分け

Bicep CLI v0.41.2以降で使えるsnapshotは、.bicepparamが最終的に生成するリソース定義を正規化し、.snapshot.jsonとして書き出します。モジュールへの切り出しのようなリファクタリングで、生成結果が変わっていないことをAzureに接続せず確認できます。Azure CLI側にも同名のコマンドがGAで用意されています。

az bicep snapshot --file main.bicepparam
az bicep snapshot --file main.bicepparam --mode Validate

--mode Validateは保存済みスナップショットと現在のテンプレートを比較し、差異があれば失敗します。what-ifとは役割が違います。

プルリクエストごとの検証はsnapshotで足ります。what-ifは実環境への問い合わせが入るぶん時間がかかり、レビュー段階で毎回回す価値は薄いためです。what-ifは本番デプロイ直前の1回に絞るのが現実的な配分になります。subscription()のような環境依存の関数やexisting参照を使っているなら、--subscription-idや--resource-groupでデプロイコンテキストを与えてください。これらはBicep CLIへ渡される値で、Azure CLIの認証先は変わりません。

consoleによる式の単体検証

v0.42.1以降ではbicep consoleでREPLが起動し、式や関数の評価結果をその場で確認できます。文字列の組み立てやラムダを含む変換ロジックを、デプロイを1回も走らせずに検証できるのが利点です。

> length(['a', 'b', 'c'])
3
> map([{ name: 'Alice' }, { name: 'Bob' }], user => user.name)
['Alice', 'Bob']

制約もあります。resourceGroup()のようにAzureコンテキストを要する式は評価できず、セッション間で状態は保持されません。入力補完もありません。consoleはAzure CLIのコマンド一覧に無いため、Bicep CLIを直接呼ぶ必要があります。パイプ入力に対応しているので、CIから式の評価結果を検証する使い方もできます。

よくある質問

Bicepの読み方や名前の由来は何ですか？

日本語圏では「バイセップ」と読まれるのが一般的ですが、Microsoftの公式ドキュメントにカタカナ表記はなく、本文は「Bicep」の英字表記で統一されています。名前の由来も同様で、Microsoft LearnのBicep FAQは6問構成のうち命名を説明する項目が無く（2026年8月2日時点）、ARM（Azure Resource Manager）＝腕にかけた命名という説明はコミュニティ発のものです。一次情報として確認できる記述はありません。英語の biceps が上腕二頭筋を指すため検索結果は混在します。Azureの文脈で調べるときは「azure bicep」と組み合わせてください。

bicep installを実行したのにコマンドが見つからないのはなぜですか？

Azure CLIがインストールするBicep CLIは自己完結型のインスタンスで、PATHに追加されないためです。bicep --versionはBicep CLIが見つからない旨のエラーになり、az bicep versionならBicep CLI version 0.46.1のように返ります。PATH上でbicepコマンドを使いたいなら手動インストールが必要です。Azure CLI側の挙動はaz config set bicep.use_binary_from_path=Trueで切り替えられ、PATH上のBicep CLIを使わせることもできます。

bicep buildは毎回実行する必要がありますか？

必要ありません。az deployment group createなどのデプロイコマンドが内部で変換します。構文エラーだけを先に潰したいならaz bicep lint --file main.bicep、整形はaz bicep format --file main.bicepが使えます。専用のaz bicepラッパーが無いコマンドはaz bicep run --command "build main.bicep"の形でBicep CLIへそのまま転送できます。

Bicepのダウンロードはどこから行いますか？

Bicep CLIの実体はGitHubのAzure/bicepリポジトリのリリースページで配布されています。Windowsインストーラー（bicep-setup-win-x64.exe）は管理者権限なしで実行でき、インストール後にユーザーのPATHへ追加されます。バイナリはLinuxがbicep-linux-x64、macOSがbicep-osx-x64で、ARM64機向けにはbicep-linux-arm64やbicep-osx-arm64も配布されています。Azure CLIを使う環境ではダウンロード作業自体が不要で、必要時に自動取得されます。

Bicepの利用に追加費用はかかりますか？

言語とツールの利用は無料です。GitHubリポジトリのREADMEに「100% free to use」と記載され、Microsoft Learnの概要ページも「Bicep は無料であるため、Premium 機能の料金は発生しません」としています。バージョン0.3以降はMicrosoftのサポートプランの対象です。課金が発生するのはデプロイしたAzureリソースそのものに対してで、状態ファイルを保管するためのストレージも要りません。

関連記事

• ARMテンプレートとBicep DSLの関係性と設計思想の違い
• Azure Developer CLI（azd）とは？特徴とAzure CLIとの違いを解説
• Azure Container Registry（ACR）とは？仕組み・料金プランとACR Tasks・ECR/GHCRとの違いを実装者目線で解説
• HCP Terraformとは？旧Terraform Cloud（名称変更）の機能・料金とHCPでの位置づけを解説