Use uma identidade gerenciada do Azure para autenticar para um registro de contêiner do Azure

Use uma identidade gerenciada para recursos do Azure para se autenticar em um registro de contêiner do Azure a partir de outro recurso do Azure, sem a necessidade de fornecer ou gerenciar credenciais de registro. Por exemplo, configure uma identidade gerenciada atribuída pelo usuário ou pelo sistema em uma VM Linux para acessar imagens de contêiner a partir do seu registro de contêiner, tão fácil quanto usar um registro público. Ou então, configure um cluster do serviço Kubernetes do Azure para usar sua identidade gerenciada para efetuar pull de imagens de contêiner do Registro de Contêiner do Azure para implantações de Pod.

Neste artigo, você aprenderá mais sobre identidades gerenciadas e como:

• Habilitar uma identidade atribuída pelo usuário ou pelo sistema em uma VM do Azure
• Conceder à identidade o acesso ao registro de contêiner do Azure
• Use a identidade gerenciada para acessar o registro e efetuar pull de uma imagem de contêiner

CLI do Azure

Este artigo exige que você esteja executando a CLI do Azure versão 2.0.55 ou posterior para criar os recursos do Azure. Execute az --version para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

PowerShell do Azure

Para criar os recursos do Azure, este artigo requer que você execute a versão 7.5.0 ou posterior do módulo do Azure PowerShell. Execute Get-Module Az -ListAvailable para encontrar a versão. Se você precisar instalá-lo ou atualizá-lo, confira Instalar o módulo do Azure PowerShell.

Para configurar um registro de contêiner e enviar por push uma imagem de contêiner a ele, você também deve ter o Docker instalado localmente. O Docker fornece pacotes que configuram facilmente o Docker em qualquer sistema macOS, Windows ou Linux.

Por que usar uma identidade gerenciada?

Se você não estiver familiarizado com as identidades gerenciadas para funcionalidades de recursos do Azure, veja esta visão geral.

Após configurar um recurso do Azure com uma identidade gerenciada, conceda a identidade e o acesso desejado a outro recurso, assim como é feito com qualquer entidade de segurança. Por exemplo, atribua uma identidade gerenciada a uma função com pull, push e pull ou outras permissões para um registro privado no Azure. (Para obter uma lista completa de funções de registro, consulte funções e permissões do Registro de Contêiner do Azure.) Você pode conceder acesso de identidade a um ou mais recursos.

Em seguida, use a identidade para autenticar em qualquer serviço que ofereça suporte à autenticação do Microsoft Entra, sem credenciais no código. Escolha como se autenticar usando a identidade gerenciada, dependendo do cenário. Para usar a identidade para acessar um registro de contêiner do Azure a partir de uma máquina virtual, você pode se autenticar com o Azure Resource Manager.

Criar um registro de contêiner

CLI do Azure

Se você ainda não tiver um registro de contêiner do Azure, crie um registro e envie por push uma imagem de contêiner de exemplo para ele. Para as etapas, consulte Início Rápido: criar um registro de contêiner privado usando a CLI do Azure.

Este artigo pressupõe que você tenha a imagem de contêiner aci-helloworld:v1 armazenada em seu registro. Os exemplos usam um nome de registro de myContainerRegistry. Substitua pelo seu próprio registro e nomes de imagem em etapas posteriores.

PowerShell do Azure

Se você ainda não tiver um registro de contêiner do Azure, crie um registro e envie por push uma imagem de contêiner de exemplo para ele. Para as etapas, consulte Início Rápido: criar um registro de contêiner privado usando o Azure PowerShell.

Este artigo pressupõe que você tenha a imagem de contêiner aci-helloworld:v1 armazenada em seu registro. Os exemplos usam um nome de registro de myContainerRegistry. Substitua pelo seu próprio registro e nomes de imagem em etapas posteriores.

Criar uma VM habilitada para Docker

CLI do Azure

Crie uma máquina virtual Ubuntu habilitada para Docker. Você também precisará instalar a CLI do Azure na máquina virtual. Se você já tiver uma máquina virtual do Azure, ignore esta etapa para criar a máquina virtual.

Implante uma máquina virtual padrão do Azure no Ubuntu com az vm create. O exemplo abaixo cria uma VM chamada myDockerVM em um grupo de recursos existente chamado myResourceGroup:

az vm create \
    --resource-group myResourceGroup \
    --name myDockerVM \
    --image Ubuntu2204 \
    --admin-username azureuser \
    --generate-ssh-keys

A criação da VM demora alguns minutos. Quando o comando for concluído, observe o publicIpAddress exibido pela CLI do Azure. Use esse endereço para estabelecer conexões SSH à VM.

