Поделиться через

Устранение неполадок с интерфейсом командной строки разработчика Azure

В этой статье приведены решения распространенных проблем, которые могут возникнуть при использовании интерфейса командной строки разработчика Azure (azd).

Получение справки и предоставление отзывов

Если вы не можете найти то, что вы ищете в этой статье или хотите предоставить отзыв, вы можете отправить вопросы в обсуждениях CLI разработчика Azure.

Вы также можете сообщить об ошибках, открыв GitHub Issues в репозитории GitHub для разработчиков Azure CLI.

Использование коммутатора --debug

Если вы столкнулись с непредвиденной проблемой при работе с azd, выполните команду с переключателем --debug, чтобы включить дополнительный вывод отладки и диагностики.

azd up --debug

Вы также можете отправить выходные данные отладки в локальный текстовый файл для улучшения удобства использования. Этот подход позволяет другим системам мониторинга получать отладку, а также может быть полезно при отправке проблемы на GitHub.

Это важно

Перед отправкой журналов отладки на GitHub или сохранением их в других системах диагностики обязательно удалите любую конфиденциальную информацию.

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

.azure Каталог

Интерфейс командной строки разработчика Azure предполагает, что все каталоги, хранящиеся в каталоге .azure , являются средами Azure Developer CLI. Не запускайте команды Командной строки разработчика Azure из домашнего каталога пользователя, на котором установлен Azure CLI.

Не выполнен вход в Azure или срок действия токена истек в Visual Studio

После запуска azd init -t <template-name> в Visual Studio вы получите следующую ошибку: "Чтобы получить доступ к удаленному репозиторию, необходимо повторно выполнить проверку подлинности приложения Visual StudioOAuth".

Решение

Запустите 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 :

Поддержка Docker в Cloud Shell

Cloud Shell не поддерживает выполнение docker build или run команд, так как управляющая программа Docker не запущена. Дополнительные сведения см. в разделе "Устранение неполадок Cloud Shell".

Тайм-аут Cloud Shell

Cloud Shell может завершить работу из-за тайм-аута во время длительного развертывания или других длительно выполняющихся задач. Убедитесь, что сеанс не становится неактивным. См. ограничения использования Cloud Shell.

Интерфейс Cloud Shell

Cloud Shell является главным образом интерфейсом командной строки и имеет меньше функций, чем интегрированная среда разработки, например Visual Studio Code.

Не удается подключиться к управляющей программе Docker в Cloud Shell

Cloud Shell использует контейнер для размещения среды оболочки, поэтому задачи, требующие запуска управляющей программы Docker, не допускаются.

Установка другой версии azd в Cloud Shell

В некоторых случаях может потребоваться установить другую версию azd , чем версия, уже используемая в Cloud Shell. Для этого в 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.

Чтобы вернуться к использованию версии azd, уже установленной в Cloud Shell под bash:

  1. Запуск rm ~/bin/azd
  2. Запуск rm -rf ~/azd

Решение

Используйте другой узел для выполнения задач, требующих управляющей программы Docker. Один из вариантов — использовать docker-machine, как описано в документации по устранению неполадок Cloud Shell .

Требование интерфейса командной строки Azure Bicep

azd up и azd provision нуждаются в последней версии Azure Bicep CLI. Вы можете получить следующее сообщение об ошибке: "Ошибка: не удалось скомпилировать шаблон bicep: ошибка при выполнении команды сборки модуля Az PowerShell bicep: код выхода: 1, stdout: , stderr: ПРЕДУПРЕЖДЕНИЕ: доступна новая версия Bicep: v0.4.1272".

Решение

Ранее наличие Bicep являлось обязательным условием для установки и использования azd . azd теперь автоматически устанавливает Bicep в локальной azd области (не глобально) и эта проблема должна быть устранена. Однако если вы хотите использовать другую версию, можно задать переменную среды: 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 открывает вкладку браузера, которая позволяет войти в систему.

Не удается развернуть статические веб-приложения, несмотря на сообщение об успешном выполнении

При развертывании в Azure Static Web Apps существует известная проблема, когда выходные данные по умолчанию могут указывать на успешность выполнения действия, но изменения фактически не развертываются. Эту проблему можно диагностировать, выполнив azd up команду с включенным флагом --debug . В выходных журналах может отображаться следующее сообщение:

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

Скорее всего, эта проблема возникает при azd выполнении из GitHub Actions. В качестве обходного решения после сборки сайта скопируйте staticwebapp.config.json в папку сборки. Этот шаг можно автоматизировать с помощью перехватчика команд prepackage или predeploy command hook, что позволяет выполнять пользовательские скрипты на различных этапах рабочих процессов команды azd.

Команда разработчиков работает над решением этой проблемы.

Ошибка GitHub Actions — "Нет разрешения на получение секретов из хранилища ключей"

Совместное использование одного и того же имени среды или группы ресурсов при локальной подготовке ресурсов и в GitHub Actions может привести к ошибке Does not have secrets get permission on key vault.. из службы Key Vault. Key Vault не поддерживает добавочные обновления разрешений через Bicep, что фактически означает, что рабочий процесс GitHub Actions перезаписывает разрешения политики доступа локального пользователя.

