Compartir a través de

AKS 托管的 Microsoft Entra 集成

  • Artículo

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 托管的 Microsoft Entra 集成。
  • 不支持将 AKS 托管的 Microsoft Entra 集成群集更改为旧版 Microsoft Entra ID。
  • AKS 托管的 Microsoft Entra 集成不支持未启用 Kubernetes RBAC 的群集。

开始之前

  • 确保已安装且已配置 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 群集上启用 AKS 托管的 Microsoft Entra 集成

创建新群集

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

    az group create --name myResourceGroup --location chinaeast

  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 ID 群集升级到 AKS 托管的 Microsoft Entra 集成

如果你的群集使用旧版 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"
    }

访问 AKS 托管的已启用 Microsoft Entra ID 的群集

  1. 使用 az aks get-credentials 命令获取用户凭据以访问群集。

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

  2. 按照说明进行登录。

  3. 使用 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 已知问题。

排查 AKS 托管的 Microsoft Entra ID 访问权限问题

重要

本部分中介绍的步骤会绕过正常的 Microsoft Entra 组身份验证。 请仅在紧急情况下使用它们。

如果因为无权访问具有群集访问权限的有效 Microsoft Entra 组而被永久阻止，你仍可以获取管理员凭据以直接访问群集。 你需要具有访问 Azure Kubernetes 服务群集管理员内置角色的权限。

后续步骤