Erstellen eines Dienstkontos und Konfigurieren der Workload-Identität für die agentic CLI für Azure Kubernetes Service (AKS) (Vorschau)

In diesem Artikel erfahren Sie, wie Sie das erforderliche Dienstkonto erstellen und optional die Workloadidentität für die agentische CLI für Azure Kubernetes Service (AKS) konfigurieren. Die Erstellung des Dienstkontos ist für die Bereitstellung im Clustermodus obligatorisch , während die Workload-Identitätseinrichtung optional ist, aber für erhöhte Sicherheit beim Zugriff auf Azure-Ressourcen empfohlen wird.

Voraussetzungen

Voraussetzungen für die Erstellung von Dienstkonten:

• Azure CLI, Version 2.76 oder höher. Überprüfen Sie Ihre Version mit dem Befehl az version. Informationen zum Installieren oder Aktualisieren finden Sie unter Installieren der Azure CLI.

• Legen Sie Ihr aktives Azure-Abonnement mithilfe des az account set Befehls fest.

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

• Sie benötigen ausreichende Berechtigungen zum Erstellen und Verwalten von Kubernetes-Dienstkonten, Rollen und Rollenbindungen.

Voraussetzungen für die Konfiguration der Workload-Identität:

• Workload-Identität auf Ihrem AKS-Cluster aktiviert.
• Sie benötigen ausreichende Berechtigungen, um von Azure verwaltete Identitäten zu erstellen und zu verwalten und Verbundidentitätsanmeldeinformationen zu erstellen.

Definieren von Variablen

Richten Sie zunächst die erforderlichen Variablen für Ihre Umgebung ein. Ersetzen Sie die Platzhalterwerte durch Ihre tatsächlichen Cluster- und Azure-Details.

Erforderliche Variablen für die Erstellung von Dienstkonten:

# 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

Zusätzliche Variablen (nur bei der Konfiguration der Workloadidentität):

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

Erstellen eines Kubernetes-Dienstkontos und Zuweisen von Berechtigungen (erforderlich)

Erstellen des Dienstkontos

Erstellen Sie das Dienstkonto im Zielnamespace mit dem folgenden Befehl:

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

Erstellen von RBAC-Berechtigungen

Erstellen Sie wie notwendig Rolle und RoleBinding für das Dienstkonto mit Lesezugriff für die aks-mcp-Problembehandlung. Hier sind zwei Beispiele, die auf Ihren Zugriffsanforderungen basieren:

Clusterweiter Lesezugriff (empfohlen für Clusteradministratoren)

1. Verwenden Sie diese ClusterRoleBinding, um schreibgeschützten Zugriff auf alle Kubernetes-Ressourcen außer Secrets in allen Namespaces zu gewähren. Diese Option wird für Administratoren auf Clusterebene oder DevOps-Techniker empfohlen, die Probleme im gesamten Cluster untersuchen und beheben müssen.

   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. Überprüfen Sie, ob die Ressourcen erfolgreich mithilfe der folgenden Befehle erstellt wurden:

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

Namespace-übergreifender Lesezugriff (für Szenarien mit begrenztem Zugriff)

1. Verwenden Sie RoleBindings, um schreibgeschützten Zugriff auf alle Kubernetes-Ressourcen zu gewähren, mit Ausnahme von geheimen Schlüsseln nur in bestimmten Namespaces. Diese Option eignet sich für Teams oder Benutzer, die nur eingeschränkten Zugriff auf bestimmte Namespaces und nicht für den gesamten Cluster haben sollten. Wiederholen Sie dieses RoleBinding für jeden Namespace, der Zugriff erfordert.

   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. Überprüfen Sie, ob die Ressourcen erfolgreich mithilfe der folgenden Befehle erstellt wurden:

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

Konfigurieren der Workloadidentität für den Azure-Ressourcenzugriff (optional)

Die folgenden Schritte sind optional , aber empfohlen, wenn Sie die agentische CLI für den sicheren Zugriff auf Azure-Ressourcen mithilfe der Workload-Identität aktivieren möchten.

