Az Azure Developer CLI hibaelhárítása

Ez a cikk az Azure Developer CLI (azd) használatakor felmerülő gyakori problémák megoldását ismerteti.

Segítség kérése és visszajelzés küldése

Ha nem találja, amit ebben a cikkben keres, vagy visszajelzést szeretne küldeni, kérdéseket tehet fel az Azure Developer CLI-vitafórumokban.

A hibák bejelentéséhez nyissa meg a GitHub-problémákat az Azure Developer CLI GitHub-adattárában.

A --debug kapcsoló használata

Ha váratlan problémával találkozik a azd használata során, futtassa újra a parancsot a --debug kapcsolóval, hogy több hibakeresési és diagnosztikai kimenetet engedélyezzen.

azd up --debug

A hibakeresési kimenetet egy helyi szövegfájlba is elküldheti a jobb használhatóság érdekében. Ez a megközelítés lehetővé teszi, hogy a többi monitorozási rendszer feldolgozza a hibakeresést, és hasznos lehet, amikor GitHubon jelentünk be egy problémát.

Fontos

A Hibakeresési naplók GitHubon való elküldésekor vagy más diagnosztikai rendszerekbe való mentésekor ügyeljen arra, hogy minden bizalmas információt újra kiírjon.

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

A .azure könyvtár

Az Azure Developer CLI feltételezi, hogy a .azure címtárban tárolt könyvtárak Azure Developer CLI-környezetek. Ne futtasson Azure Developer CLI-parancsokat egy olyan felhasználó kezdőkönyvtárából, aki telepítette az Azure CLI-t.

Nincs bejelentkezve az Azure-ba, vagy lejárt a token a Visual Studio-ban.

A Visual Studióban való futtatás azd init -t <template-name> után a következő hibaüzenet jelenik meg: "A távoli hozzáféréshez ehhez az adattárhoz újra be kell szereznie az OAuth-alkalmazást Visual Studio."

Megoldás

Futtassa a azd auth login parancsot a hozzáférési jogkivonat frissítéséhez.

A frissített Azure-fiókengedélyek nem frissülnek azd

Alapértelmezés szerint azd gyorsítótárazza az Azure-beli hitelesítő adatokat és engedélyeket. Ha az Azure-fiókja új szerepkörökhöz és engedélyekhez van rendelve, vagy több előfizetéshez van hozzáadva, előfordulhat, hogy ezek a módosítások nem jelennek meg azonnal a dokumentumban azd. A probléma megoldásához jelentkezzen ki, majd jelentkezzen be újra azd a következő parancsokkal:

azd auth logout

azd auth login

Kövesse a parancsban található utasításokat a azd auth login bejelentkezési folyamat befejezéséhez és a gyorsítótárazott hitelesítő adatok frissítéséhez.

A Cloud Shell korlátozásai azd

A Cloud Shellben való futtatásnak azd van néhány korlátozása:

Docker-támogatás a Cloud Shellben

A Cloud Shell nem támogatja a docker build vagy run parancsok futtatását, mert a docker démon nem fut. További információkért lásd a Cloud Shell hibaelhárítását.

A Cloud Shell időtúllépése

A Cloud Shell időtúllépést okozhat egy hosszú üzembe helyezés vagy más hosszan futó feladat során. Győződjön meg arról, hogy a munkamenet nem válik inaktívvá. Lásd a Cloud Shell használati korlátait.

Cloud Shell-felület

A Cloud Shell elsősorban parancssori felület, és kevesebb funkcióval rendelkezik, mint egy integrált fejlesztési környezet, például a Visual Studio Code.

Nem lehet csatlakozni a Docker-démonhoz a Cloud Shellben

A Cloud Shell tárolóval üzemelteti a rendszerhéjkörnyezetet, így a Docker-démon futtatását igénylő feladatok nem engedélyezettek.

Az azd különböző verziójának telepítése a Cloud Shellben

