使用 kubelogin 为 Kubernetes 群集启用 Azure 托管标识身份验证

项目
08/08/2024

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 群集上启用集成

创建新群集

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

az group create --name myResourceGroup --location chinanorth3

创建一个 AKS 群集，并使用 az aks create 命令为 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"
    }

访问已启用的群集

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

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

按照说明进行登录。

将 kubelogin 设置为使用 Azure CLI。

kubelogin convert-kubeconfig -l azurecli

使用 kubectl get nodes 命令查看群集中的节点。
```
kubectl get nodes
```

有一些不支持 kubectl 的非交互式方案。在这些情况下，请使用 kubelogin 通过非交互式服务主体凭据连接到群集，以执行持续集成管道。

注意

在获取 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 的群集。

通过