PowerShell do Azure

Crie uma máquina virtual Ubuntu habilitada para Docker. Você também precisará instalar o Azure PowerShell na máquina virtual. Se você já tiver uma máquina virtual do Azure, ignore esta etapa para criar a máquina virtual.

Implante uma máquina virtual padrão do Azure no Ubuntu com New-AzVM. O exemplo a seguir cria uma VM chamada myDockerVM em um grupo de recursos existente chamado myResourceGroup. Você receberá uma solicitação para um nome de usuário que será usado quando você se conectar à VM. Especifique azureuser como nome de usuário. Você também será solicitado a usar uma senha, que pode deixar em branco. O logon de senha para a VM é desabilitado ao usar uma chave SSH.

$vmParams = @{
    ResourceGroupName   = 'MyResourceGroup'
    Name                = 'myDockerVM'
    Image               = 'UbuntuLTS'
    PublicIpAddressName = 'myPublicIP'
    GenerateSshKey      = $true
    SshKeyName          = 'mySSHKey'
}
New-AzVM @vmParams

A criação da VM demora alguns minutos. Quando o comando for concluído, execute o comando a seguir para obter o endereço IP público. Use esse endereço para estabelecer conexões SSH à VM.

Get-AzPublicIpAddress -Name myPublicIP -ResourceGroupName myResourceGroup | Select-Object -ExpandProperty IpAddress

Instalar o Docker na VM

Depois que a VM estiver em execução, estabeleça uma conexão SSH à VM. Substitua publicIpAddress pelo endereço IP público da VM.

ssh azureuser@publicIpAddress

Execute o seguinte comando para instalar o Docker na VM:

sudo apt update
sudo apt install docker.io -y

Após a instalação, execute o seguinte comando para verificar se o Docker está funcionando corretamente na VM:

sudo docker run -it mcr.microsoft.com/hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.
[...]

CLI do Azure

Instalar a CLI do Azure

Siga as etapas em Instalar a CLI do Azure com apt para instalar a CLI do Azure em sua máquina virtual do Ubuntu. Neste artigo, certifique-se de instalar a versão 2.0.55 ou posterior.

PowerShell do Azure

Instalar o Azure PowerShell

Siga as etapas em Instalando o PowerShell no Ubuntu e Instalar o módulo Azure Az do PowerShell para instalar o PowerShell e o Azure PowerShell em sua máquina virtual Ubuntu. Neste artigo, certifique-se de instalar a versão 7.5.0 ou posterior do Azure PowerShell.

Saia da sessão do SSH.

Exemplo 1: acessar com uma identidade atribuída pelo usuário

Criar uma identidade

CLI do Azure

Crie uma identidade em sua assinatura usando o comando az identity create. Você pode usar o mesmo grupo de recursos que você usou anteriormente para criar o registro de contêiner ou máquina virtual ou pode usar um diferente.

az identity create --resource-group myResourceGroup --name myACRId

Para configurar a identidade nas etapas a seguir, use o comando az identity show para armazenar a ID do recurso da entidade e a ID da entidade de serviço nas variáveis.

# Get resource ID of the user-assigned identity
userID=$(az identity show --resource-group myResourceGroup --name myACRId --query id --output tsv)

# Get service principal ID of the user-assigned identity
spID=$(az identity show --resource-group myResourceGroup --name myACRId --query principalId --output tsv)

Como você precisa da ID da identidade em uma etapa posterior (quando fizer logon na CLI da sua máquina virtual) mostre o valor:

echo $userID

A ID pertence ao formulário:

/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myACRId

PowerShell do Azure

Crie uma identidade na assinatura usando o cmdlet New-AzUserAssignedIdentity. Você pode usar o mesmo grupo de recursos que você usou anteriormente para criar o registro de contêiner ou máquina virtual ou pode usar um diferente.

New-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Location eastus -Name myACRId

Para configurar a identidade nas etapas a seguir, use o comando Get-AzUserAssignedIdentity para armazenar a ID do recurso da entidade e a ID da entidade de serviço em variáveis.

# Get resource ID of the user-assigned identity
$userID = (Get-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Name myACRId).Id

# Get service principal ID of the user-assigned identity
$spID = (Get-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Name myACRId).PrincipalId

Como você precisará da ID da identidade em uma etapa posterior, quando fizer logon na CLI de sua máquina virtual do Azure PowerShell, mostre o valor:

$userID

A ID pertence ao formulário:

/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myACRId

Configurar a VM com a identidade

CLI do Azure

O comando az vm identity assign a seguir configura sua VM do Docker com a identidade atribuída pelo usuário:

az vm identity assign --resource-group myResourceGroup --name myDockerVM --identities $userID

