Azure Developer CLI のトラブルシューティング
この記事では、Azure Developer CLI (azd) を使用しているときに発生する可能性がある一般的な問題の解決策を提示します。
質問とフィードバック
このアーティクルで探しているものが見つからない場合、またはフィードバックを提供したい場合は、Azure Developer CLI ディスカッションに質問を投稿できます。
また、Azure Developer CLI GitHub リポジトリで GitHubイシューを開いてバグをレポートすることもできます。
--debug スイッチの使用
azd の操作中に予期しない問題が発生した場合は、--debug スイッチを付けてコマンドを再実行して、追加のデバッグと診断出力を有効にします。
azd up --debug
また、デバッグ出力をローカル テキスト ファイルに送信して、使いやすさを向上させることもできます。 この方法では、デバッグ情報を他の監視システムに取り込むことができます。また、GitHub で問題を報告する場合にも役立ちます。
重要
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 でこれを行うには:
mkdir -p ~/binを実行して、~/binフォルダーが存在することを確認しますmkdir -p ~/azdを実行して、ローカル~/azdフォルダーが存在することを確認します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 を使用するように戻すには:
rm ~/bin/azdを実行します。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 リージョンに特定のリソースをプロビジョニングできません。」
- 「関連リソース プロバイダーがそのリージョンに存在しません。」
トラブルシューティングステップは、根本原因によって異なる場合があります。
解決策
Azure ポータルにアクセスします。
リソース グループ (rg-<環境名>) を見つけます。
詳細を取得するには、[デプロイ] を選択します。
環境名と同じ環境名を指定したことを確認します。
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 フォルダーが既に提供されているためです。
解決策
既に提供されている
.azdフォルダーを手動で削除してください。rm -r ~/.azdazdに対して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 を実行すると、エラーが発生する可能性があります。 たとえば、以下を実行したとします。
Windows 上で次を実行します。
azd init --template Azure-Samples/todo-java-mongo azd pipeline config以下のエラーが発生しました。
解決策
これは既知の問題です。 当社では現在、この問題に取り組んでいますが、回避策として次のコマンドを試してください。
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 パッケージをアップグレードします。
- ディレクトリを、エラーが発生したサービスに変更します (
failed packaging service 'api'の場合はsrc/api) npm upgrade v8-compile-cacheを実行します。- ディレクトリをリポジトリのルートに変更し、
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: be3438c1-42fc-4c37-96d8-0e723ac54f01\r\nCorrelation ID: f535565f-9f3c-4014-ad65-403f514bf892\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"be3438c1-42fc-4c37-96d8-0e723ac54f01","correlation_id":"f535565f-9f3c-4014-ad65-403f514bf892"}
このエラーは、条件付きアクセス ポリシーの Microsoft Entra テナントの有効化に関連しています。 特定のポリシーでは、サポート対象デバイス プラットフォームにサインインしている必要があります。
また、デバイス コード メカニズムを使用してログインしているために、このエラーが発生する可能性もあります。これにより、Microsoft Entra ID がデバイス プラットフォームを正しく検出できなくなります。
解決策
ワークフローを構成するには、ユーザーに代わって Azure にデプロイするためのアクセス許可を GitHub に付与する必要があります。 AZURE_CREDENTIALS という名前の GitHub シークレットに格納される Azure サービス プリンシパルを作成して、GitHubを承認します。 手順として Codespace ホストを選択します。
エラー メッセージに従って、サポート対象として一覧表示されているデバイス上で実行していることを確認します。
フラグ
--use-device-code=falseを追加してazd auth loginを再び実行します。azd auth login --use-device-code=falseログイン後にメッセージ
localhost refused to connectが表示される場合があります。 その場合:- URL をコピーします。
- 新しい Codespaces ターミナルで
curl '<pasted url>'を実行します (URL は引用符で囲む)。
元のターミナルで、ログインに成功するはずです。
ログイン後、
azd pipeline configを再び実行します。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示