Bagikan melalui

Memecahkan masalah Azure Developer CLI

Artikel ini menyediakan solusi untuk masalah umum yang mungkin muncul saat Anda menggunakan Azure Developer CLI (azd).

Dapatkan bantuan dan berikan umpan balik

Jika Anda tidak dapat menemukan apa yang Anda cari dalam artikel ini atau ingin memberikan umpan balik, Anda dapat memposting pertanyaan ke Diskusi CLI Pengembang Azure.

Anda juga dapat melaporkan bug dengan membuka Masalah GitHub di repositori GitHub Azure Developer CLI.

Menggunakan sakelar --debug

Jika Anda mengalami masalah tak terduga saat bekerja dengan azd, jalankan ulang perintah dengan sakelar --debug untuk aktivasi lebih banyak debugging dan output diagnostik.

azd up --debug

Anda juga dapat mengirim output penelusuran kesalahan ke file teks lokal untuk meningkatkan kegunaan. Pendekatan ini memungkinkan sistem pemantauan lain untuk menyerap debugging dan juga dapat berguna saat mengajukan masalah di GitHub.

Penting

Pastikan untuk meredaksi informasi sensitif apa pun saat mengirimkan log debug di GitHub atau menyimpannya ke sistem diagnostik lainnya.

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

.azure Direktori

Azure Developer CLI mengasumsikan bahwa direktori apa pun yang disimpan di .azure direktori adalah lingkungan Azure Developer CLI. Jangan jalankan perintah Azure Developer CLI dari direktori beranda pengguna yang menginstal Azure CLI.

Tidak masuk ke Azure atau token kedaluwarsa di Visual Studio

Setelah Anda menjalankan azd init -t <template-name> di Visual Studio, Anda mendapatkan kesalahan berikut: "Untuk mengakses jarak jauh: repositori ini, Anda harus mengotorisasi ulang Aplikasi Visual StudioOAuth ."

Solusi

Jalankan azd auth login untuk memperbarui token akses.

Izin akun Azure yang diperbarui tidak di-refresh azd

Secara default, azd cache kredensial dan izin Azure Anda. Jika akun Azure Anda diberi peran dan izin baru, atau ditambahkan ke lebih banyak langganan, perubahan ini mungkin tidak segera tercermin dalam azd. Untuk memecahkan masalah ini, keluar dan masuk kembali ke azd menggunakan perintah berikut:

azd auth logout

azd auth login

Ikuti perintah dari azd auth login perintah untuk menyelesaikan proses masuk dan memperbarui kredensial cache Anda.

Batasan Cloud Shell untuk azd

Ada beberapa batasan untuk menjalankan azd di Cloud Shell.

Dukungan Docker di Cloud Shell

Cloud Shell tidak mendukung menjalankan docker build atau run perintah karena daemon docker tidak berjalan. Untuk informasi selengkapnya, lihat Pemecahan Masalah Cloud Shell.

Penghentian otomatis Cloud Shell

Cloud Shell mungkin berhenti berfungsi selama penyebaran yang panjang atau tugas lain yang memakan waktu lama. Pastikan sesi tidak menjadi diam atau tidak aktif. Lihat Batas Penggunaan Cloud Shell.

Antarmuka Cloud Shell

Cloud Shell terutama merupakan antarmuka baris perintah dan memiliki lebih sedikit fitur daripada lingkungan pengembangan terintegrasi seperti Visual Studio Code.

Tidak dapat tersambung ke daemon Docker di Cloud Shell

Cloud Shell menggunakan kontainer untuk menghosting lingkungan shell Anda, sehingga tugas yang mengharuskan menjalankan daemon Docker tidak diizinkan.

Menginstal versi azd yang berbeda di Cloud Shell

Dalam beberapa kasus, mungkin perlu menginstal versi azd yang berbeda daripada versi yang sudah dipakai di Cloud Shell. Untuk melakukan ini di bash:

  1. Jalankan mkdir -p ~/bin untuk memastikan bahwa ~/bin folder ada
  2. Jalankan mkdir -p ~/azd untuk memastikan bahwa folder lokal ~/azd ada
  3. Jalankan curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version> (<version> akan secara default stable, tetapi versi rilis tertentu seperti 1.0.0 juga dapat ditentukan).

