Azure Developer CLI（azd）とは？Azure CLIとの違い・インストールとazd upの使い方

Azure Developer CLI（コマンド名は azd）は、アプリのコード・インフラ定義（BicepまたはTerraform）・CI/CDの設定をひとつのプロジェクトとして扱い、azd up 1回でAzureへのリソース作成とデプロイまで進めるオープンソースのCLIです。この記事では、Azure CLI（az）との役割の違い、OS別のインストール、azd init から azd down までの主要コマンド、認証と環境の切り替え、azd pipeline config が付与する権限までを、2026年9月30日公開の azd 1.35.0 のヘルプ出力と公式ドキュメントで確認した内容で整理します。

まとめ：azdの要点

• azdはアプリ単位の「作って載せる」を担うCLI、Azure CLI（az）はリソース単位の管理を担うCLI。公式も両者を補完関係と説明しており、置き換えではない。
• インストールはWindowsが winget install microsoft.azd、macOSが brew install azure/azd/azd、Linuxが curl -fsSL https://aka.ms/install-azd.sh | bash。確認は azd version。
• azd up はpackage → provision → deployの3段をまとめて実行する。コードだけ変えたら azd deploy、Bicep／Terraformを変えたら azd provision。
• プロジェクトの定義は azure.yaml、環境ごとの値は .azure/<環境名>/.env。.azure は azd init が .gitignore に入れる。
• azd pipeline config は既定でOIDC（フェデレーション資格情報）を使い、サービスプリンシパルに共同作成者とユーザーアクセス管理者の2ロールを付ける。権限設計が厳しい組織では --principal-role で絞るか、azdを使わない判断が要る。

以下、役割の違い→導入→コマンド→認証と環境→CI/CD→採用判断の順に説明します。

Azure Developer CLI（azd）の役割とAzure CLI（az）との違い

Microsoftの比較ページ「Azure Developer CLI vs Azure CLI overview」は、azdを「フルスタックアプリの構築・プロビジョニング・デプロイ・管理を効率化する開発者向けCLI」、Azure CLIを「Azureリソースを管理する汎用CLI」と定義しています。違いはコマンドの粒度に表れます。azdのコマンドは init・provision・deploy・monitor のようにアプリのライフサイクルに沿って並び、azのコマンドは acr・aks・appservice のようにサービス名で並びます。

実務では併用が前提になります。azdで環境を立ち上げた後、ログの確認やスケール設定の微調整、ロールの付与といった個別操作はazで行うのが普通です。azdのヘルプにも「Azure CLIと違い、azdはサブスクリプションやリージョンを名前付きの環境に保存する」と書かれています。azも az config set defaults.location=japaneast のようにユーザー単位の既定値は持てますが、dev・prodといった環境ごとに値の組を切り替える仕組みはazd側にしかありません。Azure CLI自体のバージョン確認は az version、ブラウザだけで試すならAzure Cloud Shellの使い方で紹介している環境にazが入っています。

azdのインストール手順（Windows・macOS・Linux）

公式のインストール手順（install-azd）に載っているコマンドは次のとおりです。インストール時にGitHub CLIとBicep CLIがazdの専用領域に入り、azdをアンインストールすると一緒に消えます。システム全体の gh や bicep とは別物なので、既存の環境を上書きする心配はありません。

Windows：winget・Chocolatey・PowerShellスクリプト

winget install microsoft.azd
winget upgrade microsoft.azd

choco install azd

powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"

Arm64版のWindowsはアルファ扱いで、パッケージマネージャー経由の配布はなく、GitHubのリリースページから直接ダウンロードします。x86_64版が入っている場合は先にアンインストールしないと、MSIの更新でArm64版の実行ファイルが上書きされると公式が注意しています。

macOS：Homebrew

brew install azure/azd/azd
brew upgrade --cask azure/azd/azd

公式の推奨はHomebrewです。インストールスクリプト（curl -fsSL https://aka.ms/install-azd.sh | bash）で入れたazdをbrew管理へ移す場合は、先に既存のバイナリを消してから brew install します。

Linux：スクリプト・.deb・.rpm

curl -fsSL https://aka.ms/install-azd.sh | bash

# 版を固定する場合（Debian/Ubuntu）
curl -fSL https://github.com/Azure/azure-dev/releases/download/azure-dev-cli_1.35.0/azd_1.35.0_amd64.deb -o azd_1.35.0_amd64.deb
sudo apt install ./azd_1.35.0_amd64.deb -y

# アンインストール
curl -fsSL https://aka.ms/uninstall-azd.sh | bash

1.35.0のリリースにはx86_64とaarch64の.deb・.rpm、macOSのamd64・arm64、Windowsのamd64（MSI・zip）が並んでいます。CIのランナーなど版を揃えたい環境では、スクリプトより版番号入りのパッケージのほうが再現性を保てます。

バージョン確認・更新とテレメトリの無効化

$ azd version
azd version 1.35.0 (commit 170ebb858071da353cc9bf8657a377bff268ba36) (stable)

$ azd update --channel stable
$ export AZURE_DEV_COLLECT_TELEMETRY=no          # bash/zsh（現在のシェルのみ）
PS> $env:AZURE_DEV_COLLECT_TELEMETRY = "no"   # PowerShell（現在のセッションのみ）

リリースはおおむね週1回で、1.34.0（9月9日）→1.34.1（9月16日）→1.34.2（9月24日）→1.35.0（9月30日）と進んでいます。azd update はベータ扱いのコマンドで、--channel に stable か daily を指定します。使用状況の送信を止めるには、azure-devリポジトリのREADMEにあるとおり環境変数 AZURE_DEV_COLLECT_TELEMETRY=no を設定します。上の例は現在のシェルだけに効くので、常に止めたい場合は ~/.zshrc などのシェル設定や、Windowsのユーザー環境変数に登録してください。

azd initによるプロジェクトの初期化

azd init は、テンプレートから始める方法と、手元のコードに設定ファイルを足す方法の2通りで使います。フラグなしで実行すると、どちらにするかを対話で選べます。

テンプレートの指定方法と公式ギャラリー

azd init --template hello-azd
azd init -t Azure-Samples/todo-nodejs-mongo .
azd init -t https://github.com/Azure-Samples/hello-azd --branch main
azd template list --filter python

--template にはフルURI、<owner>/<repository>、Azure-Samples配下ならリポジトリ名だけ、ローカルのディレクトリパスのいずれも渡せます。1.24.0（2026年4月14日）以降は --template を付けると git clone と同じようにテンプレート名のディレクトリが新しく作られるため、カレントディレクトリに展開したいときは末尾に . を付けます。2026年10月7日に既定のテンプレートソース設定のまま azd template list を実行し、出力の REPOSITORY: 行を数えると303件で、いずれもソースは「Awesome azd」でした。件数は日々変わるので目安としてください。初期化と同時にデプロイまで進める --up フラグもあります。

既存コードからの初期化と生成されるファイル

手元のアプリをazd化するときは azd init --from-code で言語とホスト先を検出させるか、--minimal で空の azure.yaml だけを作ります。空のディレクトリで azd init --minimal -e dev --no-prompt を実行すると、次のファイルができました。

.gitignore            # 中身は ".azure" の1行
azure.yaml            # name: <ディレクトリ名> のみ
.azure/config.json    # {"version":1,"defaultEnvironment":"dev"}
.azure/dev/.env       # AZURE_ENV_NAME="dev"

gitリポジトリが無ければ初期化も行われます。.azure 配下はサブスクリプションIDやデプロイ結果の出力値が書き込まれる場所なので、コミットしない設計になっています。リソースの追加は、ベータの azd add で対話的に足していきます。

azure.yamlのservicesとhostの値

name: todo-app
services:
  api:
    project: ./src/api
    language: python
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp
hooks:
  postprovision:
    shell: sh
    run: ./scripts/seed.sh

1.35.0タグのazure.yamlスキーマが例示する host の値は、appservice・containerapp・function・springapp・staticwebapp・aks と、ai.endpoint や azure.ai.agent などFoundry系の値です。公式の対応表ではApp Service・Static Web Apps・Container Apps・Functionsが安定版、AKSは kubectl apply -f で展開できる構成に限ったベータです。言語はNode.js・Python・.NET・Javaが安定版で、GoはAzure Functions向けのみのプレビューです。IaCの既定はBicepで、infra.provider: terraform に切り替えられます（Azure Bicepの実務手順、TerraformでAzureを構築する手順）。

