Efetuar pull de imagens de um registro de contêiner do Azure para um cluster do Kubernetes usando um segredo de pull

  • Artigo

Você pode usar um registro de contêiner do Azure como fonte de imagens de contêiner com qualquer cluster Kubernetes, incluindo clusters Kubernetes "locais", como minikube e kind. Este artigo mostra como criar um segredo de pull do Kubernetes usando credenciais para um registro de contêiner do Azure. Em seguida, use o segredo para efetuar pull de imagens de um registro de contêiner do Azure em uma implantação de pod.

Este exemplo cria um segredo de pull usando as credenciais da entidade de serviço do Microsoft Entra. Também é possível configurar um segredo de pull usando outras credenciais de registro de contêiner do Azure, como um token de acesso com escopo de repositório.

Observação

Embora os segredos de pull sejam comumente usados, eles causam sobrecarga de gerenciamento adicional. Se estiver usando o Serviço de Kubernetes do Azure recomendamos outras opções, como usar a identidade gerenciada do cluster ou a entidade de serviço para efetuar pull com segurança da imagem sem uma configuração imagePullSecrets adicional em cada pod.

Pré-requisitos

Este artigo pressupõe que você já tenha criado um registro de contêiner privado do Azure. Você também precisa ter um cluster Kubernetes em execução e acessível por meio da ferramenta de linha de comando kubectl.

Criar uma entidade de serviço

Para criar uma entidade de serviço com acesso ao registro de contêiner, execute o script a seguir no Azure Cloud Shell ou uma instalação local da CLI do Azure. O script é formatado para o shell do Bash.

Antes de executar o script, atualize a variável ACR_NAME com o nome do registro de contêiner. O valor SERVICE_PRINCIPAL_NAME deve ser exclusivo em seu locatário do Microsoft Entra. Se você receber um erro "'http://acr-service-principal' already exists.", especifique um nome diferente para a entidade de serviço.

Como opção, modifique o valor --role no comando az ad sp create-for-rbac se quiser conceder permissões diferentes. Para obter uma lista completa de funções, consulte Funções e permissões do ACR.

Depois de executar o script, anote a ID e a senha da entidade de serviço. Quando você tiver suas credenciais, poderá configurar os aplicativos e serviços para se autenticarem no registro de contêiner como a entidade de serviço.

#!/bin/bash
# This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_NAME=$servicePrincipal

# Obtain the full registry ID
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
# echo $registryId

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"

Usar uma entidade de serviço existente

Para conceder acesso de registro a uma entidade de serviço existente, você precisa atribuir uma nova função à entidade de serviço. Assim como ocorre ao criar uma nova entidade de serviço, é possível conceder acesso de proprietário, pull, push e pull, dentre outros.

O script a seguir usa o comando az role assignment create para conceder permissões pull a uma entidade de serviço especificada na variável SERVICE_PRINCIPAL_ID. Ajuste o valor --role se você desejar conceder um nível diferente de acesso.

#!/bin/bash
# Modify for your environment. The ACR_NAME is the name of your Azure Container
# Registry, and the SERVICE_PRINCIPAL_ID is the service principal's 'appId' or
# one of its 'servicePrincipalNames' values.
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_ID=$servicePrincipal

# Populate value required for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Assign the desired role to the service principal. Modify the '--role' argument
# value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
az role assignment create --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID --role acrpull

Se você não salvar ou lembrar a senha da entidade de serviço, poderá redefini-la com o comando az ad sp credential reset:

az ad sp credential reset  --name http://<service-principal-name> --query password --output tsv

Ele retorna uma nova senha válida para sua entidade de serviço.

Criar um segredo de pull de imagem

O Kubernetes usa um segredo de pull de imagem para armazenar as informações necessárias para a autenticação no registro. Para criar o segredo de pull para um registro de contêiner do Azure, forneça o ID da entidade de serviço, a senha e a URL do registro.

Crie um segredo de pull de imagem com o comando kubectl a seguir:

kubectl create secret docker-registry <secret-name> \
    --namespace <namespace> \
    --docker-server=<container-registry-name>.azurecr.io \
    --docker-username=<service-principal-ID> \
    --docker-password=<service-principal-password>

em que:

Valor Descrição
secret-name Nome do segredo de pull da imagem, por exemplo, acr-secret
namespace Namespace do Kubernetes no qual o segredo será colocado
Necessário apenas quando você quer colocar o segredo em um namespace diferente do padrão
container-registry-name O nome do registro de contêiner do Azure, por exemplo, myregistry

O --docker-server é o nome totalmente qualificado do servidor de logon do registro
service-principal-ID ID da entidade de serviço a ser usada pelo Kubernetes para acessar o registro
service-principal-password Senha da entidade de serviço

Usar o segredo de pull de imagem

Depois de criar o segredo de pull de imagem, você pode usá-lo para criar pods e implantações do Kubernetes. Forneça o nome do segredo em imagePullSecrets no arquivo de implantação. Por exemplo:

apiVersion: v1
kind: Pod
metadata:
  name: my-awesome-app-pod
  namespace: awesomeapps
spec:
  containers:
    - name: main-app-container
      image: myregistry.azurecr.io/my-awesome-app:v1
      imagePullPolicy: IfNotPresent
  imagePullSecrets:
    - name: acr-secret

No exemplo anterior, my-awesome-app:v1 é o nome da imagem para pull do registro de contêiner do Azure, e acr-secret é o nome do segredo de pull que você criou para acessar o registro. Ao implantar o pod, o Kubernetes fará pull automaticamente da imagem do registro, se ela ainda não estiver no cluster.

Próximas etapas