Verwenden eines Dienstprinzipals mit Azure Kubernetes Service (AKS)

  • Artikel

Ein AKS-Cluster erfordert entweder einen Microsoft Entra-Dienstprinzipal oder eine verwaltete Identität, damit andere Azure-Ressourcen, z. B. eine Azure Load Balancer oder eine Azure Container Registry (ACR), dynamisch erstellt und verwaltet werden können.

Hinweis

Die Verwendung von verwalteten Identitäten zur Authentifizierung bei anderen Ressourcen in Azure wird empfohlen. Diese werden als Standardauthentifizierungsmethode für Ihren AKS-Cluster eingesetzt. Weitere Informationen zur Verwendung einer verwalteten Identität mit Ihrem Cluster finden Sie unter Verwenden verwalteter Identitäten in Azure Kubernetes Service.

Dieser Artikel veranschaulicht Ihnen das Erstellen und Verwenden eines Dienstprinzipals für Ihre AKS-Cluster.

Voraussetzungen

Um einen Microsoft Entra-Dienstprinzipal zu erstellen, müssen Sie über die Berechtigung verfügen, eine Anwendung bei Ihrem Microsoft Entra-Mandanten zu registrieren und die Anwendung einer Rolle in Ihrem Abonnement zuzuweisen. Sollten Sie nicht über die erforderlichen Berechtigungen verfügen, müssen Sie ggf. Ihre Microsoft Entra ID- oder Abonnementadministrator*innen bitten, Ihnen die erforderlichen Berechtigungen zuzuweisen oder vorab einen Dienstprinzipal für die Verwendung mit Ihrem AKS-Cluster für Sie zu erstellen.

Wenn Sie einen Dienstprinzipal aus einem anderen Microsoft Entra-Mandanten verwenden, müssen weitere Überlegungen zu den nach der Bereitstellung des Clusters verfügbaren Berechtigungen angestellt werden. Möglicherweise haben Sie nicht die entsprechenden Berechtigungen zum Lesen und Schreiben von Verzeichnisinformationen. Weitere Informationen finden Sie unter Welche Standardbenutzerberechtigungen gibt es in Microsoft Entra ID?.

Voraussetzungen

  • Wenn Sie Azure CLI verwenden, benötigen Sie Azure CLI Version 2.0.59 oder höher. Führen Sie az --version aus, um die Version zu ermitteln. Informationen zum Durchführen einer Installation oder eines Upgrades finden Sie bei Bedarf unter Installieren der Azure CLI.
  • Wenn Sie Azure PowerShell verwenden, benötigen Sie Azure PowerShell Version 5.0.0 oder höher. Führen Sie Get-InstalledModule -Name Az aus, um die Version zu ermitteln. Wenn Sie eine Installation oder eine Aktualisierung vornehmen müssen, beachten Sie den Abschnitt Installieren des Azure Az PowerShell-Moduls.