プロジェクト全体のフックは preprovision・postprovision・preup・postup・predeploy・postdeploy・predown・postdown など18種、サービス単位では prebuild・prepackage・predeploy など10種がスキーマに定義されています。DBの初期データ投入や、作成されたAPIのURLを環境変数として後続処理へ渡す処理は postprovision に書くのが定番です。ただし既定の azd up はpackageをprovisionより先に実行するので、URLをビルド成果物に埋め込むフロントエンドでは、前述の workflows でprovisionを先頭に移す必要があります。

azd up・provision・deploy・downの違い

azd up の手順は azure.yaml の workflows で並べ替えられ、ヘルプには「provisionを先に実行してからpackageとdeployを行う」例が載っています。azd provision には変更内容だけを表示する --preview と、保存済みのデプロイ状態を無視してBicepを適用し直す --no-state があります。1.35.0では azd deploy --preview が加わり、App Service・Container Apps・Functions・Static Web Apps・AKSなどで、配置せずに変更内容だけを確認できるようになりました。azd deploy の既定タイムアウトはサービスごとに1,200秒で、超えてもazdが待つのをやめるだけでAzure側のデプロイは止まりません。azd deploy api --from-package <パス> で、作成済みのzipやコンテナイメージをそのまま配置することもできます。

azd down –purgeを付ける理由

azd down はローカルのファイルを消さず、Azure上のリソースだけを削除します。Key Vaultのように既定で論理削除されるリソースは、通常の azd down では完全削除するかを確認され、完全削除しなかった場合は名前が保持期間中予約されたまま残るため、同じ名前で azd up し直すと衝突します。--purge はこの完全削除を確認なしで行う指定で、検証環境を作っては壊す運用に向きます。ただしKey Vaultの消去保護（purge protection）が有効な場合は保持期間が過ぎるまで完全削除できないので、論理削除済みの資格情報コンテナーを復元して使い直すか、名前を変えて作り直します。Terraformのプロジェクトは、CIや --no-prompt で実行すると --force を付けない限り削除対象を表示するだけで終わる点に注意してください。

azd auth loginとazd envによる認証・環境管理

azd auth loginのログイン方式

azd auth login                                 # ブラウザ
azd auth login --use-device-code               # SSH先・コンテナ内
azd auth login --client-id <ID> --client-secret <SECRET> --tenant-id <TENANT>
azd auth login --client-id <ID> --federated-credential-provider github --tenant-id <TENANT>
azd auth login --managed-identity
azd auth login --check-status

azdの資格情報は az login とは別に保存されます。azで済ませたログインをazdでも使いたい場合は azd config set auth.useAzCliAuth true を設定します。--federated-credential-provider に指定できる値は github・azure-pipelines・oidc の3つです。

なお、Foundryのエージェントなど azd ai 系の機能は本体ではなく拡張機能として配布されています。拡張機能の仕組み自体はGAですが、2026年9月30日時点で azure.ai.agents は1.0.0-beta.18のプレリリースです。

azd envによる開発・本番環境の切り替え

azd env new prod
azd env select dev
azd env set AZURE_LOCATION japaneast
azd env get-values
azd env set-secret DB_PASSWORD

環境ごとの値は .azure/<環境名>/.env に保存され、azd up などは選択中の環境を自動で読みます。一時的に別環境を使うなら各コマンドに -e prod を付けます。パスワードなどの機密値は azd env set-secret でKey Vaultのシークレットへの参照として持たせると、.envに平文で残りません（Azure Key Vaultの仕組み）。サブスクリプションとリージョンの既定値は azd config set defaults.location japaneast のようにユーザー設定にも置けます。

azd pipeline configによるGitHub Actions・Azure Pipelinesの構成

azd pipeline config                       # GitHub Actions（既定）
azd pipeline config --provider azdo       # Azure Pipelines
azd pipeline config -e prod --principal-role Contributor

