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

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

ヘルプを表示してフィードバックを送信する

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

また、Azure Developer CLI GitHub リポジトリで GitHub Issues を開いてバグを報告することもできます。

--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 コマンドの指示に従ってサインイン プロセスを完了し、キャッシュされた資格情報を更新します。

Cloud Shell の制限事項 azd

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などの特定のリリースバージョンを指定することもできます)。

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

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 の最新リリースが必要です。 次のエラーメッセージが表示されることがあります: "Error: Bicepテンプレートのコンパイルに失敗しました: Az PowerShellモジュールのbicepビルドを実行できませんでした: exit code: 1, stdout: , stderr: WARNING: 新しい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-<your-environment-name> を見つけます。

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

4. あなたの環境名と一致する環境名を指定したことを確認してください。

5. 影響を受ける GitHub リポジトリの [アクション ] タブに移動し、パイプライン実行のログ ファイルを調べて詳細を確認します。

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

azd init はsudoを必要とする

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

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

解決策

1. 既に指定されている .azd フォルダーを手動で削除します。

   rm -r ~/.azd
   

2. azd initのazdを実行して、適切なアクセス レベルでフォルダーをもう一度作成します。

azd monitor 開発コンテナー用

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

Codespaces 環境で認証できない

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

成功メッセージにもかかわらず静的 Web アプリのデプロイに失敗する

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

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

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

製品チームは、この問題の解決に取り組んでいます。

GitHub Actions エラー - "キー ボールトに対するシークレットの取得権限を持っていません"

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

この問題の推奨される解決策は、ローカル開発と GitHub Actions ワークフローに個別の環境名を使用することです。 FAQ ページの コマンドでazd envする方法の詳細を確認します。

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

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

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

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

failed packaging service 'api': failed invoking action 'package', failed to run NPM script build, signal: segmentation fault Apple Silicon (M1/M2) で azd をアップグレードした後のエラー

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

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

1. 失敗したサービスにディレクトリを変更する (src/apiの場合はfailed packaging service '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 ホストを選択します。

現在の Dockerfile の代わりに、キャッシュされた Dockerfile が使用される。

Docker を使用してローカル開発環境で azd を使用する場合、Docker は現在のバージョンではなく、キャッシュされたバージョンの Dockerfile を使用する場合があります。 これにより、正しくない情報を含むコンテナーを使用してデプロイが行われます。

解決策

Azure Developer CLI によってコンテナーをビルドするために使用されるローカル Docker インストールを構成するには、次の環境変数を使用して Docker を構成する必要があります。

DOCKER_BUILDKIT=1
DOCKER_BUILD_ARGS="--no-cache"

azd upを変更して、次の設定を含めることができます。

DOCKER_BUILDKIT=1 DOCKER_BUILD_ARGS="--no-cache" azd up

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 と 投稿する場合の投稿に関するドキュメント を参照してください。