Compartilhar via

Implantar e configurar a identidade da carga de trabalho (versão prévia) em um cluster Serviço de Kubernetes do Azure (AKS)

  • Artigo

O AKS (Serviço de Kubernetes do Azure) é um serviço de Kubernetes gerenciado que permite implantar e gerenciar clusters do Kubernetes rapidamente. Este artigo mostra como:

  • Implante um cluster do AKS usando a CLI do Azure com o emissor do OpenID Connect e uma ID de carga de trabalho do Microsoft Entra.
  • Crie uma ID de Carga de Trabalho do Microsoft Entra e uma conta de serviço do Kubernetes.
  • Configurar a identidade gerenciada para federação de token.
  • Implantar a carga de trabalho e verificar 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.

Este artigo pressupõe que você tenha uma compreensão básica dos conceitos do Kubernetes. Para obter mais informações, confira Principais conceitos do Kubernetes para o AKS (Serviço de Kubernetes do Azure). Se você não estiver familiarizado com a ID de Carga de Trabalho do Microsoft Entra, consulte o artigo visão geral a seguir.

Pré-requisitos

  • Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.
  • Este artigo requer a versão 2.47.0 ou posterior da CLI do Azure. Se você está 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 obter mais informações sobre o acesso e identidade do AKS, confiraOpções de acesso e identidade para o Serviço de Kubernetes do Azure (AKS).
  • Se você tiver várias assinaturas do Azure, selecione a ID de assinatura apropriada na qual os recursos devem ser cobrados usando o comando az account set.

Observação

Você pode usar Service Connector para ajudá-lo a configurar algumas etapas automaticamente. Veja também: Tutorial: conectar-se à conta de armazenamento do Azure no Serviço de Kubernetes do Azure (AKS) com o conector de serviço usando a identidade da carga de trabalho.

Definir a assinatura ativa

Primeiro, defina sua assinatura como a assinatura ativa atual chamando o comando az account set e passando sua ID de assinatura.

az account set --subscription <subscription-id>

Exportar variáveis de ambiente

Para ajudar a simplificar as etapas para configurar as identidades necessárias, as etapas abaixo definem variáveis de ambiente referenciadas nos exemplos deste artigo. Lembre-se de substituir os valores mostrados por seus próprios valores:

export RESOURCE_GROUP="myResourceGroup"
export LOCATION="eastus"
export CLUSTER_NAME="myAKSCluster"
export SERVICE_ACCOUNT_NAMESPACE="default"
export SERVICE_ACCOUNT_NAME="workload-identity-sa"
export SUBSCRIPTION="$(az account show --query id --output tsv)"
export USER_ASSIGNED_IDENTITY_NAME="myIdentity"
export FEDERATED_IDENTITY_CREDENTIAL_NAME="myFedIdentity"
# Include these variables to access key vault secrets from a pod in the cluster.
export KEYVAULT_NAME="keyvault-workload-id"
export KEYVAULT_SECRET_NAME="my-secret"

Criar um grupo de recursos

Um grupo de recursos do Azure é um grupo lógico no qual os recursos do Azure são implantados e gerenciados. Ao criar um grupo de recursos, você é solicitado a especificar um local. Essa é a localização na qual os metadados do grupo de recursos são armazenados e na qual os recursos são executados no Azure, caso você não especifique outra região durante a criação de recursos.

Crie um grupo de recursos chamando o comando az group create:

az group create --name "${RESOURCE_GROUP}" --location "${LOCATION}"

O exemplo de saída a seguir mostra a criação bem-sucedida de um grupo de recursos:

{
  "id": "/subscriptions/<guid>/resourceGroups/myResourceGroup",
  "location": "eastus",
  "managedBy": null,
  "name": "myResourceGroup",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null
}

Criar um cluster AKS

Crie um cluster do AKS usando o comando az aks create com o parâmetro --enable-oidc-issuer para habilitar o emissor do OIDC. O exemplo a seguir cria um cluster com um único nó:

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 será concluído e retornará informações no formato JSON sobre o cluster.

Observação

Quando você cria um cluster do AKS, um segundo grupo de recursos é criado automaticamente para armazenar os recursos do AKS. Para obter mais informações, confira Por que dois grupos de recursos são criados com o AKS?.

Atualizar um cluster de AKS existente

Você pode atualizar um cluster do AKS para usar o emissor do OIDC e habilitar a identidade da carga de trabalho chamando o comando az aks update com os parâmetros --enable-oidc-issuer e --enable-workload-identity. O exemplo a seguir atualiza um cluster existente:

az aks update \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --enable-oidc-issuer \
    --enable-workload-identity

Recuperar a URL do emissor do OIDC

Para obter a URL do emissor OIDC e salvá-la em uma variável ambiental, execute o seguinte comando:

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 seguinte exemplo:

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 base https://{region}.oic.prod-aks.azure.com/{tenant_id}/{uuid}, em que o valor para {region} corresponde ao local ao qual o cluster do AKS é implantado. O valor {uuid} representa a chave OIDC, que é um guid gerado aleatoriamente para cada cluster que está imutável.

Criar uma identidade gerenciada

Chame o comando az identity create para criar uma identidade gerenciada.

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

Em seguida, crie uma variável para a ID do cliente da identidade gerenciada.

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

Crie uma conta de serviço do Kubernetes e 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 "${CLUSTER_NAME}" --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 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