azd pipeline config はサービスプリンシパルを作成（または既存のものを使用）し、選択中の環境の値をパイプラインの変数とシークレットに書き込みます。テンプレートに同梱された azure-dev.yml が、GitHubなら .github/workflows、Azure DevOpsなら .azdo/pipelines などに配置されます。認証方式の既定はGitHub・Azure DevOpsとも federated（OIDC）で、--auth-type client-credentials でシークレット方式に切り替えられます。ただし公式ドキュメントは「OIDC／フェデレーション資格情報はTerraformでは使えない」と明記しており、Terraformのプロジェクトはシークレット方式になります。

見落とされやすいのが既定のロールです。ヘルプの記述は「既定でサービスプリンシパルに共同作成者（Contributor）とユーザーアクセス管理者（User Access Administrator）のロールを付与する」です。ユーザーアクセス管理者はロールの割り当てそのものを変更できる強い権限なので、本番サブスクリプションでは --principal-role で必要なロールだけを指定してください。Azure Pipelines側の設計はAzure PipelinesのYAMLとCI/CDの手順を参照してください。

azdを採用すべきでない場面と判断基準

azdが効くのは「アプリとインフラを同じリポジトリで持ち、環境を何度も作って壊す」チームです。次の条件のうち、設定や運用の工夫で解消できないものがあるなら、azdの導入は見送るほうが手戻りが少なくなります。

• 既存のリソースをポータルやazで長く運用しており、IaCが無い。azdはBicep／Terraformの定義が正になる前提で、手作業の変更とは同期しない。
• CI/CDのサービスプリンシパルに付けられるロールが決まっており、Bicep内のロール割り当て（マネージドIDへの権限付与など）も許されない。--principal-role で既定のユーザーアクセス管理者は外せるが、テンプレート側がロール割り当てを含むとデプロイが失敗する。
• デプロイ先がAKSでHelmやKustomizeが前提になっている。AKS対応自体が kubectl apply -f で展開できる構成に限ったベータで、Helm・Kustomize対応は azd config list-alpha に出るアルファ機能にとどまる。
• インフラの変更は別チームの承認を経てしか適用できない。azd provision と azd deploy をパイプラインの別ステージに分ければ承認を挟めるが、インフラ定義のリポジトリ自体が別管理なら、azdの「1リポジトリにまとめる」前提が成り立たない。

逆に、新規開発でContainer AppsやApp Serviceに載せ、検証環境を頻繁に作り直す案件はazdの前提とよく合います（Azure Container Appsのデプロイ手順、Azure App Serviceの仕組みとデプロイスロット）。

よくある質問

azdとazはどちらを使えばよいですか？

アプリをテンプレートとIaCでまとめてデプロイするならazd、個別リソースの作成・変更・調査ならazです。公式も補完関係と説明しており、多くのプロジェクトでは両方を入れて使い分けます。

azd upとazd deployの違いは何ですか？

azd up はpackage・provision・deployを順に実行し、azd deploy はコードの配置だけを行います。インフラ定義を変えていないなら azd deploy のほうが短時間で終わります。

azd auth loginとaz loginは共通ですか？

別々に管理されています。azのログインをazdでも使う場合は azd config set auth.useAzCliAuth true を設定します。CIではサービスプリンシパルかフェデレーション資格情報で azd auth login します。

azdのインストール後にコマンドが認識されない場合は？

Windowsでwingetやスクリプトを使った直後は、ターミナルを開き直してPATHを読み込み直してください。macOSでスクリプト版とbrew版が混在している場合は、スクリプト版を curl -fsSL https://aka.ms/uninstall-azd.sh | bash で削除してから入れ直します。

azdは無料で使えますか？

azd自体はGitHubで公開されているオープンソースのツールで、利用料はかかりません。費用が発生するのは azd up で作成したAzureリソースのほうなので、検証後は azd down --purge で削除してください。

関連記事

• Azure Bicepとは？インストールからbicep build・デプロイまでの実務手順
• Azure Container Appsとは？特徴・料金・デプロイ手順とAKS・App Serviceの違い
• TerraformでAzureを構築する手順｜azurerm 5系の認証とbackend設計
• Azure Pipelinesの使い方｜YAMLでCI/CDを組む手順と無料枠・権限設定
• Azure Cloud Shellの使い方｜起動・料金・エフェメラルセッションを実務目線で解説