Bizonyos esetekben előfordulhat, hogy a Cloud Shellben már használt verziótól eltérő verziót azd kell telepíteni. Ehhez a bash-ben:

  1. Futtassa az mkdir -p ~/bin-t, hogy biztosítsa a ~/bin mappa jelenlétét.
  2. Futtassa mkdir -p ~/azd, hogy ellenőrizze, van-e helyi ~/azd mappa.
  3. Futtatás curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version> (<version> alapértelmezés szerint, stable de egy adott kiadású verzió 1.0.0 is megadható).

A telepítés után a azd-ban szimbolikusan csatolt verzió elsőbbséget élvez a ~/bin-ben szimbolikusan csatolt verzióval azd szemben.

Ha vissza szeretne térni a Cloud Shellben már telepített verzió azd használatára a bashben:

  1. Az rm ~/bin/azd parancs futtatása
  2. Az rm -rf ~/azd parancs futtatása

Megoldás

Használjon másik gazdagépet a docker-démont igénylő feladatok végrehajtásához. Az egyik lehetőség a Docker-gép használata a Cloud Shell hibaelhárítási dokumentációjában leírtak szerint.

Azure Bicep CLI-követelmény

azd up és azd provision az Azure Bicep CLI legújabb kiadását követelik meg. A következő hibaüzenet jelenhet meg: "Hiba: nem sikerült lefordítani a bicep-sablont: nem sikerült futtatni az Az PowerShell-modul bicep-buildjének futtatását: kilépési kód: 1, stdout: , stderr: FIGYELMEZTETÉS: Egy új Bicep-kiadás érhető el: 0.4.1272-es verzió."

Megoldás

Korábban a Bicep előfeltétele volt a azd telepítésének és használatának. azd Most automatikusan telepíti a Bicep-et a helyi azd hatókörön belül (nem globálisan), és ezt a problémát most meg kell oldani. Ha azonban másik verziót szeretne használni, beállíthatja a környezeti változót, AZD_BICEP_TOOL_PATH hogy a szükséges verzió helyére mutasson.

azd up vagy azd provision sikertelen

A dolgok néha félre mennek a azd up vagy azd provision esetén. Gyakori hibák a következők:

  • "Nem lehet bizonyos erőforrásokat kiépni egy Azure-régióban, mert a régió kapacitáson kívül van."
  • "A releváns erőforrás-szolgáltató nem található ebben a régióban."

A hibaelhárítási lépések a kiváltó októl függően eltérhetnek.

Megoldás

  1. Nyissa meg az Azure Portalt.

  2. Keresse meg az erőforráscsoportot, amely rg-<a-környezete-neve>.

  3. További információkért válassza a Telepítések lehetőséget.

  4. Ellenőrizze, hogy a környezet nevével megegyező környezeti nevet adott-e meg.

  5. Lépjen az érintett GitHub-adattár Műveletek lapjára, és további információért vizsgálja meg a folyamatfuttatás naplófájlját.

Egyéb erőforrásokért lásd: Gyakori Azure-telepítési hibák elhárítása – Azure Resource Manager.

azd init Megköveteli sudo

Korábban azd version = azure-dev-cli_0.2.0-beta.1azd létrehozott egy .azd mappát, amelyhez drw-r--r-- hozzáférés tartozik.

Ez problémát okoz, mivel a linuxos beállítás (WSL, ssh-remote, devcontainer stb.) ezen vagy korábbi verzióinak használata már tartalmaz írásvédett .azd módban lévő mappát.

Megoldás

  1. Törölje manuálisan a már megadott .azd mappát:

    rm -r ~/.azd

  2. Futtassa azd init a azd segítségével, hogy ismét létrehozza a mappát a megfelelő hozzáférési szintekkel.

azd monitor fejlesztői tárolóhoz

azd monitor jelenleg nem támogatott, ha fejlesztési környezetként fejlesztési tárolót használ.

Nem lehet hitelesítést végezni Codespaces-környezetekben