PowerShell do Azure

O seguinte comando Update-AzVM configura sua VM do Docker com a identidade atribuída pelo usuário:

$vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myDockerVM
Update-AzVM -ResourceGroupName myResourceGroup -VM $vm -IdentityType UserAssigned -IdentityID $userID

Conceder à identidade acesso ao registro de contêiner

CLI do Azure

Agora, configure a identidade para acessar o registro de contêiner. Primeiro, use o comando az acr show para obter a ID de recurso do registro:

resourceID=$(az acr show --resource-group myResourceGroup --name myContainerRegistry --query id --output tsv)

Use o comando az role assignment create para atribuir a função AcrPull à identidade. Esta função oferece permissões de pull ao registro. Para fornecer permissões de pull e push, atribua a função AcrPush.

az role assignment create --assignee $spID --scope $resourceID --role acrpull

PowerShell do Azure

Agora, configure a identidade para acessar o registro de contêiner. Primeiro, use o comando Get-AzContainerRegistry para obter a ID de recurso do registro:

$resourceID = (Get-AzContainerRegistry -ResourceGroupName myResourceGroup -Name myContainerRegistry).Id

Use o cmdlet New-AzRoleAssignment para atribuir a função AcrPull à identidade. Esta função oferece permissões de pull ao registro. Para fornecer permissões de pull e push, atribua a função AcrPush.

New-AzRoleAssignment -ObjectId $spID -Scope $resourceID -RoleDefinitionName AcrPull

Usar a identidade para acessar o registro

CLI do Azure

SSH para a máquina virtual do Docker que está configurada com a identidade. Execute os seguintes comandos da CLI do Azure, usando a CLI do Azure instalada na VM.

Primeiro, entre na CLI do Azure com az login, usando a identidade configurada na VM. Para <userID>, substitua a ID da identidade que você recuperou em uma etapa anterior.

az login --identity --username <userID>

Em seguida, faça a autenticação no registro com az acr login. Quando você usa esse comando, a CLI usa o token do Active Directory criado quando você executou az login para autenticar sua sessão com o registro de contêiner. (Dependendo da configuração da sua VM, você talvez precise executar esse comando e os comandos do docker com sudo.)

az acr login --name myContainerRegistry

Você deve ver uma mensagem Login succeeded. Você pode executar os comandos docker sem fornecer credenciais. Por exemplo, execute docker pull para efetuar pull da imagem aci-helloworld:v1, especificando o nome do servidor de logon do registro. O nome do servidor de logon consiste em seu nome de registro de contêiner (letras minúsculas) seguido por .azurecr.io - por exemplo, mycontainerregistry.azurecr.io.

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

PowerShell do Azure

SSH para a máquina virtual do Docker que está configurada com a identidade. Execute os comandos do Azure PowerShell a seguir usando o Azure PowerShell instalado na VM.

Primeiro, autentique-se no Azure PowerShell com Connect-AzAccount, usando a identidade configurada na VM. Para -AccountId, especifique uma ID do cliente da identidade.

$clientId = (Get-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Name myACRId).ClientId
Connect-AzAccount -Identity -AccountId $clientId

Em seguida, autentique-se no registro com Connect-AzContainerRegistry. Quando você usa esse comando, o Azure PowerShell usa o token do Active Directory criado quando você executou Connect-AzAccount para autenticar sua sessão com o registro de contêiner. (Dependendo da configuração da sua VM, você talvez precise executar esse comando e os comandos do docker com sudo.)

sudo pwsh -command Connect-AzContainerRegistry -Name myContainerRegistry

Você deve ver uma mensagem Login succeeded. Você pode executar os comandos docker sem fornecer credenciais. Por exemplo, execute docker pull para efetuar pull da imagem aci-helloworld:v1, especificando o nome do servidor de logon do registro. O nome do servidor de logon consiste em seu nome de registro de contêiner (letras minúsculas) seguido por .azurecr.io - por exemplo, mycontainerregistry.azurecr.io.

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

Exemplo 2: acessar uma identidade atribuída pelo sistema

Configurar a VM com uma identidade gerenciada pelo sistema

CLI do Azure

O comando az vm identity assign a seguir configura sua VM do Docker com uma identidade atribuída pelo sistema:

az vm identity assign --resource-group myResourceGroup --name myDockerVM

Use o comando az vm show para definir uma variável como o valor de principalId (a ID de entidade de serviço) da identidade da VM, para ser usada em etapas posteriores.

spID=$(az vm show --resource-group myResourceGroup --name myDockerVM --query identity.principalId --out tsv)

PowerShell do Azure

