Compartilhar via

Solucionar problemas da Azure Developer CLI

Este artigo fornece soluções para problemas comuns que podem surgir ao usar a Azure Developer CLI (azd).

Obter ajuda e fazer comentários

Se você não conseguir encontrar o que está procurando neste artigo ou quiser adicionar comentários, poderá postar perguntas nas Discussões sobre a Azure Developer CLI.

Você também pode relatar bugs abrindo problemas do GitHub no repositório GitHub da Azure Developer CLI.

Usando a opção --debug

Se você encontrar um problema inesperado ao usar azd, execute novamente o comando com a opção --debug para habilitar a saída de depuração e diagnóstico.

azd up --debug

Você também pode enviar a saída de depuração para um arquivo de texto local a fim de melhorar a usabilidade. Essa abordagem permite que outros sistemas de monitoramento processem a depuração e também podem ser úteis ao apresentar um problema no GitHub.

Importante

Certifique-se de redigir informações confidenciais ao enviar logs de depuração no GitHub ou salvá-los em outros sistemas de diagnóstico.

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

Diretório do .azure

O Azure Developer CLI pressupõe que todos os diretórios armazenados em .azure sejam ambientes do Azure Developer CLI. Não execute comandos do Azure Developer CLI no diretório inicial de um usuário que tenha o Azure CLI instalado.

Não conectado ao Azure ou token expirado no Visual Studio

Depois de executar azd init -t <template-name> no Visual Studio, você receberá o seguinte erro: "Para acessar remotamente este repositório, você deve reautorizar o aplicativo OAuth Visual Studio".

Solução

Execute azd auth login para atualizar o token de acesso.

As permissões de conta do Azure não são atualizadas em azd

Por padrão, azd armazena em cache suas credenciais e permissões do Azure. Se sua conta do Azure receber novas funções e permissões ou for adicionada a mais assinaturas, essas alterações poderão não ser refletidas imediatamente em azd. Para resolver esse problema, faça logoff e faça logon em azd novamente usando os seguintes comandos:

azd auth logout

azd auth login

Siga os prompts do comando azd auth login para concluir o processo de entrada e atualizar suas credenciais armazenadas em cache.

Limitações do Cloud Shell para azd

Há algumas limitações para execução do azd no Cloud Shell:

Suporte do Docker no Cloud Shell

O Cloud Shell não dá suporte à execução de comandos docker build ou run porque o daemon do docker não está em execução. Para obter mais informações, consulte a solução de problemas do Cloud Shell.

Tempo limite do Cloud Shell

O Cloud Shell pode atingir o tempo limite durante uma implantação longa ou outras tarefas de execução longa. Verifique se a sessão não fica ociosa. Consulte os limites de uso do Cloud Shell.

Interface do Cloud Shell

O Cloud Shell é principalmente uma interface de linha de comando e tem menos recursos do que um ambiente de desenvolvimento integrado, como o Visual Studio Code.

Não é possível se conectar ao daemon do Docker no Cloud Shell

O Cloud Shell usa um contêiner para hospedar seu ambiente de shell, portanto, as tarefas que exigem a execução do daemon do Docker não são permitidas.

Instalar uma versão diferente do azd no Cloud Shell

Em alguns casos, pode ser necessário instalar uma versão diferente da versão azd já em uso no Cloud Shell. Para fazer isso no Bash:

  1. Execute mkdir -p ~/bin para garantir que a pasta ~/bin esteja presente
  2. Execute mkdir -p ~/azd para garantir que uma pasta local ~/azd esteja presente
  3. Executar curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version> (<version> seria stable por padrão, mas uma versão lançada específica como 1.0.0 também pode ser especificada).

Depois de instalada, a versão de azd simbolicamente vinculada tem ~/bin precedência sobre a versão de azd simbolicamente vinculada em /usr/local/bin.

Para reverter para usar a versão do azd já instalada no Cloud Shell no Bash:

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

Solução

Use outro host para executar tarefas que exigem o daemon do Docker. Uma opção é usar o docker-machine, conforme descrito na documentação de solução de problemas do Cloud Shell.

Requisito do Azure Bicep CLI

azd up e azd provision exija a versão mais recente do Azure Bicep CLI. Você pode receber a seguinte mensagem de erro: "Erro: falha ao compilar o modelo bicep: falha ao executar o build bicep do módulo do Az PowerShell: código de saída: 1, stdout: , stderr: AVISO: Uma nova versão do Bicep está disponível: v0.4.1272."

Solução

Anteriormente, o Bicep era um pré-requisito para instalar e usar azd . azd agora instala automaticamente o Bicep no escopo local azd (não globalmente) e esse problema agora deve ser resolvido. No entanto, se você quiser usar uma versão diferente, poderá definir a variável de ambiente: AZD_BICEP_TOOL_PATH para apontar para o local da versão necessária.

azd up ou azd provision falha

