Compartilhar via

Solucionar problemas de autenticação do Registro de Contêiner do Azure

  • Artigo

O ACR (Registro de Contêiner do Azure) é um serviço de registro privado. Para executar operações como push ou pull (exceto a operação de pull anônimo), você precisa se autenticar no ACR primeiro.

Este artigo ajuda você a solucionar problemas de autenticação do ACR e fornece soluções para os erros mais comuns que ocorrem quando você efetua pull de imagens de um registro de contêiner.

Solução de problemas inicial

  1. Identifique a opção de autenticação que você está usando. Depois de escolher um, reproduza o problema de autenticação para obter o erro.

  2. Inicie a solução de problemas verificando a integridade do registro de contêiner do Azure.

    Para verificar a integridade do registro de contêiner, execute o seguinte comando:

    az acr check-health --name <acr-name> --ignore-errors --yes

    Se um problema for detectado, a saída do comando fornecerá um código de erro e uma descrição. Para obter mais informações sobre o código de erro e possíveis soluções, consulte a referência de erro de verificação de integridade.

    Observação

    Se você receber erros relacionados ao Helm ou ao Notary, isso não significa que você tem um problema que afeta seu registro ou dispositivo de contêiner. Ele indica apenas que o Helm ou o Notary não está instalado ou que a CLI do Azure não é compatível com a versão atualmente instalada do Helm ou do Notary.

Erro 1: "DOCKER_COMMAND_ERROR Verifique se o cliente Docker está instalado e em execução"

Aqui está um exemplo dos detalhes do erro:

You may want to use 'az acr login -n <acr-name> --expose-token' to get an access token, which does not require Docker to be installed.
<date and time> An error occurred: DOCKER_COMMAND_ERROR
Please verify if Docker client is installed and running.

Solução 1: verifique se o Docker está instalado

O az acr login comando chama o docker login comando e usa o token de acesso do Microsoft Entra para autenticar no ACR. Ele requer que o cliente do Docker e o daemon do Docker sejam instalados na máquina em que você executa o comando. Para instalar o Docker, consulte Instalar o Docker Engine.

Solução 2: use o comando "az acr login" com o parâmetro "--expose-token"

Quando o daemon do Docker não for executado em seu ambiente, se você precisar se autenticar com o ACR, use o comando az acr login com o parâmetro --expose-token. Esse comando é útil quando você precisa executar scripts que não exigem o daemon do Docker, mas apenas a CLI do Docker (por exemplo, ao usar o Azure Cloud Shell).

Erro 2: "Este comando requer a execução do daemon do docker, que não tem suporte no Azure Cloud Shell"

Aqui está um exemplo dos detalhes do erro:

This command requires running the docker daemon, which is not supported in Azure Cloud Shell. You may want to use 'az acr login -n <acr-name> --expose-token' to get an access token, which does not require Docker to be installed.

Solução 1: execute o comando "az acr login -n <acr-name>" em outro ambiente

O az acr login -n <acr-name> comando requer que o cliente do Docker e o daemon do Docker sejam executados. O Azure Cloud Shell fornece apenas o cliente do Docker. Para resolver esse erro, execute o az acr login -n <acr-name> comando em um ambiente em que o daemon do Docker esteja instalado.

Solução 2: use o comando "az acr login" com o parâmetro "--expose-token"

O az acr login -n <acr-name> comando requer que o cliente do Docker e o daemon do Docker sejam executados. O Azure Cloud Shell fornece apenas o cliente do Docker. No entanto, o az acr login comando com o --expose-token parâmetro funciona para ambientes sem o daemon do Docker, como o Azure Cloud Shell.

Erro 3: "Não autorizado: autenticação necessária"

Aqui está um exemplo dos detalhes do erro:

Error response from daemon: Get "https://<acr-name>.azurecr.io/v2/": unauthorized: {"errors":[{"code":"UNAUTHORIZED","message":"authentication required, visit https://aka.ms/acr/authorization for more information."}]}

O erro indica que a autenticação falhou ao acessar o ACR. Esse erro pode ocorrer ao executar o az acr login comando or docker login com um nome de usuário e/ou senha incorretos ou credenciais expiradas (ao usar uma entidade de serviço, um token com um mapa de escopo ou um usuário administrador).