Ha hitelesítési problémákat tapasztal a Codespacesben, győződjön meg arról, hogy a Dockerfile sablon tartalmazza a sudo apt-get update && sudo apt-get install xdg-utils parancsokat. A xdg-utils parancs megnyitja a böngészőlapot, amely lehetővé teszi a bejelentkezést.

A statikus webalkalmazások üzembe helyezése sikertelen volt a sikeres üzenet ellenére

Ismert probléma áll fenn az Azure Static Web Appsben való üzembe helyezéskor, amelyben az alapértelmezett azd up kimenet azt jelezheti, hogy a művelet sikeres volt, de a módosítások ténylegesen nem lettek üzembe helyezve. Ezt a problémát diagnosztizálhatja úgy, hogy a azd up parancsot engedélyezve futtatja a --debug jelölőt. A kimeneti naplókban a következő üzenet jelenhet meg:

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

Ez a probléma valószínűleg akkor jelenik meg, amikor a azd egy GitHub-műveletből van futtatva. Kerülő megoldásként a webhely létrehozása után másolja staticwebapp.config.json a buildmappába. Ezt a lépést automatizálhatja egy előre csomagolt vagy előre üzembe helyezési parancshook használatával, amely lehetővé teszi egyéni szkriptek végrehajtását az azd parancs munkafolyamatainak különböző pontjain.

A termékcsapat dolgozik a probléma megoldásán.

GitHub Actions-hiba – "Nincs titkos kulcs a key vaulthoz való hozzáféréshez"

Ha ugyanazt a környezet- vagy erőforrás csoportnevet használja az erőforrások helyi és a GitHub Actionsben történő kiépítésekor, az a Key Vault szolgáltatás hibáját okozhatja. A Key Vault nem támogatja a Bicep növekményes engedélyfrissítéseit, ami gyakorlatilag azt jelenti, hogy a GitHub Actions munkafolyamat felülírja a helyi felhasználó hozzáférési szabályzatának engedélyeit.

A probléma ajánlott megoldása a helyi fejlesztési és GitHub Actions-munkafolyamatok különálló környezetneveinek használata. További információt találhat a több környezet használatáról a azd env parancs használatával kapcsolatban a GYIK oldalon.

Szövegalapú böngészőtámogatás

Jelenleg a azd monitor nem támogatja a szövegalapú böngészőket.

azd pipeline config AzDo használata Java-sablonokhoz Windows rendszeren

Hiba léphet fel az AzDo for Java-sablonok Windows rendszeren való futtatásakor azd pipeline config . Például, neked van:

  1. Futtassa a következőket Windows rendszeren:

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

  2. A következő hibaüzenetet kapta:

    Képernyőkép az azd folyamatkonfiguráció windowsos AzDo for Java-val való futtatásakor kapott hibáról.

Megoldás

Ez egy ismert probléma. A probléma megoldása közben próbálkozzon a következő paranccsal:

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 hiba az Apple Silicon (M1/M2) frissítése azd után

Bizonyos esetekben az ARM64 bináris x86_64 verziójáról azd való frissítés meghiúsulhat a x86_64 verziójával azdkészült sablonok esetében. Ennek az az oka, hogy a sablon az v8-compile-cache verziót használja, amely megpróbálhatja az x86_64-re fordított bájtkódot betölteni egy ARM64-folyamatba.

A probléma megoldásához frissítse a v8-compile-cache csomagot az érintett projektben:

  1. Módosítsa a könyvtárat arra a szolgáltatásra, amely nem sikerült (src/api a következő esetén failed packaging service 'api': )
  2. Az npm upgrade v8-compile-cache parancs futtatása
  3. Módosítsa a könyvtárat az adattár gyökerére, és futtassa újra a azd parancsot (például azd package vagy azd up)

azd pipeline config hiba a feltételes hozzáférési szabályzat miatt

