Compartilhar via

Migrar da identidade gerenciada do pod para a identidade da carga de trabalho

  • Artigo

Este artigo se concentra na migração de uma identidade gerenciada por pod para a ID de Carga de Trabalho do Microsoft Entra para seu cluster do Serviço de Kubernetes do Azure (AKS). Ele também fornece diretrizes dependendo da versão da biblioteca de clientes do Azure Identity usada pelo aplicativo baseado em contêiner.

Se você não estiver familiarizado com a ID de Carga de Trabalho do Microsoft Entra, consulte o artigo visão geral a seguir.

Antes de começar

A CLI do Azure, versão 2.47.0 ou posterior. Execute az --version para localizar a versão e az upgrade para atualizar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

Cenários de migração

Esta seção explica as opções de migração disponíveis dependendo de qual versão do SDK de Azure Identity está instalada.

Para qualquer um dos cenários, você precisa ter a confiança federada configurada antes de atualizar o aplicativo para usar a identidade da carga de trabalho. Seguem as etapas mínimas necessárias:

Migrar da versão mais recente

Se o aplicativo já estiver usando a versão mais recente do SDK do Azure Identity, execute as seguintes etapas para concluir a configuração de autenticação:

  • Implante a identidade da carga de trabalho em paralelo com a identidade gerenciada por pod. Você pode reiniciar a implantação do aplicativo para começar a usar a identidade de carga de trabalho, onde ela injeta as anotações OIDC no aplicativo automaticamente.
  • Após verificar se o aplicativo é capaz de autenticar-se com êxito, você pode remover as anotações da identidade gerenciada por pod do aplicativo e, em seguida, remover o complemento da identidade gerenciada por pod.

Migrar da versão mais antiga

Se o aplicativo não estiver usando a versão mais recente do SDK do Azure Identity, haverá duas opções:

  • Você pode usar um sidecar de migração que fornecemos em seus aplicativos Linux, que faz o proxy das transações IMDS que seu aplicativo faz para OpenID Connect (OIDC). O sidecar de migração não é para ser usado como uma solução em longo prazo, mas uma maneira de começar a trabalhar rapidamente na identidade da carga de trabalho. Execute as etapas a seguir para:

    • Implantar a carga de trabalho com sidecar de migração para fazer proxy das transações IMDS do aplicativo.
    • Verifique se as transações de autenticação estão sendo concluídas com sucesso.
    • Agende o trabalho para que os aplicativos atualizem seus SDKs para uma versão com suporte.
    • Depois que os SDKs forem atualizados para a versão com suporte, você poderá remover o sidecar de proxy e reimplantar o aplicativo.

    Observação

    O sidecar de migração não é suportado para uso em produção. Esse recurso tem como objetivo dar a você tempo para migrar seus SDKs de aplicativos para uma versão com suporte e não pretende ser uma solução de longo prazo. O sidecar de migração só está disponível para contêineres do Linux, pois só fornece identidades gerenciadas por pods com pools de nós do Linux.

  • Regravar o aplicativo para usar a versão mais recente da biblioteca de clientes do Azure Identity. Em seguida, execute as etapas a seguir:

    • Reinicie a implantação do aplicativo para começar a autenticação usando a identidade de carga de trabalho.
    • Ao verificar que as transações de autenticação estão sendo concluídas com êxito, você poderá remover as anotações da identidade gerenciada por pod do aplicativo e, em seguida, remover o complemento da identidade gerenciada por pod.

Criar uma identidade gerenciada