Às vezes, podem ocorrer erros com azd up ou azd provision. Os erros comuns incluem:

  • "Não é possível provisionar determinados recursos em uma região do Azure porque a região está fora de capacidade."
  • "O provedor de recursos relevante não está presente nessa região."

As etapas de solução de problemas podem ser diferentes, dependendo da causa raiz.

Solução

  1. Acesse o portal do Azure.

  2. Localize o grupo de recursos, que é rg-<your-environment-name>.

  3. Selecione Implantações para obter mais informações.

  4. Verifique se você especificou um nome de ambiente correto.

  5. Vá para a guia Ações do repositório do GitHub afetado e investigue o arquivo de log na execução do pipeline para obter mais informações.

Para outros recursos, confira Solução de erros comuns de implantação do Azure - Azure Resource Manager.

azd init requer sudo

Antes azd version = azure-dev-cli_0.2.0-beta.1, azd criaria uma pasta .azd com acesso drw-r--r--.

Isso causa um problema, pois usar essa ou qualquer versão anterior em qualquer configuração do Linux (WSL, ssh-remote, devcontainer etc.) já fornece uma pasta .azd com modo somente leitura.

Solução

  1. Exclua manualmente a pasta .azd já fornecida:

    rm -r ~/.azd

  2. Execute azd init para azd para criar a pasta novamente com os níveis de acesso corretos.

azd monitor para contêiner de desenvolvimento

azd monitor não é suportado no momento se você usar um contêiner de desenvolvimento como seu ambiente de desenvolvimento.

Não é possível autenticar em ambientes de Codespaces

Se você estiver enfrentando problemas de autenticação em Codespaces, verifique se o Dockerfile de modelo inclui os comandos sudo apt-get update && sudo apt-get install xdg-utils. O comando xdg-utils abre uma guia do navegador que permite que você se registre.

Os Aplicativos Web Estáticos não são implantados apesar da mensagem de êxito

Existe um problema conhecido ao implantar nos Aplicativos Web Estáticos do Azure em que a saída padrão azd up pode indicar que a ação foi bem-sucedida, mas as alterações não foram realmente implantadas. Você pode diagnosticar esse problema executando o comando azd up com o sinalizador --debug habilitado. Nos logs de saída, você pode ver a seguinte mensagem:

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

É mais provável que você encontre esse problema quando azd for executado a partir de uma ação do GitHub. Como solução alternativa, depois de compilar seu site, copie staticwebapp.config.json para a pasta de build. Você pode automatizar essa etapa usando um gancho de comando pré-empacotamento ou pré-implantação, que permite executar scripts personalizados em vários pontos nos fluxos de trabalho de comando do azd.

A equipe de produtos está trabalhando para resolver esse problema.

Erro do GitHub Actions – "Não tem segredos para obter permissão no cofre de chaves"

Compartilhar o mesmo nome de ambiente ou grupo de recursos ao provisionar recursos localmente e no GitHub Actions pode produzir o erro Does not have secrets get permission on key vault.. do serviço do Key Vault. O Key Vault não dá suporte a atualizações de permissões incrementais por meio do Bicep, o que significa efetivamente que o fluxo de trabalho do GitHub Actions substitui as permissões da Política de Acesso do usuário local.

A solução recomendada para esse problema é usar nomes de ambiente separados para fluxos de trabalho de desenvolvimento local e do GitHub Actions. Leia mais sobre como usar vários ambientes com o comando azd env na página de perguntas frequentes.

Suporte ao navegador baseado em texto

Atualmente, navegadores baseados em texto não são compatíveis com azd monitor.

azd pipeline config usando o AzDo para modelos Java no Windows

Você pode encontrar uma falha ao executar azd pipeline config com modelos do AzDo para Java no Windows. Por exemplo, você:

  1. Executou o seguinte no Windows:

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

  2. Recebeu o seguinte erro:

    Captura de tela mostrando o erro recebido ao executar a configuração do pipeline do azd com o AzDo para Java no Windows.

Solução

Esse é um problema conhecido. Enquanto resolvemos esse problema, tente o seguinte comando:

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 falha após a atualização azd no Apple Silicon (M1/M2)

Em algumas situações, a atualização da versão x86_64 de azd para um binário ARM64 pode resultar em falhas para modelos que foram criados com a versão x86_64 de azd. Isso ocorre porque o modelo usa uma versão da v8-compile-cache que pode tentar carregar o código de byte compilado em x86_64 em um processo ARM64.

Para corrigir esse problema, atualize o pacote v8-compile-cache no projeto afetado:

  1. Alterar o diretório para o serviço que falhou (src/api no caso de failed packaging service 'api')
  2. Execute npm upgrade v8-compile-cache
  3. Altere o diretório para a raiz do repositório e execute o comando azd (por exemplo, azd package ou azd up) novamente

azd pipeline config falha devido à Política de Acesso Condicional