Futtatáskor azd pipeline configaz alábbihoz hasonló hibaüzenet jelenhet meg:

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

Ez a hiba a Microsoft Entra-bérlő feltételes hozzáférési házirendjeinek engedélyezésével áll kapcsolatban. Az adott szabályzathoz egy támogatott eszközplatformra kell bejelentkezni.

Előfordulhat, hogy ezt a hibát azért is kapja, mert az eszközkód mechanizmus használatával jelentkezik be, ami megakadályozza, hogy a Microsoft Entra ID megfelelően észlelje az eszközplatformot.

Megoldás

A munkafolyamat konfigurálásához engedélyeznie kell, hogy a rendszer az Ön nevében üzembe helyezze a GitHubot az Azure-ban. Engedélyezze a GitHubot egy GitHub-titkos AZURE_CREDENTIALSkódban tárolt Azure Service Principal létrehozásával. Válassza ki a Codespace-gazdagépet a következő lépésekhez:

  1. A hibaüzenet alapján győződjön meg arról, hogy támogatottként felsorolt eszközön fut.

  2. Futtassa újra azd auth login, a következő módon kiegészítve: --use-device-code=false.

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

  3. Bejelentkezés után hibaüzenet localhost refused to connect jelenhet meg. Ha igen:

    1. URL másolása.
    2. Futtassa curl '<pasted url>' (URL-cím idézőjelekben) egy új Codespaces-terminálban.

    Az eredeti terminálban a bejelentkezésnek most sikeresnek kell lennie.

  4. Bejelentkezés után futtassa újra a következőt azd pipeline config:

Az aktuális Dockerfile helyett gyorsítótárazott Dockerfile van használatban

Ha a helyi fejlesztési környezetben használja azd a Dockert, a Docker a Docker-fájl gyorsítótárazott verzióját használhatja az aktuális verzió helyett. Ez azt eredményezi, hogy az üzembe helyezés helytelen adatokat tartalmazó tárolót használ.

Megoldás

A tároló létrehozásához az Azure Developer CLI által használt helyi Docker-telepítés konfigurálásához a Következő környezeti változókkal kell konfigurálnia a Dockert:

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

Módosíthatja a azd up, hogy tartalmazza ezeket a beállításokat:

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

azd pipeline config támogatás

azd pipeline config jelenleg nem támogatott a DevContainers/VS Code Távoli tárolókban.

Hiba az Azure-erőforrás feloldása során

A parancs azd show <name> a következő hibával hiúsulhat meg: ERROR: resolving '<name>': AZURE_RESOURCE_<NAME>_ID is not set as an output variable. Ez több okból is történhet:

  • Az <name> erőforrás nem létezik az erőforrások csomópontján belül: azure.yaml.
  • Az erőforrás <name> még nincs előirányozva.

Képernyőkép az Azure-erőforrás hibájáról.

Megoldás

Győződjön meg arról, hogy az infrastruktúrafájljai határozzák meg az erőforrást, és elérhetővé teszik a szükséges kimeneteket. Ezután futtassa a azd up parancsot az erőforrások kiépítéséhez.

Élő metrikák támogatása a Pythonhoz

Az élő metrikák (azd monitor --live) jelenleg nem támogatottak a Python-alkalmazásokban. További információk: Élő metrikák: Monitorozás és diagnosztika 1 másodperces késéssel.

GitHub-probléma létrehozása segítségkéréshez

A GitHub logójának képe.

Az Azure Developer CLI és az Azure Developer CLI Visual Studio Code bővítmény a GitHub Issues használatával követi nyomon a hibákat és a funkciókéréseket. Az ismétlődések elkerülése érdekében az új problémák bejelentése előtt keressen rá a meglévő problémákra .

Ha segítségre van szüksége a projekt használatával kapcsolatban, tekintse meg wikinket az Azure Developer CLI használatához, és ha hozzá szeretne járulni, tekintse meg a közreműködői dokumentumunkat .

  • Last updated on