Criar uma conta de serviço e configurar a identidade da carga de trabalho para a CLI agente do AKS (Serviço de Kubernetes do Azure) (versão prévia)

Este artigo mostra como criar a conta de serviço necessária e , opcionalmente , configurar a identidade da carga de trabalho para a CLI agente do AKS (Serviço de Kubernetes do Azure). A criação da conta de serviço é obrigatória para a implantação do modo de cluster, enquanto a configuração de identidade de carga de trabalho é opcional, mas recomendada para segurança aprimorada ao acessar recursos do Azure.

Pré-requisitos

Pré-requisitos de criação da conta de serviço:

• CLI do Azure versão 2.76 ou posterior. Verifique a versão usando o comando az version. Para instalar ou atualizar, consulte Instalar a CLI do Azure.

• Defina sua assinatura ativa do Azure usando o az account set comando.

  az account set --subscription "your-subscription-id-or-name"
  

• Você precisa de permissões suficientes para criar e gerenciar contas de serviço, funções e associações de função do Kubernetes.

Pré-requisitos para configuração da identidade de trabalho:

• Identidade de carga de trabalho habilitada no cluster AKS.
• Você precisa de permissões suficientes para criar e gerenciar identidades gerenciadas do Azure e criar credenciais de identidade federadas.

Definir variáveis

Primeiro, configure as variáveis necessárias para seu ambiente. Substitua os valores de preenchimento por seus dados reais do cluster e do Azure.

Variáveis necessárias para a criação da conta de serviço:

# Cluster information
export RESOURCE_GROUP="<YOUR_RESOURCE_GROUP>"
export CLUSTER_NAME="<YOUR_CLUSTER_NAME>"

# Service account configuration
export SERVICE_ACCOUNT_NAME="aks-mcp"
export SERVICE_ACCOUNT_NAMESPACE="<YOUR_NAMESPACE>"  # e.g., "kube-system" or custom namespace

Variáveis adicionais (somente se estiver configurando a identidade da carga de trabalho):

# Azure information for workload identity
export LOCATION="<YOUR_LOCATION>"
export SUBSCRIPTION="$(az account show --query id --output tsv)"

# Workload identity configuration
export USER_ASSIGNED_IDENTITY_NAME="aks-mcp-identity"
export FEDERATED_IDENTITY_CREDENTIAL_NAME="aks-mcp-fed-identity"

# Generate unique suffix for resource naming
export RANDOM_ID="$(openssl rand -hex 3)"

Criar uma conta de serviço do Kubernetes e atribuir permissões (obrigatório)

Criar a conta de serviço

Crie a conta de serviço no namespace de destino usando o seguinte comando:

kubectl create serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"

Criar permissões RBAC

Crie a Função e RoleBinding necessários para a conta de serviço com acesso de leitura para solução de problemas do aks-mcp. Aqui estão dois exemplos com base em seus requisitos de acesso:

Acesso de leitura em todo o cluster (recomendado para administradores de cluster)

1. Utilize este ClusterRoleBinding para conceder acesso somente leitura a todos os recursos do Kubernetes, exceto segredos, em todos os namespaces. Essa opção é recomendada para administradores de nível de cluster ou engenheiros de DevOps que precisam investigar e solucionar problemas em todo o cluster.

   cat <<EOF | kubectl apply -f -
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: aks-mcp-view-rolebinding
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: view
   subjects:
   - kind: ServiceAccount
     name: ${SERVICE_ACCOUNT_NAME}
     namespace: ${SERVICE_ACCOUNT_NAMESPACE}
   EOF
   

2. Verifique se os recursos foram criados com êxito usando os seguintes comandos:

   kubectl get serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"
   kubectl get clusterrolebinding aks-mcp-view-rolebinding
   

Acesso de leitura com escopo de namespace (para cenários de acesso limitado)

1. Use RoleBindings para conceder acesso somente leitura a todos os recursos do Kubernetes, exceto segredos somente em namespaces específicos. Essa opção é adequada para equipes ou usuários que devem ter acesso limitado a namespaces específicos em vez de todo o cluster. Repita essa RoleBinding para cada namespace que requer acesso.

   cat <<EOF | kubectl apply -f -
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: aks-mcp-view-rolebinding
     namespace: ${SERVICE_ACCOUNT_NAMESPACE}
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: view
   subjects:
   - kind: ServiceAccount
     name: ${SERVICE_ACCOUNT_NAME}
     namespace: ${SERVICE_ACCOUNT_NAMESPACE}
   EOF
   

2. Verifique se os recursos foram criados com êxito usando os seguintes comandos:

   kubectl get serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"
   kubectl get rolebinding aks-mcp-view-rolebinding --namespace "${SERVICE_ACCOUNT_NAMESPACE}"
   

Configurar a identidade da carga de trabalho para acesso a recursos do Azure (opcional)

As etapas a seguir são opcionais , mas recomendadas se você quiser habilitar a CLI agente para acessar recursos do Azure com segurança usando a identidade da carga de trabalho.

Verifique o status atual da identidade de carga de trabalho

Verifique se a identidade da carga de trabalho já está habilitada no cluster do AKS usando o az aks show comando.

az aks show --resource-group "${RESOURCE_GROUP}" --name "${CLUSTER_NAME}" --query "securityProfile.workloadIdentity.enabled"

Se a saída for true, a identidade de carga de trabalho está habilitada. Se null ou false, você precisa habilitá-lo.

Ativar identidade da carga de trabalho

Habilite a identidade da carga de trabalho no cluster AKS usando o comando az aks update com os sinalizadores --enable-workload-identity e --enable-oidc-issuer.

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

Recuperar a URL do emissor do OIDC

Obtenha a URL do emissor OIDC usando o comando e salve-a az aks show em uma variável de ambiente.

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/

Criar uma identidade gerenciada atribuída ao usuário

Crie uma identidade gerenciada atribuída pelo usuário para acesso a recursos do Azure usando o az identity create comando.

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",
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Obter a ID do cliente de identidade gerenciada

Obtenha a ID do cliente da identidade gerenciada usando-a az identity show e salve-a em uma variável de ambiente.

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

Atribuir a função necessária à identidade gerenciada

Atribua as funções necessárias à identidade gerenciada usando o az role assignment create comando.

O exemplo a seguir atribui a função "Leitor" no escopo da assinatura, o que permite que a CLI do agentic leia informações sobre os recursos do Azure. Ajuste a função e o escopo conforme necessário para seu caso de uso.

az role assignment create --role "Reader" \
    --assignee $USER_ASSIGNED_CLIENT_ID \
    --scope /subscriptions/${SUBSCRIPTION}

Se você estiver usando o Azure OpenAI com a ID do Microsoft Entra (autenticação sem chave), também deverá atribuir a função "Usuário dos Serviços Cognitivos" ou "Usuário de IA do Azure" no recurso do Azure OpenAI:

# Option 1: Assign Cognitive Services User role
az role assignment create \
    --role "Cognitive Services User" \
    --assignee $USER_ASSIGNED_CLIENT_ID \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<openai-resource-name>

# Option 2: Assign Azure AI User role
az role assignment create \
    --role "Azure AI User" \
    --assignee $USER_ASSIGNED_CLIENT_ID \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<openai-resource-name>

Substitua <subscription-id>, <resource-group>e <openai-resource-name> com seus valores reais.

Anotar a conta de serviço com a identidade da carga de trabalho (opcional)

1. Atualize a conta de serviço para incluir a anotação para a identidade da carga de trabalho usando o seguinte comando:

   kubectl annotate serviceaccount "${SERVICE_ACCOUNT_NAME}" \
       --namespace "${SERVICE_ACCOUNT_NAMESPACE}" \
       azure.workload.identity/client-id="${USER_ASSIGNED_CLIENT_ID}" \
       --overwrite
   

2. Verifique se a conta de serviço tem a anotação de identidade de carga de trabalho correta usando o seguinte comando:

   kubectl describe serviceaccount "${SERVICE_ACCOUNT_NAME}" --namespace "${SERVICE_ACCOUNT_NAMESPACE}"
   

Criar uma credencial de identidade federada (opcional)

1. Crie uma credencial de identidade federada entre a identidade gerenciada, o emissor da conta de serviço e o assunto usando o az identity federated-credential create comando.

   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.

2. Liste as credenciais de identidade federadas para confirmar a criação usando o az identity federated-credential list comando.

   az identity federated-credential list \
       --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
       --resource-group "${RESOURCE_GROUP}"
   

Conteúdo relacionado

• Instalar e usar a CLI de agente para AKS
• Implantar e configurar a ID de Carga de Trabalho do Microsoft Entra em um cluster do AKS
• Visão geral da Identificação de Carga de Trabalho do Microsoft Entra