Ao executar azd pipeline config, você pode receber um erro como o seguinte:

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

Esse erro está relacionado à habilitação do locatário do Microsoft Entra das Políticas de Acesso Condicional. A política específica exige que você esteja conectado a uma plataforma de dispositivo com suporte.

Você também pode estar recebendo esse erro por estar conectado usando o mecanismo de código do dispositivo, o que impede que a ID do Microsoft Entra detecte a plataforma do dispositivo corretamente.

Solução

Para configurar o fluxo de trabalho, você precisa dar permissão ao GitHub para implantar no Azure em seu nome. Autorize o GitHub criando uma Entidade de Serviço do Azure armazenada em um segredo do GitHub chamado AZURE_CREDENTIALS. Selecione o host do Codespace para obter etapas:

  1. Verifique se você está em execução em um dispositivo listado como compatível, de acordo com a mensagem de erro.

  2. Execute novamente azd auth login com o sinalizador --use-device-code=false anexado:

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

  3. Você pode receber um erro com a mensagem localhost refused to connect após fazer logon. Se for o caso:

    1. Copie a URL.
    2. Executar curl '<pasted url>' (URL entre aspas) em um novo terminal do Codespaces.

    No terminal original, o logon agora deve ter êxito.

  4. Depois de fazer logon, execute azd pipeline config novamente.

Dockerfile armazenado em cache usado em vez do Dockerfile atual

Ao usar azd no seu ambiente de desenvolvimento local com o Docker, o Docker pode usar a versão armazenada em cache do Dockerfile em vez da versão atual. Isso resulta na implantação usando um contêiner com informações incorretas.

Solução

Para configurar a instalação local do Docker, que é usada pelo Azure Developer CLI para criar o contêiner, você precisa configurar o Docker com as seguintes variáveis de ambiente:

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

Você pode alterar azd up para incluir estas configurações:

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

Suporte do azd pipeline config

azd pipeline config não é suportado no momento nos Contêineres Remotos de DevContainers/VS Code.

Erros do recurso de composição

O azd recurso de redação só está disponível para tipos de projeto específicos. Se você tentar usar comandos de composição como azd add ou azd infra gen em um contexto sem suporte, poderá encontrar os seguintes erros.

Projeto incompatível

Se você vir uma ERROR: incompatible project mensagem ao executar o azd add comando, verifique o tipo de projeto com o qual está trabalhando. O comando azd add não tem suporte para projetos do .NET Aspire ou para modelos azd que já têm uma pasta infra definida. A tentativa de usar azd add com esses tipos de projeto resultará em erros como:

  • ERRO: projeto incompatível: host do aplicativo Aspire encontrado

  • ERRO: projeto incompatível: foi encontrado o diretório infra e o arquivo azure.yaml está sem recursos

    Uma captura de tela mostrando o erro de projeto incompatível do .NET Aspire.

    Uma captura de tela mostrando o erro de infraestrutura de projeto incompatível.

O projeto não possui infraestrutura para gerar

O erro ERROR: this project does not contain any infrastructure to generate ocorre quando:

  • Você executa azd infra gen sem nenhum recurso de orquestração definido em seu projeto.
  • Em projetos do .NET Aspire, esse erro também poderá aparecer se azd não for possível detectar um Host de Aplicativo Aspire no diretório atual.

Para resolver esse erro, use azd add para adicionar novos recursos antes de executar azd infra gen ou garantir que seu projeto .NET Aspire esteja estruturado corretamente.

Uma captura de tela mostrando o erro de infraestrutura.

Erro ao resolver o recurso do Azure

O comando azd show <name> pode falhar com o erro: ERROR: resolving '<name>': AZURE_RESOURCE_<NAME>_ID is not set as an output variable. Isso pode acontecer por vários motivos:

  • O recurso <name> não existe em azure.yaml em resources: node.
  • O recurso <name> ainda não foi provisionado.

Uma captura de tela mostrando o erro de recurso do Azure.

Solução

Execute azd up para provisionar os recursos. Talvez seja necessário executar azd infra gen primeiro para gerar o Bicep atualizado, incluindo o recurso <name>e, em seguida, executar azd up.

Suporte a métricas dinâmicas para Python

Atualmente, não há suporte para métricas dinâmicas (azd monitor --live) para aplicativos Python. Para obter mais informações, consulte Live Metrics: monitorar e diagnosticar com latência de um segundo.

Criar um problema do GitHub para solicitar ajuda

Uma imagem do logotipo do GitHub.

O Azure Developer CLI e a extensão do Visual Studio Code do Azure Developer CLI usam problemas do GitHub para rastrear bugs e solicitações de recursos. Pesquise os problemas existentes antes de registrar novos problemas para evitar duplicatas.

Para obter ajuda e perguntas sobre como usar este projeto, leia nosso wiki para usar o Azure Developer CLI e nosso documento de CONTRIBUIÇÃO se você quiser colaborar.

  • Last updated on