Aktivieren der verwalteten Azure-Identitätsauthentifizierung für Kubernetes-Cluster mit kubelogin

  • Artikel

Die von AKS verwaltete Microsoft Entra-Integration vereinfacht den Integrationsprozess für Microsoft Entra. Zuvor mussten Sie eine Client- und Server-App erstellen, und der Microsoft Entra-Mandant musste die Berechtigungen Verzeichnisleseberechtigte zuweisen. Jetzt verwaltet der AKS-Ressourcenanbieter die Client- und Server-App.

Clusteradministratoren können die rollenbasierte Zugriffssteuerung von Kubernetes (Kubernetes RBAC) auf Grundlage einer Benutzeridentität oder Verzeichnisgruppenmitgliedschaft konfigurieren. Die Microsoft Entra ID-Authentifizierung wird für AKS-Cluster mit OpenID Connect bereitgestellt. OpenID Connect ist eine Identitätsebene, die auf dem OAuth 2.0-Protokoll aufbaut. Weitere Informationen zu OpenID Connect finden Sie in der OpenID Connect-Dokumentation.

Erfahren Sie mehr über den Microsoft Entra-Integrationsfluss in der Microsoft Entra-Dokumentation.

Dieser Artikel enthält Details zum Aktivieren und Verwenden von verwalteten Identitäten für Azure-Ressourcen mit Ihrem AKS-Cluster.

Begrenzungen

Im Folgenden sind Einschränkungen für die Integration der verwalteten Azure Ideitätsauthentifizierung auf AKS integrieren aufgeführt.

  • Die Integration kann nach dem Hinzufügen nicht deaktiviert werden.
  • Herabstufungen von einem integrierten Cluster auf Microsoft Entra ID Legacy-Cluster werden nicht unterstützt.
  • Cluster ohne Kubernetes RBAC-Unterstützung können die Integration nicht hinzufügen.

Voraussetzungen

Die folgenden Anforderungen müssen erfüllt werden, um das AKS-Add-on für verwaltete Identität ordnungsgemäß zu installieren.

  • Sie haben Azure CLI-Version 2.29.0 oder höher installiert und konfiguriert. 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.
  • Sie benötigen kubectl mit einer Mindestversion von 1.18.1 oder mit kubelogin. Bei der Azure CLI und dem Azure PowerShell-Modul werden diese beiden Befehle eingebunden und automatisch verwaltet. Das bedeutet, dass sie standardmäßig aktualisiert werden und die Ausführung von az aks install-cli weder erforderlich ist noch empfohlen wird. Wenn Sie eine automatisierte Pipeline verwenden, müssen Sie sich um Upgrades auf die richtige oder neueste Version kümmern. Der Unterschied zwischen den Nebenversionen von Kubernetes und kubectl sollte höchstens eine Version betragen. Andernfalls treten Authentifizierungsprobleme mit der falschen Version auf.
  • Wenn Sie helm verwenden, benötigen Sie eine Mindestversion von helm 3.3.
  • Diese Konfiguration erfordert, dass Sie über eine Microsoft Entra-Gruppe für Ihr Cluster verfügen. Diese Gruppe wird als Administratorgruppe für den Cluster registriert, um Administratorberechtigungen zu erteilen. Wenn Sie nicht über eine Microsoft Entra-Gruppe verfügen, können Sie eine mit dem Befehl az ad group create erstellen.

Hinweis

Integrierte Microsoft Entra-Cluster, die eine neuere Kubernetes-Version als Version 1.24 verwenden, verwenden automatisch das kubelogin-Format. Ab Kubernetes Version 1.24 lautet das Standardformat der clusterUser-Anmeldeinformationen für Microsoft Entra ID-Cluster exec. Dafür ist eine kubelogin-Binärdatei im Ausführungspfad (PATH) erforderlich. Es gibt keine Verhaltensänderung für Nicht-Microsoft Entra-Cluster oder Microsoft Entra ID-Cluster mit einer Version, die älter als 1.24 ist. Vorhandene heruntergeladene kubeconfig-Dateien funktionieren weiterhin. Beim Abrufen der clusterUser-Anmeldeinformationen wird der optionale Abfrageparameter format eingebunden, um die Standardverhaltensänderung zu überschreiben. Sie können für das Format explizit azure angeben, wenn Sie das alte kubeconfig-Format beibehalten müssen.

Aktivieren der Integration in Ihrem AKS-Cluster

