Freigeben über

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. ein Azure Load Balancer oder eine Azure Container Registry (ACR), dynamisch erstellt und verwaltet werden können.

Für optimale Sicherheit und Benutzerfreundlichkeit empfiehlt Microsoft, verwaltete Identitäten anstelle von Dienstprinzipalen zu verwenden, um den Zugriff von einem AKS-Cluster auf andere Ressourcen in Azure zu autorisieren. Eine verwaltete Identität ist ein spezieller Dienstprinzipaltyp, der zum Abrufen von Microsoft Entra-Anmeldeinformationen verwendet werden kann, ohne dass Anmeldeinformationen verwaltet und gesichert werden müssen. Weitere Informationen zur Verwendung einer verwalteten Identität mit Ihrem Cluster finden Sie unter Verwenden verwalteter Identitäten in AKS.

Dieser Artikel veranschaulicht 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 Abonnementadministratoren und -administratorinnen bitten, Ihnen die erforderlichen Berechtigungen zuzuweisen oder vorab einen Dienstprinzipal für die Verwendung mit Ihrem AKS-Cluster 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.

Erstellen eines Dienstprinzipals

Erstellen Sie einen Dienstprinzipal, bevor Sie Ihren Cluster erstellen.

  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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

  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> \
    --generate-ssh-keys

    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 z. B. Ihren AKS-Cluster in einem vorhandenen virtuellen Azure-Netzwerk-Subnetz bereitstellen möchten, eine Verbindung mit Azure Container Registry (ACR) herstellen oder Zugriffsschlüssel oder geheime Schlüssel in einem Schlüsseltresor aus Ihrem Cluster bereitstellen möchten, müssen Sie den Zugriff auf diese Ressourcen an den Dienstprinzipal delegieren. Weisen Sie dem Dienstprinzipal eine rollebasierte Azure-Zugriffssteuerungsrolle (Azure RBAC) zu, um den Zugriff zu delegieren.

Wichtig

Es kann bis zu 60 Minuten dauern, bis die einem Dienstprinzipal in einem Cluster erteilten Berechtigungen verteilt werden.

  • Erstellen Sie eine Rollenzuweisung anhand des Befehls az role assignment create. Geben Sie den Wert der AppID des Dienstprinzipals für den Parameter appId an. Geben Sie den Bereich für die Rollenzuweisung an, z. B. eine Ressourcengruppe oder eine virtuelle Netzwerkressource. Die Rollenzuweisung bestimmt, welche Berechtigungen der Dienstprinzipal für die Ressource und in welchem Bereich hat.

    Um beispielsweise dem Dienstprinzipal Berechtigungen für den Zugriff auf geheime Schlüssel in einem Schlüsseltresor zuzuweisen, können Sie den folgenden Befehl verwenden:

    az role assignment create \
    --assignee <appId> \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" \
    --role "Key Vault Secrets User"

    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.

In den folgenden Abschnitten werden allgemeine Delegierungen, die Sie möglicherweise einem Dienstprinzipal 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 \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query servicePrincipalProfile.clientId \
  --output tsv)

Problembehandlung

Die Azure CLI speichert die Anmeldeinformationen des Dienstprinzipals für AKS-Cluster zwischen. Wenn diese Anmeldeinformationen ablaufen, können während der Bereitstellung des AKS-Clusters Fehler auftreten. 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" \
    --output 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).