Creare un account del servizio e configurare l'identità del carico di lavoro per l'interfaccia della riga di comando agentica per il servizio Azure Kubernetes (anteprima)

Questo articolo illustra come creare l'account del servizio necessario e facoltativamente configurare l'identità del carico di lavoro per l'interfaccia a riga di comando agentica di Azure Kubernetes Service (AKS). La creazione dell'account del servizio è obbligatoria per la distribuzione in modalità cluster, mentre la configurazione dell'identità del carico di lavoro è facoltativa, ma consigliata per la sicurezza avanzata durante l'accesso alle risorse di Azure.

Prerequisiti

Prerequisiti per la creazione dell'account del servizio:

  • Interfaccia della riga di comando di Azure versione 2.76 o successiva. Verificare la versione usando il comando az version. Per installare o aggiornare, vedere Installare l'interfaccia della riga di comando di Azure.

  • Imposta la sottoscrizione di Azure attiva usando il comando az account set.

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

  • Sono necessarie autorizzazioni sufficienti per creare e gestire account, ruoli e associazioni di ruoli del servizio Kubernetes.

Prerequisiti di configurazione dell'identità del carico di lavoro:

Definire le variabili

Prima di tutto, configurare le variabili necessarie per l'ambiente. Sostituire i valori segnaposto con i dettagli di Azure e del cluster effettivi.

Variabili obbligatorie per la creazione dell'account del servizio:

# 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

Variabili aggiuntive (solo se si configura l'identità del carico di lavoro):

# 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)"

Creare un account del servizio Kubernetes e assegnare le autorizzazioni (obbligatorio)

Importante

L'account del servizio è necessario per consentire all'interfaccia della riga di comando agentica di eseguire l'autenticazione con il cluster del servizio Azure Kubernetes in modalità cluster.

Creare l'account di servizio

Creare l'account di servizio nel namespace di destinazione usando il comando seguente:

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

Creare le autorizzazioni del controllo degli accessi in base al ruolo

Creare il ruolo e l'associazione di ruolo necessari per l'account di servizio con accesso in lettura per la risoluzione dei problemi di aks-mcp. Di seguito sono riportati due esempi in base ai requisiti di accesso:

  1. Utilizzare questo elemento ClusterRoleBinding per concedere l'accesso in sola lettura a tutte le risorse Kubernetes, ad eccezione dei segreti in tutti gli spazi dei nomi. Questa opzione è consigliata per gli amministratori a livello di cluster o i tecnici DevOps che devono analizzare e risolvere i problemi nell'intero 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. Verificare che le risorse siano state create correttamente usando i comandi seguenti:

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

Accesso in lettura con ambito spazio dei nomi (per scenari con accesso limitato)

  1. Usare RoleBindings per concedere l'accesso in sola lettura a tutte le risorse Kubernetes, eccetto i segreti, soltanto nei namespace specifici. Questa opzione è adatta per i team o gli utenti che devono avere accesso limitato a spazi dei nomi specifici anziché all'intero cluster. Ripetere questo RoleBinding per ogni namespace che richiede l'accesso.

    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. Verificare che le risorse siano state create correttamente usando i comandi seguenti:

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

Configurare l'identità del carico di lavoro per l'accesso alle risorse di Azure (facoltativo)

La procedura seguente è facoltativa, ma consigliata se si vuole abilitare l'interfaccia della riga di comando agente per accedere in modo sicuro alle risorse di Azure usando l'identità del carico di lavoro.

Controllare lo stato corrente dell'identità dei carichi di lavoro

Controllare se il workload identity è già abilitato sul cluster AKS utilizzando il comando az aks show.

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

Se l'output è true, l'identità del carico di lavoro è abilitata. Se null o false, è necessario abilitarlo.

Abilitare l'identità del carico di lavoro

Abilitare l'identità del workload nel cluster AKS usando il comando az aks update con i flag --enable-workload-identity e --enable-oidc-issuer.

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

Recuperare l'URL dell'autorità di certificazione OIDC

Ottenere l'URL dell'autorità emittente OIDC usando il az aks show comando e salvarlo in una variabile di ambiente.

export AKS_OIDC_ISSUER="$(az aks show --name "${CLUSTER_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --query "oidcIssuerProfile.issuerUrl" \
    --output tsv)"

La variabile di ambiente deve contenere l'URL dell'autorità di certificazione, in modo simile all'esempio seguente:

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

Creare un'identità gestita assegnata dall'utente

Creare un'identità gestita assegnata dall'utente per l'accesso alle risorse di Azure usando il az identity create comando .

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

L'esempio di output seguente mostra la corretta creazione di un'identità gestita:

{
  "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"
}

Ottenere l'ID client dell'identità gestita

Ottenere l'ID client dell'identità gestita usando az identity show e salvarlo in una variabile di ambiente.

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

Assegnare il ruolo necessario all'identità gestita

Assegnare i ruoli necessari all'identità gestita usando il az role assignment create comando .

L'esempio seguente assegna il ruolo "Lettore" nell'ambito della sottoscrizione, per consentire all'interfaccia della riga di comando agentica di leggere le informazioni sulle risorse di Azure. Modificare il ruolo e l'ambito in base alle esigenze per il caso d'uso.

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

Se si usa Azure OpenAI con Microsoft Entra ID (autenticazione senza chiave), è necessario assegnare anche il ruolo "Utente servizi cognitivi" o "Utente di Intelligenza artificiale di Azure" nella risorsa OpenAI di Azure:

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

Sostituire <subscription-id>, <resource-group>e <openai-resource-name> con i valori effettivi.

Annotare l'account del servizio con l'identità del carico di lavoro (facoltativo)

  1. Aggiornare l'account del servizio per includere l'annotazione per l'identità del carico di lavoro usando il comando seguente:

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

  2. Verificare che l'account del servizio abbia l'annotazione corretta dell'identità del carico di lavoro usando il comando seguente:

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

Creare credenziali di identità federate (facoltativo)

  1. Creare una credenziale di identità federata tra l'identità gestita, l'autorità emittente dell'account del servizio e il soggetto usando il comando az identity federated-credential create.

    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

    Annotazioni

    La propagazione delle credenziali dell'identità federata richiede alcuni secondi dopo l'aggiunta. Se una richiesta di token viene effettuata immediatamente dopo l'aggiunta della credenziale dell'identità federata, la richiesta potrebbe non riuscire finché non viene aggiornata la cache. Per evitare questo problema, è possibile aggiungere un lieve ritardo dopo l'aggiunta delle credenziali di identità federate.

  2. Elencare le credenziali dell'identità federata per confermare la creazione usando il az identity federated-credential list comando .

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

Contenuti correlati

  • Last updated on