Überprüfen des aktuellen Workloadidentitätsstatus

Überprüfen Sie mithilfe des az aks show Befehls, ob die Workload-Identität bereits auf Ihrem AKS-Cluster aktiviert ist.

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

Wenn die Ausgabe lautet true, ist die Workload-Identität aktiviert. Wenn null oder false der Fall ist, müssen Sie es aktivieren.

Workload-Identität aktivieren

Aktivieren Sie die Workloadidentität auf Ihrem AKS-Cluster mithilfe des az aks update-Befehls und der --enable-workload-identity- und --enable-oidc-issuer-Kennzeichnungen.

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

Abrufen der OIDC-Zertifikataussteller-URL

Rufen Sie die OIDC-Aussteller-URL mithilfe des az aks show Befehls ab, und speichern Sie sie in einer Umgebungsvariable.

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

Die Umgebungsvariable sollte die URL des Zertifikatausstellers enthalten, ähnlich wie im folgenden Beispiel:

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

Erstellen einer benutzerseitig zugewiesenen verwalteten Identität

Erstellen Sie mithilfe des Befehls eine vom Benutzer zugewiesene verwaltete Identität für den az identity create Azure-Ressourcenzugriff.

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

Das folgende Ausgabebeispiel zeigt die erfolgreiche Erstellung einer verwalteten Identität:

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

Holen Sie sich die Client-ID für verwaltete Identitäten

Rufen Sie die Client-ID der verwalteten Identität mithilfe von az identity show ab, und speichern Sie sie in einer Umgebungsvariable.

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

Notwendige Rolle der verwalteten Identität zuweisen

Weisen Sie der verwalteten Identität mithilfe des az role assignment create Befehls die erforderlichen Rollen zu.

Im folgenden Beispiel wird die Rolle "Reader" im Abonnementbereich zugewiesen, wodurch die agentische CLI Azure-Ressourceninformationen lesen kann. Passen Sie die Rolle und den Umfang nach Bedarf für Ihren Anwendungsfall an.

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

Wenn Sie Azure OpenAI mit Microsoft Entra ID (schlüssellose Authentifizierung) verwenden, müssen Sie auch die Rolle "Cognitive Services User" oder "Azure AI User" in der Azure OpenAI-Ressource zuweisen:

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

Ersetzen Sie <subscription-id>, <resource-group> und <openai-resource-name> durch Ihre tatsächlichen Werte.

Annotieren des Dienstkontos mit Workload-Identität (optional)

1. Aktualisieren Sie das Dienstkonto so, dass es die Anmerkung für die Workload-Identität mit dem folgenden Befehl enthält:

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

2. Stellen Sie sicher, dass das Dienstkonto über die richtige Workloadidentitätsanmerkung verfügt, indem Sie den folgenden Befehl verwenden:

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

Erstellen Sie eine verbundene Anmeldeinformation (optional)

1. Erstellen Sie mithilfe des az identity federated-credential create-Befehls federierte Identitätsnachweise zwischen der verwalteten Identität, dem Herausgeber des Dienstkontos und dem Subjekt.

   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
   

   Hinweis

   Es dauert einige Sekunden, bis die Anmeldeinformationen für die Verbundidentität nach dem Hinzufügen weitergegeben werden. Wenn eine Tokenanforderung unmittelbar nach dem Hinzufügen der Anmeldeinformationen für die Verbundidentität erfolgt, schlägt die Anforderung möglicherweise fehl, bis der Cache aktualisiert wird. Um dieses Problem zu vermeiden, können Sie eine kleine Verzögerung nach dem Hinzufügen der Verbundidentitäts-Anmeldeinformationen hinzufügen.

2. Listen Sie die Verbundidentitätsdaten auf, um die Erstellung mithilfe des az identity federated-credential list-Befehls zu bestätigen.

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

Verwandte Inhalte

• Installieren und Verwenden der agentischen CLI für AKS
• Bereitstellen und Konfigurieren der Microsoft Entra Workload-ID in einem AKS-Cluster
• Übersicht über die Microsoft Entra Workload-ID