Se você não tiver uma identidade gerenciada criada e atribuída ao pod, execute as etapas a seguir para criar e conceder as permissões necessárias para armazenamento, Key Vault ou outros recursos dos quais seu aplicativo precise para autenticar no Azure.

  1. Use o comando az account set da CLI do Azure para definir uma assinatura específica como a assinatura ativa atual. Em seguida, use o comando az identity create para criar uma identidade gerenciada.

    az account set --subscription "subscriptionID"

    az identity create --name "userAssignedIdentityName" --resource-group "resourceGroupName" --location "location" --subscription "subscriptionID"

    export USER_ASSIGNED_CLIENT_ID="$(az identity show --resource-group "resourceGroupName" --name "userAssignedIdentityName" --query 'clientId' -otsv)"

  2. Conceda à identidade gerenciada as permissões necessárias para acessar os recursos no Azure de que ela precisa. Para obter informações sobre como fazer isso, confira Atribuir um acesso de identidade gerenciada a um recurso.

  3. Para obter a URL do Emissor OIDC e salvá-la em uma variável de ambiente, execute o comando a seguir. Substitua os valores padrão pelo nome do cluster e pelo nome do grupo de recursos.

    export AKS_OIDC_ISSUER="$(az aks show --name myAKSCluster --resource-group myResourceGroup --query "oidcIssuerProfile.issuerUrl" -o tsv)"

    A variável deve conter a URL do emissor, semelhante ao seguinte exemplo:

    https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/

    Por padrão, o Emissor está definido para usar a URL de base https://{region}.oic.prod-aks.azure.com/{uuid}, em que o valor de {region} corresponde ao local em que o cluster do AKS está implantado. O valor {uuid} representa a chave OIDC.

Criar uma conta de serviço do Kubernetes

Se você não tiver uma conta de serviço do Kubernetes dedicada criada para esse aplicativo, execute as etapas a seguir para criar e, em seguida, anote-a com a ID do cliente da identidade gerenciada criada na etapa anterior. Use o comando az aks get-credentials e substitua os valores pelo nome do cluster e o nome do grupo de recursos.

az aks get-credentials --name myAKSCluster --resource-group "${RESOURCE_GROUP}"

Copie e cole a entrada de várias linhas a seguir na CLI do Azure.

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    azure.workload.identity/client-id: ${USER_ASSIGNED_CLIENT_ID}
  name: ${SERVICE_ACCOUNT_NAME}
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
EOF

A seguinte saída é semelhante à criação bem-sucedida da identidade:

Serviceaccount/workload-identity-sa created

Estabelecer uma credencial de identidade federada

Use o comando az identity federated-credential create para criar a credencial de identidade federada entre a identidade gerenciada, o emissor da conta de serviço e o assunto. Substitua os valores resourceGroupName, userAssignedIdentityName, federatedIdentityName, serviceAccountNamespace e serviceAccountName.

az identity federated-credential create --name federatedIdentityName --identity-name userAssignedIdentityName --resource-group resourceGroupName --issuer ${AKS_OIDC_ISSUER} --subject system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME} --audience api://AzureADTokenExchange

Observação

Leva alguns segundos para que a credencial de identidade federada seja propagada após ser inicialmente adicionada. Se uma solicitação de token for feita imediatamente após a adição da credencial de identidade federada, isso poderá levar a uma falha por alguns minutos enquanto o cache for preenchido no diretório com os dados antigos. Para evitar esse problema, você pode adicionar um pequeno atraso depois de adicionar a credencial de identidade federada.

Implantar a carga de trabalho com sidecar de migração

Observação

O sidecar de migração não é suportado para uso em produção. Esse recurso tem como objetivo dar a você tempo para migrar seus SDKs de aplicativos para uma versão com suporte e não pretende ser uma solução de longo prazo. O sidecar de migração é apenas para contêineres Linux, pois as identidades gerenciadas por pods estavam disponíveis apenas em pools de nós do Linux.

Se o aplicativo estiver usando a identidade gerenciada e ainda depender do IMDS para obter um token de acesso, você poderá usar o sidecar de migração de identidade de carga de trabalho para começar a migrar para a identidade da carga de trabalho. Esse sidecar é uma solução de migração e, nos aplicativos de longo prazo, você deve modificar o código deles para usar os SDKs de Identidade do Azure mais recentes que dão suporte à declaração do cliente.

Para atualizar ou implantar a carga de trabalho, adicione essas anotações de pod somente se você quiser usar o sidecar de migração. Injete os seguintes valores de anotação para usar o sidecar na especificação do pod:

  • azure.workload.identity/inject-proxy-sidecar - o valor é true or false
  • azure.workload.identity/proxy-sidecar-port - o valor é a porta desejada do sidecar do proxy. O valor padrão é 8000.

Quando um pod com as anotações acima é criado, o webhook de mutação da Identidade de Carga de Trabalho do Azure injeta automaticamente o sidecar de contêiner de entrada e proxy na especificação do pod.

O webhook que já está em execução adiciona os seguintes snippets YAML à implantação do pod. Veja a seguir um exemplo da especificação do pod mutado:

apiVersion: v1
kind: Pod
metadata:
  name: httpbin-pod
  labels:
    app: httpbin
    azure.workload.identity/use: "true"
  annotations:
    azure.workload.identity/inject-proxy-sidecar: "true"
spec:
  serviceAccountName: workload-identity-sa
  initContainers:
  - name: init-networking
    image: mcr.microsoft.com/oss/azure/workload-identity/proxy-init:v1.1.0
    securityContext:
      capabilities:
        add:
        - NET_ADMIN
        drop:
        - ALL
      privileged: true
      runAsUser: 0
    env:
    - name: PROXY_PORT
      value: "8000"
  containers:
  - name: nginx
    image: nginx:alpine
    ports:
    - containerPort: 80
  - name: proxy
    image: mcr.microsoft.com/oss/azure/workload-identity/proxy:v1.1.0
    ports:
    - containerPort: 8000

Essa configuração se aplica a qualquer configuração em que um pod está sendo criado. Depois de atualizar ou implantar seu aplicativo, você pode verificar se o pod está em um estado em execução usando o comando kubectl describe pod. Substitua o valor podName pelo nome da imagem do pod implantado.

kubectl describe pods podName

Para verificar se o pod está passando transações IMDS, use o comando kubectl logs. Substitua o valor podName pelo nome da imagem do pod implantado:

kubectl logs podName

A saída de log a seguir se assemelha à comunicação bem-sucedida por meio do sidecar proxy. Verifique se os logs mostram que um token foi adquirido com êxito e que a operação GET foi bem-sucedida.

I0926 00:29:29.968723       1 proxy.go:97] proxy "msg"="starting the proxy server" "port"=8080 "userAgent"="azure-workload-identity/proxy/v0.13.0-12-gc8527f3 (linux/amd64) c8527f3/2022-09-26-00:19"
I0926 00:29:29.972496       1 proxy.go:173] proxy "msg"="received readyz request" "method"="GET" "uri"="/readyz"
I0926 00:29:30.936769       1 proxy.go:107] proxy "msg"="received token request" "method"="GET" "uri"="/metadata/identity/oauth2/token?resource=https://management.core.windows.net/api-version=2018-02-01&client_id=<client_id>"
I0926 00:29:31.101998       1 proxy.go:129] proxy "msg"="successfully acquired token" "method"="GET" "uri"="/metadata/identity/oauth2/token?resource=https://management.core.windows.net/api-version=2018-02-01&client_id=<client_id>"

Remover identidades gerenciadas por pod

Depois de concluir o teste e o aplicativo conseguir obter um token usando o sidecar do proxy, você poderá remover o mapeamento de identidade gerenciado por pod do Microsoft Entra para o pod do seu cluster e remover a identidade.

  1. Execute o comando az aks pod-identity delete para remover a identidade do pod. Isso só deve ser feito depois que todos os pods no namespace que usarem o mapeamento de identidade gerenciado por pod migrarem para usar o sidecar.

    az aks pod-identity delete --name podIdentityName --namespace podIdentityNamespace --resource-group myResourceGroup --cluster-name myAKSCluster

Próximas etapas

Este artigo mostrou como configurar seu pod para autenticar usando uma identidade de carga de trabalho como uma opção de migração. Para obter mais informações sobre a ID da Carga de Trabalho do Microsoft Entra, consulte o artigo de Visão geral a seguir.