Setelah diinstal, versi yang ditautkan secara simbolis di azd diutamakan daripada versi yang ditautkan secara simbolis di ~/bin.

Untuk kembali menggunakan versi azd yang sudah diinstal pada Cloud Shell di bash:

  1. Jalankan rm ~/bin/azd
  2. Jalankan rm -rf ~/azd

Solusi

Gunakan host lain untuk melakukan tugas yang memerlukan daemon docker. Salah satu opsinya adalah menggunakan docker-machine, seperti yang dijelaskan dalam dokumentasi pemecahan masalah Cloud Shell .

Persyaratan CLI Azure Bicep

azd up dan azd provision memerlukan rilis terbaru Azure Bicep CLI. Anda mungkin mendapatkan pesan kesalahan berikut: "Kesalahan: gagal mengkompilasi templat bicep: gagal menjalankan build bicep modul Az PowerShell: kode keluar: 1, stdout: , stderr: PERINGATAN: Rilis Bicep baru tersedia: v0.4.1272."

Solusi

Sebelumnya, Bicep adalah prasyarat untuk menginstal dan menggunakan azd . azd sekarang secara otomatis menginstal Bicep dalam cakupan lokal azd (tidak secara global) dan masalah ini sekarang harus diselesaikan. Namun, jika Anda ingin menggunakan versi yang berbeda, Anda dapat mengatur variabel lingkungan: AZD_BICEP_TOOL_PATH untuk menunjuk ke lokasi versi yang Anda butuhkan.

azd up atau azd provision gagal

Hal-hal kadang-kadang bisa bermasalah dengan azd up atau azd provision. Kesalahan umum meliputi:

  • "Tidak dapat menyediakan sumber daya tertentu di wilayah Azure karena wilayah tersebut berada di luar kapasitas."
  • "Penyedia sumber daya yang relevan tidak ada di wilayah tersebut."

Langkah-langkah pemecahan masalah mungkin berbeda, tergantung pada akar penyebabnya.

Solusi

  1. Buka portal Azure.

  2. Temukan grup sumber daya Anda, yaitu rg-your-environment-name<>.

  3. Pilih Penyebaran untuk mendapatkan informasi selengkapnya.

  4. Verifikasi bahwa Anda menentukan nama lingkungan yang sama dengan nama lingkungan Anda.

  5. Buka tab Tindakan dari repositori GitHub yang terkena dampak dan selidiki file log dalam eksekusi alur untuk informasi selengkapnya.

Untuk sumber daya lain, lihat Memecahkan masalah kesalahan penyebaran Azure umum - Azure Resource Manager.

azd init Memerlukan sudo

Sebelum azd version = azure-dev-cli_0.2.0-beta.1, azd akan membuat folder .azd dengan akses drw-r--r--.

Ini menyebabkan masalah, karena menggunakan versi ini atau versi sebelumnya pada pengaturan Linux apa pun (WSL, ssh-remote, devcontainer, dll.) sudah menyediakan .azd folder dengan mode baca-saja.

Solusi

  1. Hapus folder yang sudah disediakan .azd secara manual:

    rm -r ~/.azd

  2. azd init Jalankan azd untuk membuat folder lagi dengan tingkat akses yang tepat.

azd monitor untuk kontainer pengembangan

azd monitor saat ini tidak didukung jika Anda menggunakan kontainer pengembangan sebagai lingkungan pengembangan Anda.

Tidak dapat mengautentikasi di lingkungan Codespaces

Jika Anda mengalami masalah autentikasi di Codespaces, pastikan templat Dockerfile menyertakan perintah sudo apt-get update && sudo apt-get install xdg-utils. Perintah xdg-utils membuka tab browser yang memungkinkan Anda masuk.

Static Web Apps gagal disebarkan meskipun pesan berhasil

Ada masalah yang diketahui saat menerapkan ke Azure Static Web Apps di mana output default azd up dapat menyatakan tindakan berhasil, tetapi perubahan tidak benar-benar disebarkan. Anda dapat mendiagnosis masalah ini dengan menjalankan azd up perintah dengan --debug bendera diaktifkan. Dalam log output, Anda mungkin melihat pesan berikut:

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