Neuen Cluster erstellen

  1. Erstellen Sie mithilfe des Befehls az group create eine Azure-Ressourcengruppe.

    az group create --name myResourceGroup --location centralus

  2. Erstellen Sie mit dem Befehl az aks create ein AKS-Cluster und aktivieren Sie den Verwaltungszugriff für Ihre Microsoft Entra-Gruppe.

    az aks create -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]

    Eine erfolgreiche Erstellung eines von AKS verwalteten Microsoft Entra-Clusters wird im Antworttext mit dem folgenden Abschnitt angegeben:

    "AADProfile": {
    "adminGroupObjectIds": [
    "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
}

Verwenden eines vorhandenen Clusters

Sie können die von AKS verwaltete Microsoft Entra-Integration in Ihrem vorhandenen Kubernetes-Cluster mit aktivierter RBAC mit dem Befehl az aks update aktivieren. Stellen Sie sicher, dass Ihre Administratorengruppe Zugriff auf Ihren Cluster behält.

az aks update -g MyResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id-1>,<id-2> [--aad-tenant-id <id>]

Eine erfolgreiche Aktivierung eines von AKS verwalteten Microsoft Entra ID-Clusters wird im Antworttext mit dem folgenden Abschnitt angegeben:

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

Migrieren eines Legacy-Clusters in die Integration

Wenn Ihr Cluster Microsoft Entra Legacy-Integration verwendet, können Sie mithilfe des az aks update-Befehls auf die AKS-verwaltete Microsoft Entra-Integration aktualisieren.

Warnung

Bei Clustern im Free-Tarif kann während des Upgrades eine Ausfallzeit beim API-Server auftreten. Es wird empfohlen, Upgrades außerhalb der Geschäftszeiten durchzuführen. Nach dem Upgrade ändert sich der kubeconfig-Inhalt. Sie müssen az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> ausführen, um die neuen Anmeldeinformationen in die kubeconfig-Datei einzubinden.

az aks update -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]

Eine erfolgreiche Migration eines von AKS verwalteten Microsoft Entra ID-Clusters wird im Antworttext mit dem folgenden Abschnitt angegeben:

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

Zugreifen auf Ihren aktivierten Cluster

  1. Rufen Sie die Benutzeranmeldeinformationen für den Zugriff auf den Cluster mit dem Befehl az aks get-credentials ab.

    az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

  2. Befolgen Sie die Anweisungen zum Anmelden.

  3. Legen Sie kubelogin so fest, dass die Azure CLI verwendet wird.

    kubelogin convert-kubeconfig -l azurecli

  4. Zeigen Sie die Knoten im Cluster mit dem kubectl get nodes-Befehl an.

    kubectl get nodes

Nicht interaktive Anmeldung per kubelogin

Es gibt einige nicht interaktive Szenarien, die kubectl nicht unterstützen. Verwenden Sie in diesen Fällen kubelogin, um eine Verbindung mit dem Cluster mit einer nicht interaktiven Dienstprinzipalanmeldeinformation herzustellen, damit Continuous Integration-Pipelines ausgeführt werden.

Hinweis

Integrierte Microsoft Entra-Cluster, die eine neuere Kubernetes-Version als Version 1.24 verwenden, verwenden automatisch das kubelogin-Format. Ab Kubernetes Version 1.24 lautet das Standardformat der clusterUser-Anmeldeinformationen für Microsoft Entra ID-Cluster exec. Dafür ist eine kubelogin-Binärdatei im Ausführungspfad (PATH) erforderlich. Es gibt keine Verhaltensänderung für Nicht-Microsoft Entra-Cluster oder Microsoft Entra ID-Cluster mit einer Version, die älter als 1.24 ist. Vorhandene heruntergeladene kubeconfig-Dateien funktionieren weiterhin. Beim Abrufen der clusterUser-Anmeldeinformationen wird der optionale Abfrageparameter format eingebunden, um die Standardverhaltensänderung zu überschreiben. Sie können für das Format explizit azure angeben, wenn Sie das alte kubeconfig-Format beibehalten müssen.

  • Beim Abrufen der clusterUser-Anmeldeinformationen können Sie den Abfrageparameter format verwenden, um das Standardverhalten zu überschreiben. Sie können den Wert auf azure festlegen, um das ursprüngliche kubeconfig-Format zu verwenden.

    az aks get-credentials --format azure

  • Wenn Ihr mit Microsoft Entra integriertes Cluster Kubernetes Version 1.24 oder niedriger verwendet, müssen Sie das kubeconfig-Format manuell konvertieren.

    export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

Hinweis

Wenn Sie die folgende Meldung erhalten: Fehler: Das Azure-Authentifizierungs-Plug-In wurde entfernt., müssen Sie den Befehl kubelogin convert-kubeconfig ausführen, um das kubeconfig-Format manuell zu konvertieren.

Weitere Informationen finden Sie unter Bekannte Probleme in Azure Kubelogin.

Behandeln von Zugriffsproblemen

Wichtig

Der in diesem Abschnitt beschriebene Schritt schlägt eine alternative Authentifizierungsmethode im Vergleich zur normalen Microsoft Entra-Gruppenauthentifizierung vor. Verwenden Sie diese Option nur im Notfall.

Wenn Sie keinen administrativen Zugriff auf eine gültige Microsoft Entra-Gruppe haben, können Sie diesen Workaround verwenden. Melden Sie sich mit einem Konto, das über die Rolle Azure Kubernetes Service-Clusteradministrator*in verfügt, an und gewähren Sie Ihrem*Ihrer Gruppen- oder Mandantenadministrator*in Anmeldeinformationen für den Zugriff auf Ihren Cluster.

Nächste Schritte