Crie uma conta de serviço e configure a identidade da carga de trabalho para a CLI do agentic para o Azure Kubernetes Service (AKS) (prévia)

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

Pré-requisitos

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

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

• Defina a sua subscrição ativa do Azure usando o az account set comando.

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

• Precisas de permissões suficientes para criar e gerir contas de serviço Kubernetes, roles e vínculos de funções.

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

• Identidade de carga de trabalho ativada no seu cluster AKS.
• Precisa de permissões suficientes para criar e gerir identidades geridas pelo Azure e criar credenciais de identidade federadas.

Definir variáveis

Primeiro, defina as variáveis necessárias para o seu ambiente. Substitui os valores provisórios pelos detalhes reais do teu cluster e 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 (apenas se estiver a configurar 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 Kubernetes e atribuir permissões (obrigatórias)

Crie a conta de serviço

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

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

Criar permissões RBAC

Crie o Role e o RoleBinding necessários para a conta de serviço com acesso de leitura para resolução de problemas do aks-mcp. Aqui estão dois exemplos baseados nos seus requisitos de acesso:

Acesso de leitura a nível de cluster (recomendado para administradores de cluster)

1. Utilize este ClusterRoleBinding para conceder acesso apenas de leitura a todos os recursos do Kubernetes, exceto segredos, em todos os namespaces. Esta opção é recomendada para administradores ao nível do cluster ou engenheiros DevOps que precisam de investigar e resolver 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 sucesso 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 espaço de nomes (para cenários de acesso limitado)

1. Use RoleBindings para conceder acesso apenas de leitura a todos os recursos Kubernetes, exceto segredos em espaços de nomes específicos. Esta opção é adequada para equipas ou utilizadores que deveriam ter acesso limitado a espaços de nomes específicos em vez de todo o cluster. Repita este RoleBinding para cada namespace que necessite de 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 sucesso 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 Azure (opcional)

Os seguintes passos são opcionais , mas recomendados se quiser ativar a CLI agente para aceder aos recursos do Azure de forma segura usando a identidade da carga de trabalho.

Verificar o estado atual da carga de trabalho da identidade

Verifica se a identidade da carga de trabalho já está ativada no teu cluster 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 da carga de trabalho está ativada. Se null ou false, precisa de o ativar.

Ativar identidade de tarefa

Ativar a identidade de carga de trabalho no teu cluster AKS usando o comando az aks update com as flags --enable-workload-identity e --enable-oidc-issuer.

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 usando o az aks show comando e guarde-o numa 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 exemplo a seguir:

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

Criar uma identidade gerenciada atribuída pelo usuário

Crie uma identidade gerida atribuída pelo utilizador para acesso a recursos 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"
}

Obtenha o ID do cliente de identidade gerida

Obtenha o ID do cliente da identidade gerida usando o az identity show e guarde-o numa 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 o papel necessário à identidade gerida

Atribuir os papéis necessários à identidade gerida usando o az role assignment create comando.

O exemplo seguinte atribui o papel "Leitor" no âmbito de subscrição, que permite à CLI agente ler informação de recursos do Azure. Ajusta o papel e o âmbito conforme necessário para o teu caso de uso.

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

Se estiver a usar Azure OpenAI com Microsoft Entra ID (autenticação sem chave), deve também atribuir o papel "Utilizador de Serviços Cognitivos" ou "Utilizador Azure AI" no recurso 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> pelos seus valores reais.

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

1. Atualize a conta do serviço para incluir a anotação da 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 correta da identidade da carga de trabalho usando o seguinte comando:

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

Crie uma credencial de identidade federada (opcional)

1. 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.

   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 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.

2. Liste as credenciais de identidade federada 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 agentic para AKS
• Implementar e configurar o ID de Carga de Trabalho do Microsoft Entra num cluster AKS
• Visão geral do Microsoft Entra Workload ID