Anda kemungkinan besar mengalami masalah ini saat azd dijalankan dari tindakan GitHub. Sebagai solusinya, setelah Anda membuat situs, salin staticwebapp.config.json ke folder build. Anda dapat mengotomatiskan langkah ini dengan menggunakan hook perintah pra-paket atau pra-penyebaran, yang memungkinkan Anda menjalankan skrip kustom di berbagai titik dalam alur kerja perintah azd.

Tim produk berupaya menyelesaikan masalah ini.

Kesalahan GitHub Actions - "Tidak memiliki izin mendapatkan rahasia pada key vault"

Berbagi nama lingkungan atau grup sumber daya yang sama saat menyediakan sumber daya secara lokal dan di GitHub Actions dapat menghasilkan kesalahan Does not have secrets get permission on key vault.. dari layanan Key Vault. Key Vault tidak mendukung pembaruan izin bertahap melalui Bicep, yang secara efektif berarti alur kerja GitHub Actions menimpa izin Kebijakan Akses pengguna lokal.

Solusi yang direkomendasikan untuk masalah ini adalah menggunakan nama lingkungan terpisah untuk pengembangan lokal dan alur kerja GitHub Actions. Baca selengkapnya tentang menggunakan beberapa lingkungan dengan azd env perintah di halaman FAQ.

Dukungan browser berbasis teks

Browser berbasis teks saat ini tidak didukung oleh azd monitor.

azd pipeline config menggunakan AzDo untuk templat Java di Windows

Anda mungkin mengalami kegagalan saat menjalankan templat AzDo untuk Java dengan azd pipeline config di Windows. Misalnya, Anda telah:

  1. Jalankan yang berikut ini di Windows:

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

  2. Menerima pesan kesalahan berikut:

    Cuplikan layar memperlihatkan kesalahan yang diterima saat menjalankan konfigurasi alur azd dengan AzDo untuk Java di Windows.

Solusi

Ini adalah masalah yang sudah diketahui. Saat kami mengatasi masalah ini, coba perintah berikut:

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 kesalahan setelah pembaruan azd pada Apple Silicon (M1/M2)

Dalam beberapa situasi, meng-upgrade dari versi x86_64 dari azd ke biner ARM64 dapat mengakibatkan kegagalan pada templat yang telah dibangun dengan versi x86_64 dari azd. Ini karena templat menggunakan versi v8-compile-cache yang dapat mencoba memuat bytecode yang dibangun di bawah x86_64 ke dalam proses ARM64.

Untuk memperbaiki masalah ini, tingkatkan v8-compile-cache paket dalam proyek yang terpengaruh:

  1. Ubah direktori ke layanan yang gagal (src/api dalam kasus failed packaging service 'api')
  2. Jalankan npm upgrade v8-compile-cache
  3. Ubah direktori ke akar repositori dan jalankan azd perintah (misalnya azd package atau azd up) lagi

azd pipeline config kegagalan karena Kebijakan Akses Bersyarat

Saat menjalankan azd pipeline config, Anda mungkin menerima kesalahan seperti berikut ini:

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"}

Kesalahan ini terkait dengan pengaktifan Kebijakan Akses Bersyarat pada penyewa Microsoft Entra Anda. Kebijakan tertentu mengharuskan Anda masuk ke platform perangkat yang didukung.

Anda mungkin juga menerima kesalahan ini karena masuk menggunakan mekanisme kode perangkat, yang mencegah ID Microsoft Entra mendeteksi platform perangkat Anda dengan benar.

Solusi

Untuk mengonfigurasi alur kerja, Anda perlu memberikan izin GitHub guna menyebarkan ke Azure atas nama Anda. Otorisasi GitHub dengan membuat Principal Layanan Azure yang disimpan dalam rahasia GitHub bernama AZURE_CREDENTIALS. Pilih host Codespace Anda untuk langkah-langkah:

  1. Pastikan Anda menggunakan perangkat yang tercantum sebagai perangkat yang didukung, sesuai pesan kesalahan.

  2. Jalankan azd auth login ulang dengan bendera --use-device-code=false ditambahkan:

    azd auth login --use-device-code=false

  3. Anda mungkin menerima kesalahan dengan pesan localhost refused to connect setelah masuk. Jika demikian:

    1. Salin URL.
    2. Jalankan curl '<pasted url>' (URL dalam tanda kutip) di terminal Codespace baru.

    Di terminal asli, login sekarang harus berhasil.

  4. Setelah masuk, jalankan ulang azd pipeline config.

