Implementar e configurar o ID de Workload do Microsoft Entra num cluster Azure Kubernetes Service (AKS)

Neste artigo, aprende como implementar e configurar um cluster Azure Kubernetes Service (AKS) com o Microsoft Entra Workload ID. Os passos deste artigo incluem:

Crie um novo cluster AKS ou atualize um cluster AKS existente usando o Azure CLI com o emissor OpenID Connect (OIDC) e o Microsoft Entra Workload ID ativado.
Crie uma identidade de carga de trabalho e uma conta de serviço Kubernetes.
Configure a identidade gerenciada para federação de tokens.
Implante a carga de trabalho e verifique a autenticação com a identidade da carga de trabalho.
Opcionalmente, conceda a um pod no cluster acesso a segredos em um cofre de chaves do Azure.

Pré-requisitos

Se não tiver uma conta do Azure, crie uma conta gratuita antes de começar.
Este artigo requer a versão 2.47.0 ou posterior da CLI do Azure. Se estiver usando o Azure Cloud Shell, a versão mais recente já está instalada.
Verifique se a identidade que você está usando para criar seu cluster tem as permissões mínimas apropriadas. Para mais informações, consulte Opções de Acesso e identidade para o Azure Kubernetes Service (AKS).
Se você tiver várias assinaturas do Azure, selecione a ID de assinatura apropriada na qual os recursos devem ser cobrados usando o az account set comando.

Nota

Você pode usar o Service Connector para ajudá-lo a configurar algumas etapas automaticamente. Para mais informações, veja Tutorial: Conectar-se à conta de armazenamento Azure no Azure Kubernetes Service (AKS) com Service Connector usando o Microsoft Entra Workload ID.

Criar um grupo de recursos

Crie um grupo de recursos usando o comando az group create.

export RANDOM_ID="$(openssl rand -hex 3)"
export RESOURCE_GROUP="myResourceGroup$RANDOM_ID"
export LOCATION="<your-preferred-region>"
az group create --name "${RESOURCE_GROUP}" --location "${LOCATION}"

Ativar o emissor OIDC e o ID de Carga de Trabalho Microsoft Entra num cluster AKS

Pode ativar o emissor OIDC e o Microsoft Entra Workload ID num cluster AKS novo ou existente.

Criar um novo cluster do AKS
Atualizar um cluster AKS existente

Crie um cluster AKS usando o comando az aks create com o parâmetro --enable-oidc-issuer para ativar o emissor OIDC e o parâmetro --enable-workload-identity para ativar o ID de Carga de Trabalho Microsoft Entra. O exemplo a seguir cria um cluster com um único nó:
```
export CLUSTER_NAME="myAKSCluster$RANDOM_ID"
az aks create \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --enable-oidc-issuer \
    --enable-workload-identity \
    --generate-ssh-keys
```
Após alguns minutos, o comando conclui e retorna informações formatadas em JSON sobre o cluster.

Atualize um cluster AKS existente para ativar o emissor OIDC e o ID de Carga de Trabalho Microsoft Entra usando o comando az aks update com os parâmetros --enable-oidc-issuer e --enable-workload-identity.
```
az aks update \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --enable-oidc-issuer \
    --enable-workload-identity
```

Recuperar o URL do emissor OIDC

Obtenha o URL do emissor OIDC e guarde-o numa variável ambiental usando o comando [az aks showaz-aks-show].
```
export AKS_OIDC_ISSUER="$(az aks show --name "${CLUSTER_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --query "oidcIssuerProfile.issuerUrl" \
    --output tsv)"
```
A variável de ambiente deve conter a URL do emissor, semelhante ao exemplo a seguir:
```
https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/11111111-1111-1111-1111-111111111111/
```
Por padrão, o emissor é definido para usar a URL https://{region}.oic.prod-aks.azure.com/{tenant_id}/{uuid}base, onde o valor for {region} corresponde ao local no qual o cluster AKS está implantado. O valor {uuid} representa a chave OIDC, que é um GUID gerado aleatoriamente e imutável para cada cluster.

Criar uma identidade gerenciada

Obtenha o ID da subscrição e guarde-o numa variável de ambiente usando o comando [az account show][az-account-show].
```
export SUBSCRIPTION="$(az account show --query id --output tsv)"
```

Crie uma identidade gerenciada atribuída pelo usuário usando o az identity create comando.

export USER_ASSIGNED_IDENTITY_NAME="myIdentity$RANDOM_ID"
az identity create \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --subscription "${SUBSCRIPTION}"

O exemplo de saída a seguir mostra a criação bem-sucedida de uma identidade gerenciada:

