Share via

Falha ao extrair imagens de Registro de Contêiner do Azure para Serviço de Kubernetes do Azure cluster

  • Artigo

Observação

Esse artigo foi útil? Sua opinião é importante para nós. Use o botão Comentários nesta página para nos informar o quão bem este artigo funcionou para você ou como podemos melhorá-lo.

Quando você estiver usando o Microsoft Registro de Contêiner do Azure junto com Serviço de Kubernetes do Azure (AKS), um mecanismo de autenticação deve ser estabelecido. Você pode configurar a integração do AKS ao Registro de Contêiner usando alguns comandos simples da CLI do Azure ou Azure PowerShell. Essa integração atribui a função AcrPull para a identidade kubelet associada ao cluster AKS para extrair imagens de um registro de contêiner.

Em alguns casos, a tentativa de extrair imagens de um registro de contêiner para um cluster do AKS falha. Este artigo fornece diretrizes para solucionar os erros mais comuns que você encontra ao extrair imagens de um registro de contêiner para um cluster do AKS.

Antes de começar

Este artigo pressupõe que você tenha um cluster AKS existente e um registro de contêiner existente. Confira as seguintes partidas rápidas:

Você também precisa que a CLI do Azure versão 2.0.59 ou uma versão posterior seja instalada e configurada. Execute az version para determinar a versão. Se você precisar instalar ou atualizar, consulte Instalar a CLI do Azure.

Sintomas e solução de problemas iniciais

O STATUS do pod Kubernetes é ImagePullBackOff ou ErrImagePull. Para obter informações detalhadas de erro, execute o comando a seguir e marcar Eventos da saída.

kubectl describe pod <podname> -n <namespace>

Recomendamos que você inicie a solução de problemas verificando a integridade do registro de contêiner e verificando se o registro de contêiner está acessível no cluster do AKS.

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

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

Se um problema for detectado, ele fornecerá um código de erro e uma descrição. Para obter mais informações sobre os erros e possíveis soluções, consulte Referência de erro marcar de integridade.

Observação

Se você receber erros relacionados ao Helm ou ao Notário, isso não significa que um problema esteja afetando o Registro de Contêiner ou o AKS. Ele indica apenas que Helm ou Notary não está instalado ou que a CLI do Azure não é compatível com a versão atual instalada do Helm ou Notary e assim por diante.

Para validar se o registro de contêiner está acessível no cluster do AKS, execute o seguinte comando az aks marcar-acr:

az aks check-acr --resource-group <MyResourceGroup> --name <MyManagedCluster> --acr <myacr>.azurecr.io

As seções a seguir ajudam você a solucionar os erros mais comuns exibidos em Eventos na saída do kubectl describe pod comando.

Causa 1: 401 Erro não autorizado

Um cluster do AKS requer uma identidade. Essa identidade pode ser uma identidade gerenciada ou uma entidade de serviço. Se o cluster do AKS usar uma identidade gerenciada, a identidade kubelet será usada para autenticação com a ACR. Se o cluster do AKS estiver usando como identidade uma entidade de serviço, a própria entidade de serviço será usada para autenticação com a ACR. Não importa qual seja a identidade, a autorização adequada usada para extrair uma imagem de um registro de contêiner é necessária. Caso contrário, você poderá obter o seguinte erro "401 Não autorizado":