Dockerfile yang di-cache digunakan alih-alih Dockerfile saat ini

Saat menggunakan azd di lingkungan pengembangan lokal Anda dengan Docker, Docker dapat menggunakan versi cache Dockerfile Anda alih-alih versi saat ini. Ini menghasilkan penyebaran menggunakan kontainer dengan informasi yang salah.

Solusi

Untuk mengonfigurasi penginstalan Docker lokal Anda, yang digunakan oleh Azure Developer CLI untuk membangun kontainer, Anda perlu mengonfigurasi Docker dengan variabel lingkungan berikut:

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

Anda dapat mengubah azd up untuk menyertakan pengaturan ini:

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

azd pipeline config dukungan

azd pipeline config saat ini tidak didukung dalam DevContainers/VS Code Remote Containers.

Kesalahan fitur penulisan

Fitur azd komposisi hanya tersedia untuk jenis proyek tertentu. Jika Anda mencoba menggunakan perintah tulis seperti azd add atau azd infra gen dalam konteks yang tidak didukung, Anda mungkin mengalami kesalahan berikut.

Proyek yang tidak kompatibel

Jika Anda melihat pesan ERROR: incompatible project saat menjalankan azd add perintah, periksa jenis proyek yang sedang Anda kerjakan. Perintah azd add tidak didukung untuk proyek .NET Aspire atau untuk templat azd yang sudah memiliki folder infra ditentukan. Mencoba menggunakan azd add dengan jenis proyek ini akan mengakibatkan kesalahan seperti:

  • KESALAHAN: proyek yang tidak kompatibel: menemukan host aplikasi Aspire

  • KESALAHAN: proyek yang tidak kompatibel: ditemukan direktori infra dan azure.yaml tanpa sumber daya

    Cuplikan layar memperlihatkan kesalahan proyek .NET Aspire yang tidak kompatibel.

    Cuplikan layar memperlihatkan kesalahan infrastruktur proyek yang tidak kompatibel.

Proyek tidak berisi infrastruktur untuk menghasilkan

Kesalahan ERROR: this project does not contain any infrastructure to generate terjadi ketika:

  • Anda menjalankan azd infra gen tanpa sumber daya kompose yang ditentukan dalam proyek Anda.
  • Dalam proyek .NET Aspire, kesalahan ini juga dapat muncul jika azd tidak dapat mendeteksi Aspire App Host di direktori saat ini.

Untuk mengatasi kesalahan ini, gunakan azd add untuk menambahkan sumber daya baru sebelum menjalankan azd infra gen atau memastikan proyek .NET Aspire Anda terstruktur dengan benar.

Cuplikan layar yang menunjukkan kesalahan infrastruktur.

Kesalahan dalam mengatasi sumber daya Azure

Perintah azd show <name> mungkin gagal dengan kesalahan: ERROR: resolving '<name>': AZURE_RESOURCE_<NAME>_ID is not set as an output variable. Ini bisa terjadi karena sejumlah alasan:

  • Sumber daya <name> tidak ada dalam simpul sumber daya: azure.yaml.
  • Sumber daya <name> belum disediakan.

Cuplikan layar memperlihatkan kesalahan sumber daya azure.

Solusi

Jalankan azd up untuk menyediakan sumber daya. Anda mungkin perlu menjalankan azd infra gen terlebih dahulu untuk menghasilkan pembaruan Bicep terbaru termasuk sumber daya <name>, lalu jalankan azd up.

Dukungan metrik langsung untuk Python

Metrik Langsung (azd monitor --live) saat ini tidak didukung untuk aplikasi Python. Untuk informasi selengkapnya, lihat Metrik Langsung: Memantau dan mendiagnosis dengan latensi 1 detik.

Membuat masalah GitHub untuk meminta bantuan

Sebuah gambar logo GitHub.

Azure Developer CLI dan ekstensi Azure Developer CLI Visual Studio Code menggunakan Masalah GitHub untuk melacak bug dan permintaan fitur. Silakan cari masalah yang ada sebelum mengajukan masalah baru untuk menghindari duplikat.

Untuk bantuan dan pertanyaan tentang penggunaan proyek ini, silakan lihat wiki kami untuk menggunakan Azure Developer CLI dan dokumen KONTRIBUSI kami jika Anda ingin berkontribusi.

  • Last updated on