共用方式為

使用 kubelogin 為 Kubernetes 叢集啟用 Azure 受控識別驗證

  • 發行項

AKS 受控 Microsoft Entra 整合可簡化 Microsoft Entra 整合流程。 之前須建立客戶端和伺服器應用程式，而且 Microsoft Entra 租用戶必須指派目錄讀者角色許可權。 現在，AKS 資源提供者會為您管理客戶端和伺服器應用程式。

叢集管理員能夠根據使用者身分識別或目錄群組成員資格，設定 Kubernetes 角色型存取控制 (Kubernetes RBAC)。 透過 OpenID Connect 向 AKS 叢集提供 Microsoft Entra 驗證。 OpenID Connect 是以 OAuth 2.0 通訊協定為建置基礎的身分識別層。 如需 OpenID Connect 的詳細資訊，請參閱 OpenID Connect 文件。

參考 Microsoft Entra 文件，深入了解 Microsoft Entra 整合流程。

本文提供如何透過 AKS 叢集啟用和使用 Azure 資源的受控識別的詳細資料。

限制

以下是在 AKS 整合 Azure 受控識別驗證的限制。

  • 一旦新增，就無法停用整合。
  • 不支援從整合式叢集降級為舊版 Microsoft Entra ID 叢集。
  • 不支援 Kubernetes RBAC 的叢集無法新增整合。

開始之前

必須符合下列需求，才能正確安裝受控識別的 AKS 附加元件。

  • 已安裝並設定 Azure CLI 2.29.0 以上版本。 執行 az --version 以尋找版本。 如果您需要安裝或升級，請參閱安裝 Azure CLI。
  • 您需要最低版本為 1.18.1 或 kubelogin 的 kubectl。 使用 Azure CLI 和 Azure PowerShell 模組時，會加入並自動管理這兩個命令。 也就是說，這些命令會依預設升級，而且不需要也不建議執行 az aks install-cli。 如使用自動化流程，必須管理正確或最新版的升級程序。 Kubernetes 和 kubectl 次要版本之間的差異不應超過一個版本。 否則，錯誤版本會發生驗證問題。
  • 如果您正在使用 helm，則至少需要 helm 3.3 版本。
  • 叢集必須有 Microsoft Entra 群組才能使用此設定。 此群組會註冊為叢集上的管理員群組，以授與叢集管理員權限。 如果您沒有現有 Microsoft Entra 群組，則可以使用 az ad group create 命令來予以建立。

注意

使用 1.24 版以上 Kubernetes 版本的 Microsoft Entra 整合叢集會自動採用 kubelogin 格式。 從 Kubernetes 1.24 版開始，Microsoft Entra ID 叢集的 clusterUser 認證預設格式為 exec，這需要執行 PATH 中的 kubelogin 二進位檔。 在非 Microsoft Entra 叢集或執行 1.24 以下版本的 Microsoft Entra ID 叢集中，則沒有任何行為變更。 現有的已下載 kubeconfig 會繼續運作。 取得 clusterUser 認證以覆寫預設行為變更時，會包含選用查詢參數 format。 如需要保留舊的 kubeconfig 格式，可將格式明確指定為 azure。

在 AKS 叢集上啟用整合

建立新叢集

  1. 使用 az group create 命令建立 Azure 資源群組。

    az group create --name myResourceGroup --location centralus

  2. 使用 az aks create 命令建立 AKS 叢集，並為 Microsoft Entra 群組啟用管理存取權限。

    az aks create \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --enable-aad \
    --aad-admin-group-object-ids <id> [--aad-tenant-id <id>] \
    --generate-ssh-keys

    成功建立 AKS 受控 Microsoft Entra ID 叢集之後，回應本文中會包含下列部分：

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

使用現有的叢集

使用 az aks update 命令在現有的 Kubernetes RBAC 啟用叢集上啟用 AKS 受控 Microsoft Entra 整合。 請務必設定系統管理員群組，保留對叢集存取權限。

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

成功啟動 AKS 受控 Microsoft Entra ID 叢集的回應本文中會包含下列部分：

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

將舊版叢集移轉至整合

如果您的叢集使用舊版 Microsoft Entra 整合，您可以透過 az aks update 命令升級至 AKS 受控 Microsoft Entra 整合。

警告

您可能會在移轉期間遇到 API 伺服器停機。 建議您在非商務時段升級。 升級之後，kubeconfig 內容發生變更。 您需要執行 az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> 將新的認證合併到 kubeconfig 檔案中。

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

成功移轉 AKS 受控 Microsoft Entra ID 叢集之後，回應本文中會包含下列部分：

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

存取已啟用的叢集

  1. 使用 az aks get-credentials 命令，取得使用者認證以存取叢集。

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

  2. 遵循指示進行登入。

  3. 設定 kubelogin 以使用 Azure CLI。

    kubelogin convert-kubeconfig -l azurecli

  4. 使用 kubectl get nodes 命令查看叢集中的節點。

    kubectl get nodes

使用 kubelogin 進行非互動式登入

有一些不支援 kubectl 的非互動式案例。 在這些情況下，請使用 kubelogin 以非互動式服務主體認證連線到叢集，以執行持續整合管線。

注意

使用 1.24 版以上 Kubernetes 版本的 Microsoft Entra 整合叢集會自動採用 kubelogin 格式。 從 Kubernetes 1.24 版開始，Microsoft Entra ID 叢集的 clusterUser 認證預設格式為 exec，這需要執行 PATH 中的 kubelogin 二進位檔。 在非 Microsoft Entra 叢集或執行 1.24 以下版本的 Microsoft Entra ID 叢集中，則沒有任何行為變更。 現有的已下載 kubeconfig 會繼續運作。 取得 clusterUser 認證以覆寫預設行為變更時，會包含選用查詢參數 format。 如需要保留舊的 kubeconfig 格式，可將格式明確指定為 azure。

  • 取得 clusterUser 認證時，您可以使用 format 查詢參數來覆寫預設行為。 您可以將值設定為 azure，以使用原始 kubeconfig 格式：

    az aks get-credentials --format azure

  • 如果您的 Microsoft Entra 整合式叢集使用 Kubernetes 1.24 版或更低版本，您必須手動轉換 kubeconfig 格式。

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

注意

如果您收到訊息錯誤：Azure 驗證外掛程式已移除。，您必須執行 kubelogin convert-kubeconfig 命令以手動轉換 kubeconfig 格式。

如需詳細資訊，請參閱 Azure Kubelogin 已知問題 (英文)。

針對存取問題進行疑難排解

重要

本節所述的步驟會建議替代驗證方法 (與一般 Microsoft Entra 群組驗證相比)。 只有在緊急狀況中才能使用。

如果您缺少有效 Microsoft Entra 群組的系統管理存取權，您可以遵循此因應措施。 使用屬於 Azure Kubernetes Service 叢集管理員角色成員的帳戶登入，並將憑證授予群組或租用戶管理員以存取叢集。

下一步