Рекомендуемое решение этой проблемы — использовать отдельные имена сред для локальных рабочих процессов разработки и GitHub Actions. Дополнительные сведения об использовании нескольких сред с командой azd env на странице часто задаваемых вопросов.

Поддержка браузера на основе текста

Текстовые браузеры в настоящее время не поддерживаются azd monitor.

azd pipeline config использование шаблонов AzDo для Java в Windows

При запуске azd pipeline config с шаблонами AzDo для Java в Windows может возникнуть сбой. Например, вы:

  1. Выполните следующие действия в Windows:

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

  2. Получено следующее сообщение об ошибке:

    Снимок экрана: ошибка, полученная при запуске azd pipeline config с AzDo для Java в Windows.

Решение

Это известная проблема. При устранении этой проблемы попробуйте выполнить следующую команду:

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 сбой после обновления azd на Apple Silicon (M1/M2)

В некоторых ситуациях обновление с 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 правильно обнаруживать платформу вашего устройства.

Решение

Чтобы настроить рабочий процесс, вам нужно предоставить GitHub разрешение на развертывание в Azure от вашего имени. Авторизация GitHub путем создания субъекта-службы Azure, хранящегося в секрете GitHub с именем AZURE_CREDENTIALS. Выберите узел Codespace для выполнения шагов:

  1. Убедитесь, что вы работаете на устройстве, указанном как поддерживаемое, в сообщении об ошибке.

  2. Повторно выполните команду azd auth login с добавленным флагом --use-device-code=false :

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

  3. После входа в систему может появиться сообщение localhost refused to connect об ошибке. Если да:

    1. Скопируйте URL-адрес.
    2. Запустите curl '<pasted url>' (URL-адрес в кавычках) в новом терминале Codespaces.

    В исходном терминале вход должен быть успешным.

  4. После входа повторно выполните команду azd pipeline config.

Кэшированный файл dockerfile используется вместо текущего dockerfile

При использовании azd в локальной среде разработки с Docker Docker можно использовать кэшированную версию Dockerfile вместо текущей версии. Это приводит к развертыванию с использованием контейнера с неверными сведениями.

Решение

Чтобы настроить локальную установку Docker, которая используется Azure Developer CLI для сборки контейнера, необходимо настроить 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.

Ошибки функции Compose

Функция azd создания доступна только для определенных типов проектов. Если вы пытаетесь использовать команды создания, например azd add или azd infra gen в неподдерживаемом контексте, могут возникнуть следующие ошибки.

Несовместимый проект

Если при выполнении azd add команды отображается ERROR: incompatible project сообщение, проверьте тип проекта, с которым вы работаете. Команда azd add не поддерживается для проектов .NET Aspire или для azd шаблонов, которые уже определены в папке infra . Попытка использования azd add с этими типами проектов приведет к ошибкам, таким как:

  • ОШИБКА: несовместимый проект: обнаружен хост приложения Aspire

  • ОШИБКА: несовместимый проект: найден каталог infra и azure.yaml без ресурсов

    Снимок экрана: несовместимая ошибка проекта .NET Aspire.

    Снимок экрана: ошибка несовместимой инфраструктуры проекта.

Проект не содержит инфраструктуры для создания

Ошибка ERROR: this project does not contain any infrastructure to generate возникает, когда:

  • Вы выполняете azd infra gen без определенных в вашем проекте ресурсов Compose.
  • В проектах .NET Aspire эта ошибка также может появиться, если azd не удается обнаружить хост приложения Aspire в текущем каталоге.

Чтобы устранить эту ошибку, используйте azd add для добавления новых ресурсов перед запуском azd infra gen или убедитесь, что проект .NET Aspire структурирован правильно.

Снимок экрана: ошибка инфраструктуры.

Ошибка при обработке ресурса Azure

Команда azd show <name> может завершиться ошибкой: ERROR: resolving '<name>': AZURE_RESOURCE_<NAME>_ID is not set as an output variable. Это может произойти по нескольким причинам:

  • Ресурс <name> не существует в узле ресурсов azure.yaml.
  • Ресурс <name> еще не подготовлен.

Снимок экрана: ошибка ресурса Azure.

Решение

Запустите azd up , чтобы подготовить ресурсы. Сначала может потребоваться запустить azd infra gen, чтобы сгенерировать обновленный Bicep, включая ресурс <name>, затем выполнить azd up.

Поддержка динамических метрик для Python

Динамические метрики (azd monitor --live) в настоящее время не поддерживаются для приложений Python. Дополнительные сведения см. в статье Динамические метрики: мониторинг и диагностика с задержкой в 1 секунду.

Создание задачи в GitHub для запроса помощи

Изображение логотипа GitHub.

Azure Developer CLI и расширение Azure Developer CLI для Visual Studio Code используют обсуждения GitHub для отслеживания ошибок и запросов на добавление функций. Выполните поиск существующих проблем перед отправкой новых проблем, чтобы избежать дубликатов.

Чтобы получить справку и вопросы об использовании этого проекта, ознакомьтесь с нашим вики-сайтом по использованию Интерфейса командной строки разработчика Azure и нашим документом CONTRIBUTEING , если вы хотите внести свой вклад.

  • Last updated on