Chame 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. Para obter mais informações sobre credenciais de identidade federadas no Microsoft Entra, consulte Visão geral das credenciais de identidade federadas no Microsoft Entra 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

Observação

Leva alguns segundos para que a credencial de identidade federada se propague após a adição. 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 depois de adicionar a credencial de identidade federada.

Implantar seu aplicativo

Quando você implanta seus pods de aplicativos, o manifesto deve fazer referência à conta de serviço criada na etapa Criar conta de serviço do Kubernetes. O manifesto a seguir mostra como referenciar a conta, especificamente as propriedades de metadados\namespace e spec\serviceAccountName. Especifique uma imagem para <image> e um nome de contêiner para <containerName>:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: sample-workload-identity
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
  labels:
    azure.workload.identity/use: "true"  # Required. Only pods with this label can use workload identity.
spec:
  serviceAccountName: ${SERVICE_ACCOUNT_NAME}
  containers:
    - image: <image>
      name: <containerName>
EOF

Importante

Verifique se os pods de aplicativo que usam a identidade da carga de trabalho incluem o rótulo azure.workload.identity/use: "true" na especificação do pod. Caso contrário, os pods falharão após serem reiniciados.

Conceder permissões para acessar o Azure Key Vault

As instruções nesta etapa mostram como acessar segredos, chaves ou certificados em um cofre de chaves do Azure do pod. Os exemplos nesta seção configuram o acesso a segredos no cofre de chaves para a identidade da carga de trabalho, mas você pode executar etapas semelhantes para configurar o acesso a chaves ou certificados.

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

  1. Crie um cofre de chaves com proteção contra limpeza e autorização RBAC habilitada. Você também poderá usar um cofre de chaves existente se ele estiver configurado para a proteção contra limpeza e a autorização do RBAC:

    export KEYVAULT_RESOURCE_GROUP="myResourceGroup"
export KEYVAULT_NAME="myKeyVault"

az keyvault create \
    --name "${KEYVAULT_NAME}" \
    --resource-group "${KEYVAULT_RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --enable-purge-protection \
    --enable-rbac-authorization

  2. Atribua a si mesmo a função RBAC Key Vault Secrets Officer para que você possa criar um segredo no novo cofre de chaves:

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

az role assignment create --assignee "\<user-email\>" \
    --role "Key Vault Secrets Officer" \
    --scope "${KEYVAULT_RESOURCE_ID}"

  3. Crie um segredo no cofre de chaves:

    export KEYVAULT_SECRET_NAME="my-secret"

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

  4. Atribua a função usuário de segredos do Key Vault à identidade gerenciada atribuída pelo usuário que você criou anteriormente. Esta etapa fornece a permissão de identidade gerenciada para ler segredos do cofre de chaves:

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

az role assignment create \
    --assignee-object-id "${IDENTITY_PRINCIPAL_ID}" \
    --role "Key Vault Secrets User" \
    --scope "${KEYVAULT_RESOURCE_ID}" \
    --assignee-principal-type ServicePrincipal

  5. Crie uma variável de ambiente para a URL do cofre de chaves:

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

  6. Implante um pod que faça referência à conta de serviço e à URL do cofre de chaves:

    cat <<EOF | kubectl apply -f -
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

Para verificar se todas as propriedades são injetadas corretamente pelo webhook, use o comando kubectl describe:

kubectl describe pod sample-workload-identity-key-vault | grep "SECRET_NAME:"

Se for bem-sucedido, a saída deverá ser semelhante à seguinte:

      SECRET_NAME:                 ${KEYVAULT_SECRET_NAME}

Para verificar se o POD consegue obter um token e acessar o recurso, utilize o comando kubectl logs:

kubectl logs sample-workload-identity-key-vault

Se for bem-sucedido, a saída deverá ser semelhante à seguinte:

I0114 10:35:09.795900       1 main.go:63] "successfully got secret" secret="Hello\\!"

Importante

As atribuições de função RBAC do Azure podem levar até dez minutos para serem propagadas. Se o pod não conseguir acessar o segredo, talvez seja necessário aguardar a propagação da atribuição de função. Para saber mais, confira Solucionar problemas do RBAC do Azure.

Desabilitar a identidade da carga de trabalho

Para desabilitar a ID de Carga de Trabalho do Microsoft Entra no cluster do AKS em que ela foi habilitada e configurada, execute o seguinte comando:

az aks update \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --disable-workload-identity

Próximas etapas

Neste artigo, você implantou um cluster do Kubernetes e configurou-o para usar uma identidade de carga de trabalho em preparação para cargas de trabalho de aplicativo a serem autenticadas 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 clientes do Azure Identity. Se você não conseguir reescrever seu aplicativo para usar a versão mais recente da biblioteca de clientes, poderá configurar o pod do aplicativo para autenticar usando a identidade gerenciada com identidade de carga de trabalho como uma solução de migração de curto prazo.

A integração do Conector de Serviço ajuda a simplificar a configuração de conexão para cargas de trabalho do AKS e serviços de backup do Azure. De maneira segura, ele lida com autenticação e configurações de rede e segue as práticas recomendadas para se conectar aos serviços do Azure. Para obter mais informações, consulte Conectar-se ao Serviço OpenAI do Azure no AKS usando a Identidade da Carga de Trabalho e a introdução do Conector de Serviço.