Manuelles Erstellen eines Dienstprinzipals

  1. Erstellen Sie einen Dienstprinzipal mit dem Befehl az ad sp create-for-rbac.

    az ad sp create-for-rbac --name myAKSClusterServicePrincipal

    Ihre Ausgabe sollte der folgenden Beispielausgabe ähneln:

    {
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

  2. Kopieren Sie die Werte für appId und password aus der Ausgabe. Diese verwenden Sie beim Erstellen eines AKS-Clusters im nächsten Abschnitt.

Angeben eines Dienstprinzipals für einen AKS-Cluster

  • Verwenden Sie einen vorhandenen Dienstprinzipal für einen neuen AKS-Cluster mithilfe des Befehls az aks create, und verwenden Sie die Parameter --service-principal und --client-secret, um die appId und password aus der Ausgabe anzugeben, die Sie im vorherigen Abschnitt erhalten haben.

    az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>

    Hinweis

    Wenn Sie einen bestehenden Dienstprinzipal mit benutzerdefiniertem Geheimnis verwenden, stellen Sie sicher, dass das Geheimnis nicht länger als 190 Bytes ist.

Delegieren des Zugriffs auf andere Azure-Ressourcen

Sie können den Dienstprinzipal für den AKS-Cluster verwenden, um auf andere Ressourcen zuzugreifen. Wenn Sie beispielsweise Ihren AKS-Cluster in ein bestehendes Subnetz eines virtuellen Azure-Netzwerks einbinden oder eine Verbindung mit Azure Container Registry (ACR) herstellen möchten, müssen Sie den Zugriff auf diese Ressourcen an den Dienstprinzipal delegieren. Es kann bis zu 60 Minuten dauern, bis die Berechtigungszuweisungen für einen Cluster mithilfe einer systemseitig zugewiesenen verwalteten Identitäten aufgefüllt werden.

  • Erstellen Sie eine Rollenzuweisung anhand des Befehls az role assignment create. Weisen Sie appId einem bestimmten Bereich zu, beispielsweise einer Ressourcengruppe oder einer virtuellen Netzwerkressource. Die Rolle definiert, welche Berechtigungen der Dienstprinzipal für die Ressource hat.

    Hinweis

    Bei dem --scope für eine Ressource muss es sich um eine vollständige Ressourcen-ID handeln, z. B. /subscriptions/<guid>/resourceGroups/myResourceGroup oder /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet.

    az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

In den folgenden Abschnitten werden allgemeine Delegierungen, die Sie möglicherweise zuweisen müssen, ausführlicher erläutert.

Azure Container Registry

Wenn Sie Azure Container Registry (ACR) als Speicher für Containerimages verwenden, müssen Sie dem Dienstprinzipal für Ihren AKS-Cluster Berechtigungen zum Lesen und Pullen von Images erteilen. Es wird empfohlen, den Befehl az aks create oder az aks update zur Integration in eine Registrierung und zur Zuweisung der entsprechenden Rolle für den Dienstprinzipal zu verwenden. Eine ausführliche Anleitung finden Sie unter Authentifizieren per Azure Container Registry über Azure Kubernetes Service.

Netzwerk

Möglicherweise verwenden Sie erweiterte Netzwerke, in denen sich das virtuelle Netzwerk und das Subnetz oder öffentliche IP-Adressen in einer anderen Ressourcengruppe befinden. Weisen Sie die integrierte Rolle Netzwerkmitwirkender für das Subnetz im virtuellen Netzwerk zu. Alternativ können Sie eine benutzerdefinierte Rolle mit Zugriffsberechtigungen für die Netzwerkressourcen in dieser Ressourcengruppe erstellen. Weitere Informationen finden Sie unter AKS-Dienstberechtigungen.

Storage

Wenn Sie auf vorhandene Datenträgerressourcen in einer anderen Ressourcengruppe zugreifen müssen, weisen Sie eine der folgenden Gruppen von Rollenberechtigungen zu:

Azure Container Instances

Wenn Sie Virtual Kubelet für die Integration in AKS verwenden und Azure Container Instances (ACI) in einer Ressourcengruppe außerhalb des AKS-Clusters ausführen, muss dem Dienstprinzipal des AKS-Clusters in der ACI-Ressourcengruppe die Berechtigung Mitwirkender gewährt werden.

Weitere Überlegungen

Berücksichtigen Sie beim Verwenden von AKS und einem Microsoft Entra-Dienstprinzipal Folgendes:

  • Der Dienstprinzipal für Kubernetes ist Teil der Clusterkonfiguration, aber verwenden Sie diese Identität nicht zum Bereitstellen des Clusters.
  • Standardmäßig sind die Anmeldeinformationen des Dienstprinzipals ein Jahr gültig. Sie können jederzeit die Anmeldeinformationen des Dienstprinzipals aktualisieren oder rotieren.
  • Jeder Dienstprinzipal ist einer Microsoft Entra-Anwendung zugeordnet. Sie können den Dienstprinzipal für einen Kubernetes-Cluster einem beliebigen gültigen Microsoft Entra-Anwendungsnamen zuordnen (z. B. https://www.contoso.org/example). Bei der URL für die Anwendung muss es sich nicht um einen realen Endpunkt handeln.
  • Geben Sie als Client-ID des Dienstprinzipals den appId-Wert an.
  • Auf den Agent-Knoten-VMs im Kubernetes-Cluster werden die Anmeldeinformationen des Dienstprinzipals in der Datei /etc/kubernetes/azure.json gespeichert.
  • Beim Löschen eines AKS-Clusters, der mit dem Befehl az aks create erstellt wurde, wird der automatisch erstellte Dienstprinzipal nicht gelöscht.

    • Um den Dienstprinzipal zu löschen, fragen Sie ServicePrincipalProfile.ClientId für Ihre Cluster ab, und löschen Sie den Dienstprinzipal mithilfe des Befehls az ad sp delete. Ersetzen Sie die Werte für den Parameter -g für den Ressourcengruppennamen und den Parameter -n für den Clusternamen:

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)

Problembehandlung

Die Azure CLI speichert die Anmeldeinformationen des Dienstprinzipals für AKS-Cluster zwischen. Wenn diese Anmeldeinformationen ablaufen, treten während der Bereitstellung des AKS-Clusters Fehler auf. Wenn Sie den Befehl az aks create ausführen und eine Fehlermeldung ähnlich der folgenden erhalten, kann dies auf ein Problem mit den zwischengespeicherten Anmeldeinformationen für den Dienstprinzipal hinweisen:

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

Sie können das Ablaufdatum Ihrer Dienstprinzipalanmeldeinformationen mithilfe des az ad app credential list-Befehls mit der "[].endDateTime"-Abfrage überprüfen.

az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv

Die Standardablaufzeit für die Anmeldeinformationen des Dienstprinzipals beträgt ein Jahr. Wenn Ihre Anmeldeinformationen älter als ein Jahr sind, können Sie die vorhandenen Anmeldeinformationen zurücksetzen oder einen neuen Dienstprinzipal erstellen.

Allgemeine Azure CLI-Problembehandlung

Die Azure CLI kann in mehreren Shellumgebungen ausgeführt werden, jedoch mit geringfügigen Formatvariationen. Wenn bei Azure CLI-Befehlen unerwartete Ergebnisse auftreten, lesen Sie diese Tipps für die erfolgreiche Verwendung der Azure CLI.

Nächste Schritte

Weitere Informationen zu Microsoft Entra-Dienstprinzipalen finden Sie unter Anwendungs- und Dienstprinzipalobjekte.

Informationen zum Aktualisieren der Anmeldeinformationen finden Sie unter Aktualisieren oder Rotieren der Anmeldeinformationen für einen Dienstprinzipal in Azure Kubernetes Service (AKS).