{
  "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroupxxxxxx/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentityxxxxxx",
  "location": "eastus",
  "name": "myIdentityxxxxxx",
  "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "resourceGroup": "myResourceGroupxxxxxx",
  "systemData": null,
  "tags": {},
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Obtenha o ID do cliente da identidade gerida e guarde-o numa variável de ambiente usando o comando [az identity show][az-identity-show].

export USER_ASSIGNED_CLIENT_ID="$(az identity show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'clientId' \
    --output tsv)"

Criar uma conta de serviço do Kubernetes

Conecte-se ao cluster AKS usando o az aks get-credentials comando.

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

Crie uma conta de serviço Kubernetes e anote-a com o ID do cliente da identidade gerida aplicando o seguinte manifesto usando o kubectl apply comando:

export SERVICE_ACCOUNT_NAME="workload-identity-sa$RANDOM_ID"
export SERVICE_ACCOUNT_NAMESPACE="default"
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 mostra a criação bem-sucedida da identidade da carga de trabalho:

serviceaccount/workload-identity-sa created

Criar a credencial de identidade federada

Crie uma credencial de identidade federada entre a identidade gerida, o emissor da conta de serviço e o sujeito que utiliza o az identity federated-credential create comando.
```
export FEDERATED_IDENTITY_CREDENTIAL_NAME="myFedIdentity$RANDOM_ID"
az identity federated-credential create \
    --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} \
    --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --issuer "${AKS_OIDC_ISSUER}" \
    --subject system:serviceaccount:"${SERVICE_ACCOUNT_NAMESPACE}":"${SERVICE_ACCOUNT_NAME}" \
    --audience api://AzureADTokenExchange
```
Nota

Leva alguns segundos para que a credencial de identidade federada se propague depois de adicionada. Se uma solicitação de token for feita imediatamente após a adição da credencial de identidade federada, a solicitação poderá falhar até que o cache seja atualizado. Para evitar esse problema, você pode adicionar um pequeno atraso após adicionar a credencial de identidade federada.

Para obter mais informações sobre credenciais de identidade federada no Microsoft Entra, consulte Visão geral das credenciais de identidade federada no Microsoft Entra ID.

Crie um cofre de chaves com autorização Azure RBAC

O exemplo a seguir mostra como usar o modelo de permissão de controle de acesso baseado em função do Azure (Azure RBAC) para conceder acesso ao pod ao cofre de chaves. Para obter mais informações sobre o modelo de permissão do Azure RBAC para o Azure Key Vault, consulte Conceder permissão a aplicativos para acessar um cofre de chaves do Azure usando o Azure RBAC.

Crie um cofre de chaves com proteção contra purga e autorização Azure RBAC ativada usando o comando [az keyvault create][az-keyvault-create]. Você também pode usar um cofre de chaves existente, se este estiver configurado para proteção contra eliminação e autorização RBAC do Azure.

export KEYVAULT_NAME="keyvault-workload-id$RANDOM_ID" # Ensure the key vault name is between 3-24 characters
az keyvault create \
    --name "${KEYVAULT_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --enable-purge-protection \
    --enable-rbac-authorization

Obtenha o ID do recurso do cofre de chaves e guarde-o numa variável de ambiente usando o comando [az keyvault show][az-keyvault-show].

export KEYVAULT_RESOURCE_ID=$(az keyvault show --resource-group "${RESOURCE_GROUP}" \
    --name "${KEYVAULT_NAME}" \
    --query id \
    --output tsv)

Atribuir permissões RBAC para gestão de cofres de chaves

Obtenha o ID do objeto do chamador e guarde-o numa variável de ambiente usando o comando [az ad signed-in-user show][az-ad-signed-in-user-show].
```
export CALLER_OBJECT_ID=$(az ad signed-in-user show --query id -o tsv)
```
Atribui-te o papel de Oficial de Segredos do Cofre de Chaves RBAC Azure para que possas criar um segredo no novo cofre de chaves usando o comando [az role assignment create][az-role-assignment-create].
```
az role assignment create --assignee "${CALLER_OBJECT_ID}" \
    --role "Key Vault Secrets Officer" \
    --scope "${KEYVAULT_RESOURCE_ID}"
```

Criar e configurar o acesso secreto

Crie um segredo no cofre de chaves usando o comando [az keyvault secret set][az-keyvault-secret-set].

export KEYVAULT_SECRET_NAME="my-secret$RANDOM_ID"
az keyvault secret set \
    --vault-name "${KEYVAULT_NAME}" \
    --name "${KEYVAULT_SECRET_NAME}" \
    --value "Hello\!"

Obtenha o principal ID da identidade gerida atribuída pelo utilizador e guarde-o numa variável de ambiente usando o comando [az identity show][az-identity-show].

export IDENTITY_PRINCIPAL_ID=$(az identity show \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --query principalId \
    --output tsv)

Atribuir o papel Key Vault Secrets User à identidade gerida atribuída a utilizador usando o comando [az role assignment create][az-role-assignment-create]. Este passo dá à identidade gerida permissão para ler segredos do cofre de chaves.
```
az role assignment create \
    --assignee-object-id "${IDENTITY_PRINCIPAL_ID}" \
    --role "Key Vault Secrets User" \
    --scope "${KEYVAULT_RESOURCE_ID}" \
    --assignee-principal-type ServicePrincipal
```

Crie uma variável de ambiente para a URL do cofre de chaves usando o comando [az keyvault show][az-keyvault-show]:

export KEYVAULT_URL="$(az keyvault show \
    --resource-group "${RESOURCE_GROUP}" \
    --name ${KEYVAULT_NAME} \
    --query properties.vaultUri \
    --output tsv)"

Implementar um pod de verificação e testar o acesso

Implemente um pod para verificar se a identidade da carga de trabalho pode aceder ao segredo no cofre de chaves. O exemplo seguinte utiliza a imagem ghcr.io/azure/azure-workload-identity/msal-go, que contém uma aplicação de exemplo que recupera um segredo do Azure Key Vault usando a ID de carga de trabalho do Microsoft Entra:

kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
    name: sample-workload-identity-key-vault
    namespace: ${SERVICE_ACCOUNT_NAMESPACE}
    labels:
        azure.workload.identity/use: "true"
spec:
    serviceAccountName: ${SERVICE_ACCOUNT_NAME}
    containers:
      - image: ghcr.io/azure/azure-workload-identity/msal-go
        name: oidc
        env:
          - name: KEYVAULT_URL
            value: ${KEYVAULT_URL}
          - name: SECRET_NAME
            value: ${KEYVAULT_SECRET_NAME}
    nodeSelector:
        kubernetes.io/os: linux
EOF

Aguarde que o pod esteja no estado Ready usando o comando kubectl wait.

kubectl wait --namespace ${SERVICE_ACCOUNT_NAMESPACE} --for=condition=Ready pod/sample-workload-identity-key-vault --timeout=120s

Verifica se a SECRET_NAME variável de ambiente está definida no pod usando o kubectl describe comando.
```
kubectl describe pod sample-workload-identity-key-vault | grep "SECRET_NAME:"
```
Se for bem-sucedida, a saída deve ser semelhante ao exemplo a seguir:
```
SECRET_NAME: ${KEYVAULT_SECRET_NAME}
```
Verifica se os pods conseguem obter um token e aceder ao recurso usando o kubectl logs comando.
```
kubectl logs sample-workload-identity-key-vault
```
Se for bem-sucedida, a saída deve ser semelhante ao exemplo a seguir:
```
I0114 10:35:09.795900       1 main.go:63] "successfully got secret" secret="Hello\\!"
```
Importante

As atribuições de função do RBAC do Azure podem levar até 10 minutos para se propagar. Se o pod não conseguir acessar o segredo, talvez seja necessário aguardar a propagação da atribuição de função. Para obter mais informações, consulte Solucionar problemas do Azure RBAC.

Desative o ID de Workload do Microsoft Entra num cluster AKS

Desative o ID de carga de trabalho do Microsoft Entra no cluster AKS onde foi ativado e configurado. Em seguida, atualize o cluster AKS usando o comando az aks update com o parâmetro --disable-workload-identity.
```
az aks update \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --disable-workload-identity
```

Neste artigo, implementaste um cluster Kubernetes e configuraste-o para usar o ID de Workload Microsoft Entra em preparação para que as cargas de trabalho da aplicação se autenticassem com essa credencial. Agora você está pronto para implantar seu aplicativo e configurá-lo para usar a identidade da carga de trabalho com a versão mais recente da biblioteca de cliente do Azure Identity . Se não for possível reescrever seu aplicativo para usar a versão mais recente da biblioteca do cliente, você poderá configurar seu pod de aplicativo para autenticar usando identidade gerenciada com identidade de carga de trabalho como uma solução de migração de curto prazo.

A integração do Service Connector ajuda a simplificar a configuração de conexão para cargas de trabalho AKS e serviços de suporte do Azure. Ele lida com segurança com autenticação e configurações de rede e segue as práticas recomendadas para se conectar aos serviços do Azure. Para mais informações, consulte Como conectar-se ao Azure OpenAI em Modelos Foundry no AKS utilizando a Identidade de Trabalho Microsoft Entra e a introdução ao Service Connector.

Feedback

Esta página foi útil?

Last updated on 2025-12-10