O seguinte comando Update-AzVM configura sua VM do Docker com uma identidade atribuída pelo sistema:

$vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myDockerVM
Update-AzVM -ResourceGroupName myResourceGroup -VM $vm -IdentityType SystemAssigned

Use o comando Get-AzVM para definir uma variável como o valor de principalId (a ID da entidade de serviço) da identidade da VM, para ser usada em etapas posteriores.

$spID = (Get-AzVM -ResourceGroupName myResourceGroup -Name myDockerVM).Identity.PrincipalId

Conceder à identidade acesso ao registro de contêiner

CLI do Azure

Agora, configure a identidade para acessar o registro de contêiner. Primeiro, use o comando az acr show para obter a ID de recurso do registro:

resourceID=$(az acr show --resource-group myResourceGroup --name myContainerRegistry --query id --output tsv)

Use o comando az role assignment create para atribuir a função AcrPull à identidade. Esta função oferece permissões de pull ao registro. Para fornecer permissões de pull e push, atribua a função AcrPush.

az role assignment create --assignee $spID --scope $resourceID --role acrpull

PowerShell do Azure

Agora, configure a identidade para acessar o registro de contêiner. Primeiro, use o comando Get-AzContainerRegistry para obter a ID de recurso do registro:

$resourceID = (Get-AzContainerRegistry -ResourceGroupName myResourceGroup -Name myContainerRegistry).Id

Use o cmdlet New-AzRoleAssignment para atribuir a função AcrPull à identidade. Esta função oferece permissões de pull ao registro. Para fornecer permissões de pull e push, atribua a função AcrPush.

New-AzRoleAssignment -ObjectId $spID -Scope $resourceID -RoleDefinitionName AcrPull

Usar a identidade para acessar o registro

CLI do Azure

SSH para a máquina virtual do Docker que está configurada com a identidade. Execute os seguintes comandos da CLI do Azure, usando a CLI do Azure instalada na VM.

Primeiro, autentique o CLI do Azure com az login, usando a identidade atribuída pelo sistema na VM.

az login --identity

Em seguida, faça a autenticação no registro com az acr login. Quando você usa esse comando, a CLI usa o token do Active Directory criado quando você executou az login para autenticar sua sessão com o registro de contêiner. (Dependendo da configuração da sua VM, você talvez precise executar esse comando e os comandos do docker com sudo.)

az acr login --name myContainerRegistry

Você deve ver uma mensagem Login succeeded. Você pode executar os comandos docker sem fornecer credenciais. Por exemplo, execute docker pull para efetuar pull da imagem aci-helloworld:v1, especificando o nome do servidor de logon do registro. O nome do servidor de logon consiste em seu nome de registro de contêiner (letras minúsculas) seguido por .azurecr.io - por exemplo, mycontainerregistry.azurecr.io.

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

PowerShell do Azure

SSH para a máquina virtual do Docker que está configurada com a identidade. Execute os comandos do Azure PowerShell a seguir usando o Azure PowerShell instalado na VM.

Primeiro, autentique-se no Azure PowerShell com Connect-AzAccount, usando a identidade atribuída pelo sistema na VM.

Connect-AzAccount -Identity

Em seguida, autentique-se no registro com Connect-AzContainerRegistry. Quando você usa esse comando, o PowerShell usa o token do Active Directory criado quando você executou Connect-AzAccount para autenticar sua sessão com o registro de contêiner. (Dependendo da configuração da sua VM, você talvez precise executar esse comando e os comandos do docker com sudo.)

sudo pwsh -command Connect-AzContainerRegistry -Name myContainerRegistry

Você deve ver uma mensagem Login succeeded. Você pode executar os comandos docker sem fornecer credenciais. Por exemplo, execute docker pull para efetuar pull da imagem aci-helloworld:v1, especificando o nome do servidor de logon do registro. O nome do servidor de logon consiste em seu nome de registro de contêiner (letras minúsculas) seguido por .azurecr.io - por exemplo, mycontainerregistry.azurecr.io.

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

Próximas etapas

Neste artigo, você aprendeu sobre identidades gerenciadas com o Registro de Contêiner do Azure e como:

• Habilitar uma identidade atribuída pelo usuário ou pelo sistema em uma VM do Azure
• Conceder à identidade o acesso ao registro de contêiner do Azure
• Use a identidade gerenciada para acessar o registro e efetuar pull de uma imagem de contêiner

• Aprenda sobre identidades gerenciadas dos recursos do Azure.
• Saiba como usar uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário com o Serviço de Aplicativo e o Registro de Contêiner do Azure.
• Saiba como implantar uma imagem de contêiner do Registro de Contêiner do Azure usando uma identidade gerenciada.