你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 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 集成流的详细信息。

本文详细介绍如何启用 Azure 资源托管标识并将其与 AKS 群集结合使用。

限制

以下是在 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。 如果需要保留旧的 格式，可将 format 显式指定为 azure。kubeconfig

在 AKS 群集上启用集成

创建新群集

1. 使用 az group create 命令创建 Azure 资源组。

   az group create --name myResourceGroup --location centralus
   

2. 创建一个 AKS 群集，并使用 az aks create 命令为 Microsoft Entra 组启用管理访问权限。

   az aks create -g myResourceGroup -n 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"
   }
   

使用现有群集

使用 az aks update 命令在现有已启用 Kubernetes RBAC 的群集上启用 AKS 托管的 Microsoft Entra 集成。 确保将管理员组设置为在群集上保留访问权限。

az aks update -g MyResourceGroup -n 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 -g myResourceGroup -n 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。 如果需要保留旧的 格式，可将 format 显式指定为 azure。kubeconfig

• 在获取 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 服务群集管理员角色的成员帐户登录，并授予用来访问群集的组或租户管理员凭据。

后续步骤

• 了解 Microsoft Entra 与 Kubernetes RBAC 的集成。
• 详细了解 AKS 和 Kubernetes 标识概念。
• 了解如何对 AKS 中所有受支持的 Microsoft Entra 身份验证方法使用 kubelogin。
• 使用 Azure 资源管理器 (ARM) 模板创建已启用 AKS 托管的 Microsoft Entra ID 的群集。