Een serviceaccount maken en workloadidentiteit configureren voor de agentische CLI voor Azure Kubernetes Service (AKS) (preview)

In dit artikel leest u hoe u het vereiste serviceaccount maakt en eventueel de workloadidentiteit configureert voor de agentische CLI voor Azure Kubernetes Service (AKS). Het maken van het serviceaccount is verplicht voor de implementatie van de clustermodus, terwijl het instellen van de workloadidentiteit optioneel is, maar wordt aanbevolen voor verbeterde beveiliging bij het openen van Azure-resources.

Vereiste voorwaarden

Vereisten voor het maken van serviceaccounts:

• Azure CLI versie 2.76 of hoger. Controleer uw versie met behulp van de az version opdracht. Als u Azure CLI wilt installeren of bijwerken, raadpleegt u Azure CLI installeren.

• Stel uw actieve Azure-abonnement in met behulp van de az account set opdracht.

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

• U hebt voldoende machtigingen nodig om Kubernetes-serviceaccounts, -rollen en -rolbindingen te maken en te beheren.

Vereisten voor configuratie van workload-identiteit:

• Workloadidentiteit ingeschakeld op uw AKS-cluster.
• U hebt voldoende machtigingen nodig om beheerde Azure-identiteiten te maken en te beheren en federatieve identiteitsreferenties te maken.

Variabelen definiëren

Stel eerst de vereiste variabelen in voor uw omgeving. Vervang de tijdelijke aanduidingen door de werkelijke cluster- en Azure-gegevens.

Vereiste variabelen voor het maken van een serviceaccount:

# 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

Aanvullende variabelen (alleen als u de workloadidentiteit configureert):

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

Een Kubernetes-serviceaccount maken en machtigingen toewijzen (vereist)

Het serviceaccount maken

Maak het serviceaccount in uw doelnaamruimte met behulp van de volgende opdracht:

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

RBAC-machtigingen maken

Maak de benodigde Role en RoleBinding voor de serviceaccount met leestoegang voor de probleemoplossing van aks-mcp. Hier volgen twee voorbeelden op basis van uw toegangsvereisten:

Leestoegang voor het hele cluster (aanbevolen voor clusterbeheerders)

1. Gebruik dit ClusterRoleBinding om alleen-lezentoegang te verlenen tot alle Kubernetes-resources, met uitzondering van geheimen in alle naamruimten. Deze optie wordt aanbevolen voor beheerders op clusterniveau of DevOps-technici die problemen in het hele cluster moeten onderzoeken en oplossen.

   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. Controleer of de resources succesvol zijn aangemaakt met behulp van de volgende opdrachten:

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

Leestoegang met naamruimtebereik (voor scenario's met beperkte toegang)

1. Gebruik RoleBindings om alleen-lezentoegang te verlenen aan alle Kubernetes-resources, behalve geheimen in specifieke naamruimten. Deze optie is geschikt voor teams of gebruikers die beperkte toegang moeten hebben tot specifieke naamruimten in plaats van het hele cluster. Herhaal deze RoleBinding voor elke naamruimte waarvoor toegang is vereist.

   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. Controleer of de resources succesvol zijn aangemaakt met behulp van de volgende opdrachten:

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

Workload-identiteit configureren voor toegang tot Azure-resources (optioneel)

De volgende stappen zijn optioneel , maar wordt aanbevolen als u de agentische CLI wilt inschakelen voor veilig toegang tot Azure-resources met behulp van workloadidentiteit.

Huidige status van workloadidentiteit controleren

Controleer of de workloadidentiteit al is ingeschakeld op uw AKS-cluster met behulp van de az aks show opdracht.

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

Als de uitvoer is true, is de workloadidentiteit ingeschakeld. Als null of false, moet u deze inschakelen.

Workloadidentiteit inschakelen

Schakel de workloadidentiteit in op uw AKS-cluster met behulp van de az aks update opdracht met de --enable-workload-identity en --enable-oidc-issuer vlaggen.

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

De URL van de OIDC-verlener ophalen

Haal de URL van de OIDC-verlener op met behulp van de az aks show opdracht en sla deze op in een omgevingsvariabele.

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

De omgevingsvariabele moet de URL van de verlener bevatten, vergelijkbaar met het volgende voorbeeld:

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

Maak een door de gebruiker toegewezen beheerde identiteit

Maak een door de gebruiker toegewezen beheerde identiteit voor toegang tot Azure-resources met behulp van de az identity create opdracht.

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

In het volgende uitvoervoorbeeld ziet u hoe een beheerde identiteit is gemaakt:

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

De client-id van de beheerde identiteit ophalen

Haal de client-id van de beheerde identiteit op met behulp van de az identity show id en sla deze op in een omgevingsvariabele.

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

De benodigde rol toewijzen aan beheerde identiteit

Wijs de benodigde rollen toe aan de beheerde identiteit met behulp van de az role assignment create opdracht.

In het volgende voorbeeld wordt de rol 'Reader' toegewezen op abonnementsniveau, waarmee de Azure CLI Azure-broninformatie kan lezen. Pas de rol en het bereik zo nodig aan voor uw use-case.

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

Als u Azure OpenAI gebruikt met Microsoft Entra ID (sleutelloze verificatie), moet u ook de rol Cognitive Services-gebruiker of Azure AI-gebruiker toewijzen aan de Azure OpenAI-resource:

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

Vervang , <subscription-id>en <resource-group> door <openai-resource-name>uw werkelijke waarden.

Annoteren van het serviceaccount met de workloadidentiteit (optioneel)

1. Werk het serviceaccount bij met de annotatie voor workloadidentiteit met behulp van de volgende opdracht:

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

2. Controleer of het serviceaccount de juiste annotatie van de workloadidentiteit heeft door de volgende opdracht uit te voeren:

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

Een federatieve identiteitsreferentie maken (optioneel)

1. Maak een federatieve identiteitsreferentie tussen de beheerde identiteit, de verlener van het serviceaccount en het onderwerp met behulp van de az identity federated-credential create opdracht.

   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
   

   Opmerking

   Het duurt enkele seconden voordat een federatieve identiteitsreferentie zich heeft verspreid nadat deze is toegevoegd. Als er direct na het toevoegen van de federatieve identiteitsreferentie een tokenaanvraag wordt gedaan, mislukt de aanvraag mogelijk totdat de cache wordt vernieuwd. U kunt dit probleem voorkomen door een kleine vertraging toe te voegen nadat u de federatieve identiteitsreferentie hebt toegevoegd.

2. Geef de federatieve identiteitsreferenties weer om de creatie te bevestigen met behulp van de az identity federated-credential list opdracht.

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

Verwante inhoud

• De agentische CLI voor AKS installeren en gebruiken
• Microsoft Entra Workload-id implementeren en configureren op een AKS-cluster
• Overzicht van de Microsoft Entra Workload ID