Azure Developer CLI のトラブルシューティング

この記事では、Azure Developer CLI (azd) を使用しているときに発生する可能性がある一般的な問題の解決策を提示します。

質問とフィードバック

このアーティクルで探しているものが見つからない場合、またはフィードバックを提供したい場合は、Azure Developer CLI ディスカッションに質問を投稿できます。

また、Azure Developer CLI GitHub リポジトリで GitHubイシューを開いてバグをレポートすることもできます。

--debug スイッチの使用

azd の操作中に予期しない問題が発生した場合は、--debug スイッチを付けてコマンドを再実行して、追加のデバッグと診断出力を有効にします。

azd up --debug

また、デバッグ出力をローカル テキスト ファイルに送信して、使いやすさを向上させることもできます。 この方法では、デバッグ情報を他の監視システムに取り込むことができます。また、GitHub で問題を報告する場合にも役立ちます。

azd deploy --debug > "<your-file-path>.txt"

.azure ディレクトリ

Azure Developer CLI では、.azureディレクトリに保存されているすべてのディレクトリが Azure Developer CLI 環境であると想定しています。 Azure CLI がインストールされているユーザーのホーム ディレクトリから Azure Developer CLI コマンドを実行しないでください。

Azure にログインしていないか、Visual Studio でトークンの有効期限が切れている

Visual Studio でazd init -t <template-name>を実行すると、次のエラーが表示されます。「リモートにアクセスするには、このリポジトリ、OAuth アプリケーション Visual Studioを再認証する必要があります。」

解決策

アクセス トークンを更新するためazd auth loginを実行する。

更新された Azure アカウントのアクセス許可の表示が、azd で更新されない

既定では、azd は Azure の資格情報とアクセス許可をキャッシュします。 Azure アカウントに新しいロールとアクセス許可が割り当てられたか、または追加のサブスクリプションに追加された場合は、これらの変更が azd にすぐには反映されない可能性があります。 この問題を解決するには、ログアウトしてから、次のコマンドを使用して azd に再びログインします。

azd auth logout

azd auth login

azd auth login コマンドのプロンプトに従ってサインイン プロセスを完了し、キャッシュされた資格情報を更新してください。

azd での Cloud Shell の制限事項

Cloud Shell で azd を実行する際には、いくつかの制限があります。

Cloud Shell での Docker サポート

Docker デーモンが実行されていないため、Cloud Shell では Docker build または run コマンドの実行をサポートしていません。 詳細については、「Cloud Shell のトラブルシューティング」を参照してください。

Cloud Shell のタイムアウト

Cloud Shell は、長いデプロイ タスクまたはその他の実行時間の長いタスクの間にタイムアウトになる場合があります。 セッションがアイドル状態にならないことを確認します。 「Cloud Shell の使用制限」を参照してください。

Cloud Shell インターフェイス

Cloud Shell は主にコマンドライン インターフェイスであり、Visual Studio Code などの統合開発環境よりも機能が少なくなります。

Cloud Shell で Docker デーモンに接続できない

Cloud Shell はコンテナーを使用してシェル環境をホストするので、Docker デーモンの実行を必要とするタスクは許可されません。

Cloud Shell に異なるバージョンの azd をインストールする

場合によっては、Cloud Shell で既に使用されているバージョンとは異なるバージョンの azd をインストールすることが必要になる場合があります。 bash でこれを行うには:

1. mkdir -p ~/bin を実行して、~/bin フォルダーが存在することを確認します
2. mkdir -p ~/azd を実行して、ローカル ~/azd フォルダーが存在することを確認します
3. curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version> を実行します (既定では <version> はstable ですが、1.0.0 のような特定のリリース済みバージョンを指定することもできます)。

インストールすると、~/bin でシンボリックにリンクされているバージョンの azd が、/usr/local/bin でシンボリックにリンクされているバージョンの azd よりも優先されます。

bash で Cloud Shell に既にインストールされているバージョンの azd を使用するように戻すには:

1. rm ~/bin/azd を実行します。
2. rm -rf ~/azd を実行します。

解決策

別のホストを使用して、Docker デーモンを必要とするタスクを実行します。 1 つの選択肢は、Cloud Shell のトラブルシューティングドキュメントで説明されているように、docker-machine を使用することです。

Azure Bicep CLI の要件

azd up とazd provision はAzure Bicep CLIの最新リリースを必要とします。 以下のエラーメッセージが表示されるかもしれません:「エラー: bicep テンプレートのコンパイルに失敗しました: Az PowerShell モジュール bicep ビルドの実行に失敗しました: 終了コード: 1, stdout: , stderr: 警告: 新しいBicep のリリースが利用可能: v0.4.1272。」

解決策

以前は、Bicep はインストールと使用 azd の前提条件でした。 azd では、(グローバルではなく) ローカル azd スコープ内に Bicep が自動的にインストールされ、この問題は解決されるはずです。 ただし、別のバージョンを使用したい場合は、必要なバージョンの場所を指すように環境変数AZD_BICEP_TOOL_PATHを設定できます。

azd upまたはazd provisionは失敗する

時々 azd up または azd provisionがうまくいかないかもしれません。 一般的なエラーの理由は、次のとおりです。

• 「リージョンの容量が不足しているため、Azure リージョンに特定のリソースをプロビジョニングできません。」
• 「関連リソース プロバイダーがそのリージョンに存在しません。」

トラブルシューティングステップは、根本原因によって異なる場合があります。

解決策

1. Azure ポータルにアクセスします。

2. リソース グループ (rg-<環境名>) を見つけます。

3. 詳細を取得するには、[デプロイ] を選択します。

4. 環境名と同じ環境名を指定したことを確認します。

5. https://github.com/<your repo>/actionsに移動し、パイプライン実行のログ ファイルを参照して詳細を確認します。

その他のリソースについては、「Azure デプロイに関する一般的なエラーのトラブルシューティング - Azure Resource Manager」 をご覧ください。

azd init には sudo が必要です。

azd version = azure-dev-cli_0.2.0-beta.1 以前は、azd は drw-r--r-- アクセス権を持つ .azd フォルダーを作成していました。

これにより問題が発生しますが、それは任意の Linux セットアップ (WSL、ssh-remote、devcontainer など) でこのバージョンまたは以前のバージョンを使用することで、読み取り専用モードの .azd フォルダーが既に提供されているためです。

解決策

1. 既に提供されている .azd フォルダーを手動で削除してください。

   rm -r ~/.azd
   

2. azd に対して azd init を実行して、適切なアクセス レベルを持つフォルダーを再び作成します。

開発コンテナー用 azd monitor

azd monitor は現在、開発環境として開発コンテナーを使用する場合はサポートされていません。

Codespaces 環境で認証できない

Codespaces で認証の問題が発生している場合は、テンプレート Dockerfile に sudo apt-get update && sudo apt-get install xdg-utils コマンドが含まれていることを確認してください。 xdg-utils コマンドを実行すると、サインインできるようにするブラウザー タブが開きます。

成功メッセージにもかかわらず Static Web Apps のデプロイに失敗する

Azure Static Web Apps にデプロイするときに既知の問題が存在します。この場合、既定の azd up 出力でアクションが成功したと示される可能性がありますが、変更内容は実際にはデプロイされていません。 この問題を診断するには、--debug フラグを有効にして azd up コマンドを実行します。 出力ログで次のメッセージが表示されることがあります。

Preparing deployment. Please wait...
An unknown exception has occurred

この問題が発生する可能性が最も高くなるのは、azd が GitHub アクションから実行された場合です。 回避策として、サイトをビルドした後、staticwebapp.config.json をビルド フォルダーにコピーします。 この手順は、事前パッケージまたは事前デプロイのコマンド フックを使用して自動化できます。これにより、azd コマンド ワークフローのさまざまなポイントでカスタム スクリプトを実行できます。

製品チームではこの問題を解決するために作業中です。

GitHub Actions エラー -「キー コンテナーに対するシークレットのアクセス許可がありません」

ローカルおよび GitHub Actions でリソースをプロビジョニングするときに、同じ環境またはリソース グループ名を共有すると、Key Vault サービスからエラー Does not have secrets get permission on key vault.. が発生する可能性があります。 Key Vault では、Bicep による増分アクセス許可の更新はサポートされていません。これは実質上、GitHub Actions ワークフローによってローカル ユーザーの Access Policy のアクセス許可が上書きされるということを意味します。