Solução: Use o nome de usuário e a senha corretos/válidos

  • Se você estiver usando um usuário administrador para autenticar, verifique a credencial na folha Chaves de acesso e se elas são as que você usou no docker login comando ou az acr login .

    Captura de tela que mostra a folha 'Chaves de acesso' do ACR.

    Observação

    Uma senha usada antes pode ter sido regenerada.

  • Se você estiver usando um token associado a um mapa de escopo, verifique as credenciais usadas. Depois de gerar uma senha para o token, você deve recuperá-la e armazenar as credenciais com segurança, pois a senha não será mais exibida depois que você fechar a tela. Veja a mensagem na captura de tela a seguir:

    Captura de tela que mostra a mensagem 'armazene suas credenciais com segurança após a geração'.

    Se você não tiver certeza da senha usada, considere regenerá-la .

  • Se você estiver usando um token associado a um mapa de escopo, uma data de expiração poderá ser definida para a senha. Para exibir a data de expiração, você pode executar os comandos da CLI do Azure descritos em Mostrar detalhes do token ou abrir o token no portal do Azure e verificar a data de expiração de acordo com a captura de tela a seguir:

    Captura de tela que mostra a coluna

  • Se você estiver usando uma entidade de serviço, verifique se ela tem as permissões específicas para autenticar com o ACR. Para encontrar as permissões específicas e as funções internas disponíveis, confira Funções e permissões do Registro de Contêiner do Azure.

  • Se você estiver usando uma entidade de serviço, verifique a credencial usada. Depois de gerar um segredo, você deve recuperá-lo e armazenar as credenciais com segurança, pois a senha não será mais exibida depois que você fechar a tela. Veja a mensagem na captura de tela a seguir:

    Captura de tela que mostra a mensagem 'salvar o segredo quando criado antes de sair da página'.

    Se você não tiver certeza do valor do segredo usado, considere criar um novo segredo.

  • Se você estiver usando uma entidade de serviço, verifique se o segredo não expirou.

    Você pode verificar a validade do segredo executando o comando az ad app credential list :

    az ad app credential list --id "$SP_ID" --query "[].endDateTime" -o tsv

    Ou você pode verificar a validade do segredo verificando a coluna Expira no portal do Azure:

    Captura de tela que mostra a coluna

    Se o segredo tiver expirado, você poderá considerar a criação de um novo segredo.

Erro 4: "Não é possível obter credenciais de usuário administrador"

Aqui está um exemplo dos detalhes do erro:

Unable to get AAD authorization tokens with message: <date> <time> An error occurred: CONNECTIVITY_REFRESH_TOKEN_ERROR
Access to registry '<acr-name>.azurecr.io' was denied. Response code: 401. Please try running 'az login' again to refresh permissions.
Unable to get admin user credentials with message: The resource with name '<acr-name>' and type 'Microsoft.ContainerRegistry/registries' could not be found in subscription '<subscription-name> (<subscription-id>)'.

Solução: verifique se a identidade usada tem as permissões específicas

Verifique se a identidade (como um usuário ou uma identidade gerenciada) usada para autenticar tem as permissões específicas. Para encontrar as permissões específicas e as funções internas disponíveis, confira Funções e permissões do Registro de Contêiner do Azure.

Erro 5: "Cliente com <endereço> IP IP não tem permissão de acesso"

Aqui está um exemplo dos detalhes do erro:

Unable to get AAD authorization tokens with message: <date> <time> An error occurred: CONNECTIVITY_REFRESH_TOKEN_ERROR
Access to registry '<acr-name>.azurecr.io' was denied. Response code: 403. Please try running 'az login' again to refresh permissions.
Error response from daemon: Get "https://<acr-name>.azurecr.io/v2/": denied: {"errors":[{"code":"DENIED","message":"client with IP \u0027<ip-address>\u0027 is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}]}

Solução: verifique se o dispositivo que você está tentando autenticar tem conectividade com o ACR

O ACR tem um firewall interno, que é um mecanismo para restringir o acesso público. Ele pode permitir acesso total, permitir acesso apenas a redes específicas ou desabilitar totalmente o acesso público. No entanto, a conectividade adequada é necessária para uma autenticação bem-sucedida. Verifique se o endereço IP tem permissão para acessar e entrar no registro. Para obter mais informações sobre como configurar o acesso público, consulte Configurar regras de rede IP pública.

Como alternativa, você pode considerar o uso do Link Privado do Azure para se conectar de forma privada ao registro de contêiner do Azure.

Entre em contato conosco para obter ajuda

Se você tiver dúvidas ou precisar de ajuda, crie uma solicitação de suporte ou peça ajuda à comunidade de suporte do Azure. Você também pode enviar comentários sobre o produto para a comunidade de comentários do Azure.