Falha ao puxar a imagem "<acrname.azurecr.io/>< repository:tag>": [erro rpc: code = desconhecido desc = falha ao puxar e desempacotar imagem "<acrname.azurecr.io/>< repository:tag>": falha ao resolve referência "<acrname.azurecr.io/<> repository:tag>": falha ao autorizar: falha ao buscar o token oauth: status inesperado: 401 Não autorizado

Várias soluções podem ajudá-lo a resolve esse erro, sujeito às seguintes restrições:

Solução 1: verifique se a atribuição de função do AcrPull foi criada para identidade

A integração entre o AKS e o Registro de Contêiner cria uma atribuição de função AcrPull no nível do registro de contêiner para a identidade kubelet do cluster AKS. Verifique se a atribuição de função foi criada.

Para marcar se a atribuição de função do AcrPull é criada, use um dos seguintes métodos:

  • Execute o seguinte comando:

    az role assignment list --scope /subscriptions/<subscriptionID>/resourceGroups/<resourcegroupname>/providers/Microsoft.ContainerRegistry/registries/<acrname> -o table

  • Faça check-in no portal do Azure selecionando atribuições de função do controle Registro de Contêiner do Azure>Access (IAM).> Para obter mais informações, confira Listar atribuições de função do Azure usando o portal do Azure.

Além da função AcrPull, algumas funções internas e funções personalizadas também podem conter a ação "Microsoft.ContainerRegistry/registries/pull/read". Verifique essas funções se você tiver alguma delas.

Se a atribuição de função do AcrPull não for criada, crie-a configurando a integração do Registro de Contêiner para o cluster AKS com o seguinte comando:

az aks update -n <myAKSCluster> -g <myResourceGroup> --attach-acr <acr-resource-id>

Solução 2: verifique se a entidade de serviço não expirou

Verifique se o segredo da entidade de serviço associada ao cluster do AKS não expirou. Para marcar a data de validade da entidade de serviço, execute os seguintes comandos:

SP_ID=$(az aks show --resource-group <myResourceGroup> --name <myAKSCluster> \
    --query servicePrincipalProfile.clientId -o tsv)

az ad sp credential list --id "$SP_ID" --query "[].endDate" -o tsv

Para obter mais informações, consulte Verificar a data de validade da entidade de serviço.

Se o segredo tiver expirado, atualize as credenciais para o cluster do AKS.

Solução 3: verifique se a função AcrPull está atribuída à entidade de serviço correta

Em alguns casos, a atribuição da função de registro de contêiner ainda se refere à entidade de serviço antiga. Por exemplo, quando a entidade de serviço do cluster AKS é substituída por uma nova. Para garantir que a atribuição da função de registro de contêiner se refira à entidade de serviço correta, siga estas etapas:

  1. Para marcar a entidade de serviço usada pelo cluster do AKS, execute o seguinte comando:

    az aks show --resource-group <myResourceGroup> \
    --name <myAKSCluster> \
    --query servicePrincipalProfile.clientId \
    --output tsv

  2. Para marcar a entidade de serviço referenciada pela atribuição da função de registro de contêiner, execute o seguinte comando:

    az role assignment list --scope /subscriptions/<subscriptionID>/resourceGroups/<resourcegroupname>/providers/Microsoft.ContainerRegistry/registries/<acrname> -o table

  3. Compare as duas entidades de serviço. Se eles não corresponderem, integre o cluster do AKS ao registro de contêiner novamente.

Solução 4: verifique se a identidade kubelet é referenciada na VMSS do AKS

Quando uma identidade gerenciada é usada para autenticação com o ACR, a identidade gerenciada é conhecida como identidade kubelet. Por padrão, a identidade kubelet é atribuída no nível de VMSS do AKS. Se a identidade kubelet for removida da VMSS do AKS, os nós do AKS não poderão extrair imagens do ACR.

Para localizar a identidade kubelet do cluster do AKS, execute o seguinte comando:

az aks show --resource-group <MyResourceGroup> --name <MyManagedCluster> --query identityProfile.kubeletidentity

Em seguida, você pode listar as identidades do VMSS do AKS abrindo o VMSS do grupo de recursos do nó e selecionandoo Usuário de Identidade> atribuído no portal do Azure ou executando o seguinte comando:

az vmss identity show --resource-group <NodeResourceGroup> --name <AksVmssName>

Se a identidade kubelet do cluster do AKS não for atribuída à VMSS do AKS, atribua-a de volta.

Observação

Não há suporte para modificar a VMSS do AKS usando as APIs IaaS ou do portal do Azure e nenhuma operação do AKS pode remover a identidade kubelet da VMSS do AKS. Isso significa que algo inesperado o removeu, por exemplo, de uma remoção manual executada por um membro da equipe. Para evitar essa remoção ou modificação, você pode considerar o uso do recurso NRGLockdown.

Como não há suporte para modificações na VMSS do AKS, elas não se propagam no nível do AKS. Para reatribuir a identidade kubelet para a VMSS do AKS, é necessária uma operação de reconciliação. Para fazer isso, execute o seguinte comando:

az aks update --resource-group <MyResourceGroup> --name <MyManagedCluster>

Solução 5: verifique se a entidade de serviço está correta e o segredo é válido

Se você puxar uma imagem usando um segredo de pull de imagem e se o segredo do Kubernetes foi criado usando os valores de uma entidade de serviço, verifique se a entidade de serviço associada está correta e o segredo ainda será válido. Siga estas etapas:

  1. Execute o seguinte comando kubectl get e base64 para ver os valores do segredo kubernetes:

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

  2. Verifique a data de validade executando o seguinte comando az ad sp credential list . O nome de usuário é o valor da entidade de serviço.

    az ad sp credential list --id "<username>" --query "[].endDate" --output tsv

  3. Se necessário, reinicie o segredo dessa entidade de serviço executando o seguinte comando de redefinição de credencial az ad sp :

    az ad sp credential reset --name "$SP_ID" --query password --output tsv

  4. Atualize ou recrie o segredo do Kubernetes de acordo.

Solução 6: verifique se o segredo do Kubernetes tem os valores corretos da conta de administrador do registro de contêiner

Se você puxar uma imagem usando um segredo de pull de imagem e se o segredo do Kubernetes foi criado usando valores da conta de administrador do registro de contêiner, verifique se os valores no segredo do Kubernetes são os mesmos que os valores da conta de administrador do registro de contêiner. Siga estas etapas:

  1. Execute o seguinte comando kubectl get e base64 para ver os valores do segredo kubernetes:

    kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

  2. No portal do Azure, pesquise e selecione Registros de contêiner.

  3. Na lista de registros de contêineres, selecione seu registro de contêiner.

  4. No painel de navegação do registro de contêiner, selecione Chaves de acesso.

  5. Na página Chaves de acesso para o registro de contêiner, compare os valores do registro de contêiner com os valores no segredo kubernetes.

  6. Se os valores não corresponderem, atualize ou recrie o segredo do Kubernetes de acordo.

Observação

Se ocorreu uma operação de senha regenerar , uma operação chamada "Regenerar Credenciais de Logon do Registro de Contêiner" será exibida na página de log de atividades do registro de contêiner. O log de atividades tem um período de retenção de 90 dias.

Causa 2: Imagem não encontrada erro

Falha ao puxar a imagem "<acrname.azurecr.io/>< repository:tag>": [erro rpc: code = NotFound desc = fail to pull and unpack image "<acrname.azurecr.io/>< repository:tag>": falha ao resolve referência "<acrname.azurecr.io/>< repository:tag>": <acrname.azurecr.io/>< repository:tag>: não encontrado

Solução: verifique se o nome da imagem está correto

Se você vir esse erro, verifique se o nome da imagem está totalmente correto. Você deve marcar o nome do registro, o servidor de logon do registro, o nome do repositório e a marca. Um erro comum é que o servidor de logon é especificado como "azureacr.io" em vez de "azurecr.io".

Se o nome da imagem não estiver totalmente correto, o erro não autorizado 401 também poderá ocorrer porque o AKS sempre tenta o pull anônimo, independentemente de o registro de contêiner ter habilitado o acesso pull anônimo.

Causa 3: 403 Erro proibido

Falha ao puxar a imagem "<acrname.azurecr.io/>< repository:tag>": erro rpc: code = unknown desc = não conseguiu puxar e desempacotar imagem "<acrname.azurecr.io/>< repository:tag>": falha ao resolve referência "<acrname.azurecr.io/<> repository:tag>": falha ao autorizar: falha ao buscar token anônimo: status inesperado: 403 Proibido

Se a interface de rede do ponto de extremidade privado do registro de contêiner e o cluster AKS estiverem em redes virtuais diferentes, verifique se o link de rede virtual para a rede virtual do cluster AKS está definido na zona DNS privado do registro de contêiner. (Esse link é chamado de "privatelink.azurecr.io" por padrão.) Se o link de rede virtual não estiver na zona DNS privado do registro de contêiner, adicione-o usando uma das seguintes maneiras:

Solução 2: adicionar o endereço IP público do Load Balancer DO AKS ao intervalo de endereços IP permitido do registro de contêiner

Se o cluster do AKS se conectar publicamente ao registro de contêiner (NÃO por meio de um link privado ou de um ponto de extremidade) e o acesso de rede pública do registro de contêiner estiver limitado a redes selecionadas, adicione o endereço IP público do AKS Load Balancer ao intervalo de endereço IP permitido do registro de contêiner:

  1. Verifique se o acesso à rede pública está limitado a redes selecionadas.

    No portal do Azure, navegue até o registro de contêiner. Em Configurações, selecione Rede. Na guia Acesso público, o acesso à rede pública é definido como Redes selecionadas ou Desabilitados.

  2. Obtenha o endereço IP público do Load Balancer do AKS usando uma das seguintes maneiras:

    • No portal do Azure, navegue até o cluster do AKS. Em Configurações, selecione Propriedades, selecione um dos conjuntos de dimensionamento de máquinas virtuais no grupo de recursos de infraestrutura e marcar o endereço IP público do Load Balancer do AKS.

    • Execute o seguinte comando:

      az network public-ip show --resource-group <infrastructure-resource-group> --name <public-IP-name> --query ipAddress -o tsv

  3. Permitir acesso do endereço IP público do Load Balancer DO AKS usando uma das seguintes maneiras:

    • Execute az acr network-rule add o comando da seguinte maneira:

      az acr network-rule add --name acrname --ip-address <AKS-load-balancer-public-IP-address>

      Para obter mais informações, consulte Adicionar regra de rede ao registro.

    • No portal do Azure, navegue até o registro de contêiner. Em Configurações, selecione Rede. Na guia Acesso público, em Firewall, adicione o endereço IP público do Load Balancer AKS ao intervalo de endereços e selecione Salvar. Para obter mais informações, confira Acesso na rede pública selecionada – portal.

      Observação

      Se o acesso à rede pública estiver definido como Desabilitado, alterne-o primeiro para redes selecionadas .

      Captura de tela sobre como adicionar o endereço IP público do Load Balancer do AKS ao intervalo de endereços

Causa 4: erro de tempo limite 443

Falha ao puxar a imagem "<acrname.azurecr.io/<> repository:tag>": erro rpc: code = desc desconhecido = falha ao puxar e desempacotar imagem "<acrname.azurecr.io/>< repository:tag>": falha ao resolve referência "<acrname.azurecr.io/<> repository:tag>": falha ao fazer a solicitação: cabeça "https://< acrname.azurecr.io/v2/>< repository>/manifests/v1": dial tcp <acrprivateipaddress>:443: i/o Timeout

Observação

O erro "443 tempo limite" ocorre somente quando você se conecta privadamente a um registro de contêiner usando Link Privado do Azure.

Solução 1: verifique se o emparelhamento de rede virtual é usado

Se a interface de rede do ponto de extremidade privado do registro de contêiner e o cluster do AKS estiverem em redes virtuais diferentes, verifique se o emparelhamento de rede virtual é usado para ambas as redes virtuais. Você pode marcar emparelhamento de rede virtual executando o comando az network vnet peering list --resource-group <MyResourceGroup> --vnet-name <MyVirtualNetwork> --output table da CLI do Azure ou no portal do Azure selecionando osemparelhamentosVNETs> no painel Configurações. Para obter mais informações sobre como listar todos os emparelhamentos de uma rede virtual especificada, consulte az network vnet peering list.

Se o emparelhamento de rede virtual for usado para ambas as redes virtuais, verifique se o status está "Conectado". Se o status for Desconectado, exclua o emparelhamento de ambas as redes virtuais e, em seguida, recrie-o. Se o status for "Conectado", consulte o guia de solução de problemas: o status de emparelhamento será "Conectado".

Para solução de problemas adicionais, conecte-se a um dos nós ou pods do AKS e teste a conectividade com o registro de contêiner no nível TCP usando o utilitário Telnet ou Netcat. Verifique o endereço IP com o nslookup <acrname>.azurecr.io comando e execute o telnet <ip-address-of-the-container-registry> 443 comando.

Para obter mais informações sobre como se conectar a nós do AKS, consulte Conectar-se com o SSH aos nós de cluster do AKS (Serviço de Kubernetes do Azure) para manutenção ou solução de problemas.

Solução 2: usar Firewall do Azure Serviço

Se a interface de rede do ponto de extremidade privado do registro de contêiner e o cluster do AKS estiverem em redes virtuais diferentes, além do emparelhamento de rede virtual, você poderá usar Firewall do Azure Serviço para configurar uma topologia de rede hub-spoke no Azure. Ao configurar a regra de firewall, você precisa usar regras de rede para permitir explicitamente a conexão de saída com os endereços IP do ponto de extremidade privado do registro de contêiner.

Causa 5: nenhuma correspondência para a plataforma no manifesto

O sistema operacional host (sistema operacional de nó) é incompatível com a imagem usada para o pod ou contêiner. Por exemplo, se você agendar um pod para executar um contêiner linux em um nó windows ou um contêiner do Windows em um nó Linux, ocorrerá o seguinte erro:

Falha ao puxar a imagem "<acrname.azurecr.io/>< repository:tag>":
[
  erro rpc:
  code = NotFound
  desc = falha ao puxar e desempacotar a imagem "<acrname.azurecr.io/>< repository:tag>": nenhuma correspondência para a plataforma no manifesto: não encontrada,
]

Esse erro pode ocorrer para uma imagem que é extraída de qualquer fonte, desde que a imagem seja incompatível com o sistema operacional host. O erro não se limita às imagens que são retiradas do registro de contêiner.

Solução: configurar o campo nodeSelector corretamente em seu pod ou implantação

Especifique o campo correto nodeSelector nas configurações do pod ou da implantação. O valor correto para a configuração deste campo kubernetes.io/os garante que o pod será agendado no tipo correto de nó. A tabela a seguir mostra como definir a kubernetes.io/os configuração no YAML:

Tipo de contêiner Configuração YAML
Contêiner linux "kubernetes.io/os": linux
Contêiner do Windows "kubernetes.io/os": windows

Por exemplo, o seguinte código YAML descreve um pod que precisa ser agendado em um nó linux:

apiVersion: v1
kind: Pod
metadata:
  name: aspnetapp
  labels:
    app: aspnetapp
spec:
  containers:
  - image: "mcr.microsoft.com/dotnet/core/samples:aspnetapp"
    name: aspnetapp-image
    ports:
    - containerPort: 80
      protocol: TCP
  nodeSelector:
    "kubernetes.io/os": linux

Mais informações

Se as diretrizes de solução de problemas neste artigo não ajudarem você a resolve o problema, aqui estão algumas outras coisas a serem consideradas:

  • Verifique os grupos de segurança de rede e as tabelas de rotas associadas às sub-redes, se você tiver algum desses itens.

  • Se um dispositivo virtual como um firewall controlar o tráfego entre sub-redes, marcar o firewall e as regras de acesso ao Firewall.

Aviso de isenção de responsabilidade para informações de terceiros

Os produtos de terceiros mencionados neste artigo são produzidos por empresas independentes da Microsoft. A Microsoft não oferece nenhuma garantia, implícita ou não, do desempenho ou da confiabilidade desses produtos.

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.