この問題の推奨される解決策は、ローカル開発と GitHub Actions ワークフローに個別の環境名を使用することです。 azd env コマンドを使用した複数環境の使用についての詳細は、FAQ ページを参照してください。

テキスト ベースのブラウザーのサポート

テキスト ベースのブラウザーは現在azd monitorにサポートされていません。

Windows 上での AzDo for Java テンプレートを使用した azd pipeline config

Windows 上で AzDo for Java テンプレートを使用して azd pipeline config を実行すると、エラーが発生する可能性があります。 たとえば、以下を実行したとします。

1. Windows 上で次を実行します。

   azd init --template Azure-Samples/todo-java-mongo
   azd pipeline config
   

2. 以下のエラーが発生しました。

   

解決策

これは既知の問題です。 当社では現在、この問題に取り組んでいますが、回避策として次のコマンドを試してください。

git update-index --chmod=+x src/api/mvnw && git commit -m "Fix executable bit permissions" && git push

Apple シリコン (M1/M2) 上で azd をアップグレードした後に failed packaging service 'api': failed invoking action 'package', failed to run NPM script build, signal: segmentation fault エラーが発生する

場合によっては、x86_64 バージョンの azd から ARM64 バイナリにアップグレードすると、x86_64 バージョンの azd を使用してビルドされたテンプレートでエラーが発生する可能性があります。 これは、テンプレートで任意のバージョンの v8-compile-cache を使用しており、これが x86_64 でビルドされたバイトコードを ARM64 プロセスに読み込もうとする可能性があるためです。

この問題を解決するには、影響を受けるプロジェクトの v8-compile-cache パッケージをアップグレードします。

1. ディレクトリを、エラーが発生したサービスに変更します (failed packaging service 'api' の場合は src/api)
2. npm upgrade v8-compile-cache を実行します。
3. ディレクトリをリポジトリのルートに変更し、azd コマンド (azd package や azd up など) をもう一度実行します

条件付きアクセス ポリシーによる azd pipeline config の失敗

azd pipeline config の実行中に、次のようなエラーが表示される場合があります。

ERROR: failed to create or update service principal: failed retrieving application list, failed executing request: http call(https://login.microsoftonline.com/common/oauth2/v2.0/token)(POST) error: reply status code was 400:
{"error":"invalid_grant","error_description":"AADSTS50005: User tried to log in to a device from a platform (Unknown) that's currently not supported through Conditional Access policy. Supported device platforms are: iOS, Android, Mac, and Windows flavors.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd"}

このエラーは、条件付きアクセス ポリシーの Microsoft Entra テナントの有効化に関連しています。 特定のポリシーでは、サポート対象デバイス プラットフォームにサインインしている必要があります。

また、デバイス コード メカニズムを使用してログインしているために、このエラーが発生する可能性もあります。これにより、Microsoft Entra ID がデバイス プラットフォームを正しく検出できなくなります。

解決策

ワークフローを構成するには、ユーザーに代わって Azure にデプロイするためのアクセス許可を GitHub に付与する必要があります。 AZURE_CREDENTIALS という名前の GitHub シークレットに格納される Azure サービス プリンシパルを作成して、GitHubを承認します。 手順として Codespace ホストを選択します。

azd pipeline config サポート

azd pipeline config は現在、DevContainers/VS Code リモート コンテナーではサポートされていません。

Python のライブ メトリックのサポート

ライブ メトリック (azd monitor --live) は現在、Python アプリではサポートされていません。 詳細については、「 ライブメトリック: １秒の待機時間の監視と診断」を参照してください。

GitHub の問題を作成して支援を求める

Azure Developer CLI と Azure Developer CLI Visual Studio Code 拡張機能 では、GitHub の問題を使用してバグと機能要求を追跡します。 重複を避けるために、新しい問題を提出する前に既存の問題を検索してください。

このプロジェクトの使用に関する支援要請と質問については、Azure Developer CLI の使用に関する Wiki を参照してください。投稿する場合は、投稿に関するドキュメントを参照してください。