Autenticar no Registro de Contêiner do Azure por meio das Instâncias de Contêiner do Azure

Você pode usar uma entidade de serviço do Microsoft Entra para fornecer acesso aos registros de contêiner privado no Registro de Contêiner do Azure.

Neste artigo, você aprenderá a criar e configurar uma entidade de serviço do Microsoft Entra com permissões de pull para o registro. Em seguida, você inicia um contêiner no ACI (Instâncias de Contêiner do Azure), que efetua pull de sua imagem por meio de seu registro particular, usando a entidade de serviço para autenticação.

Quando usar uma entidade de serviço

Você deve usar uma entidade de serviço para a autenticação no ACI em cenários “sem periféricos”, como em aplicativos ou serviços que criam instâncias de contêiner de maneira automatizada ou autônoma.

Por exemplo, se você tem um script automatizado que é executado à noite e que cria uma instância de contêiner baseada em tarefa para processar alguns dados, ele pode usar uma entidade de serviço com permissões somente pull para se autenticar no registro. Em seguida, você pode girar as credenciais da entidade de serviço ou revogar o acesso por completo, sem afetar outros serviços e aplicativos.

As entidades de serviço também devem ser usadas quando o registro usuário administrador está desabilitado.

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 no 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

Autenticar usando a entidade de serviço

Para iniciar um contêiner em Instâncias de Contêiner do Azure usando uma entidade de serviço, especifique sua ID para --registry-username e sua senha para --registry-password.

az container create \
    --resource-group myResourceGroup \
    --name mycontainer \
    --image mycontainerregistry.azurecr.io/myimage:v1 \
    --registry-login-server mycontainerregistry.azurecr.io \
    --registry-username <service-principal-ID> \
    --registry-password <service-principal-password>

Observação

É recomendável executar os comandos na versão mais recente do Azure Cloud Shell. Definir export MSYS_NO_PATHCONV=1 para executar o ambiente bash no local.

Scripts de exemplo

Você pode encontrar os scripts de exemplo anteriores para a CLI do Azure no GitHub, bem como versões do Azure PowerShell:

Próximas etapas

Os seguintes artigos contêm mais detalhes sobre como trabalhar com entidades de serviço e o ACR: