Partilhar 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 Kubernetes do Azure (AKS). Ele também fornece orientação dependendo da versão da biblioteca de cliente do Azure Identity usada pelo seu aplicativo baseado em contêiner.

Se você não estiver familiarizado com o ID de carga de trabalho do Microsoft Entra, consulte o seguinte artigo Visão geral .

Antes de começar

A CLI do Azure versão 2.47.0 ou posterior. Execute az --version para localizar a versão e execute az upgrade para atualizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).

Cenários de migração

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

Para qualquer cenário, você precisa ter a confiança federada configurada antes de atualizar seu aplicativo para usar a identidade da carga de trabalho. Seguem-se os passos mínimos necessários:

Migrar da versão mais recente

Se seu 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 pelo pod. Você pode reiniciar a implantação do aplicativo para começar a usar a identidade da carga de trabalho, onde ela injeta as anotações OIDC no aplicativo automaticamente.
  • Depois de verificar se o aplicativo é capaz de se autenticar com êxito, você pode remover as anotações de identidade gerenciadas pelo pod do seu aplicativo e, em seguida, remover o complemento de identidade gerenciado pelo pod.

Migrar da versão mais antiga

Se seu aplicativo não estiver usando a versão mais recente do SDK do Azure Identity, você terá 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 o OpenID Connect (OIDC). O sidecar de migração não pretende ser uma solução de longo prazo, mas uma maneira de começar a trabalhar rapidamente na identidade da carga de trabalho. Efetue os seguintes passos:

    • Implante 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 foram concluídas com êxito.
    • Agende o trabalho para que os aplicativos atualizem os SDKs para uma versão suportada.
    • Depois que os SDKs forem atualizados para a versão suportada, você poderá remover o sidecar do proxy e reimplantar o aplicativo.

    Nota

    O sidecar de migração não é suportado para uso em produção. Esta funcionalidade destina-se a dar-lhe tempo para migrar os SDKs da sua aplicação para uma versão suportada, e não pretende ser uma solução a longo prazo. O sidecar de migração só está disponível para contêineres Linux, devido ao fornecimento apenas de identidades gerenciadas por pod com pools de nós Linux.

  • Reescreva seu aplicativo para dar suporte à versão mais recente da biblioteca de cliente do Azure Identity . Depois, execute as seguintes etapas:

    • Reinicie a implantação do aplicativo para começar a autenticar usando a identidade da carga de trabalho.
    • Depois de verificar se as transações de autenticação foram concluídas com êxito, você pode remover as anotações de identidade gerenciadas pelo pod do seu aplicativo e, em seguida, remover o complemento de identidade gerenciado pelo pod.

Criar uma identidade gerenciada

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

  1. Use o comando Azure CLI az account set para definir uma assinatura específica como sendo 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 necessários. Para obter informações sobre como fazer isso, consulte Atribuir um acesso de identidade gerenciado a um recurso.

  3. Para obter a URL do emissor OIDC e salvá-la em uma variável ambiental, execute o seguinte comando. Substitua os valores padrão para o nome do cluster e o 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 o URL do Emissor semelhante ao exemplo a seguir:

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

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

Criar conta de serviço do Kubernetes

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

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

Copie e cole a seguinte entrada de várias linhas 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 saída a seguir se assemelha à criação bem-sucedida da identidade:

Serviceaccount/workload-identity-sa created

Estabelecer confiança de credenciais 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

Nota

A propagação da credencial de identidade federada demora alguns segundos depois de ter sido 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, pois o cache é preenchido no diretório com dados antigos. Para evitar esse problema, você pode adicionar um pequeno atraso após adicionar a credencial de identidade federada.

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

Nota

O sidecar de migração não é suportado para uso em produção. Esta funcionalidade destina-se a dar-lhe tempo para migrar os SDKs da sua aplicação para uma versão suportada, e não pretende ser uma solução a longo prazo. O sidecar de migração é apenas para contêineres Linux, pois as identidades gerenciadas por pod estavam disponíveis apenas em pools de nós Linux.

Se seu aplicativo estiver usando 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 de carga de trabalho. Este sidecar é uma solução de migração e, nos aplicativos de longo prazo, você deve modificar seu código 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 quiser usar o sidecar de migração. Você injeta os seguintes valores de anotação para usar o sidecar na especificação do seu pod:

  • azure.workload.identity/inject-proxy-sidecar - o valor é true ou false
  • azure.workload.identity/proxy-sidecar-port - value é a porta desejada para o sidecar proxy. O valor predefinido é 8000.

Quando um pod com as anotações acima é criado, o webhook mutante do Azure Workload Identity injeta automaticamente o sidecar init-container e proxy na especificação do pod.

O webhook que já está em execução adiciona os seguintes trechos de YAML à implantação do pod. Segue-se 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 esteja sendo criado. Depois de atualizar ou implantar seu aplicativo, você pode verificar se o pod está em um estado de 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 seu pod implantado:

kubectl logs podName

A saída de log a seguir se assemelha à comunicação bem-sucedida através do sidecar proxy. Verifique se os logs mostram que um token foi adquirido com êxito e se 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 identidade gerenciada por pod

Depois de concluir o teste e o aplicativo conseguir obter um token usando o sidecar proxy, você pode remover o mapeamento de identidade gerenciado pelo pod do Microsoft Entra do cluster e, em seguida, remover a identidade.

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

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

Próximos passos

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 o ID de carga de trabalho do Microsoft Entra, consulte o seguinte artigo Visão geral .