在已启用 Azure Arc 的 Kubernetes 中部署和配置工作负载联合身份验证（预览版）

项目
2025-04-30

可以使用 Azure CLI 在已启用 Azure Arc 的 Kubernetes 群集上启用工作负荷标识功能。此过程遵循以下高级步骤：

在已启用 Arc 的新或现有 Kubernetes 群集上启用工作负荷标识功能。
创建托管标识（或应用注册）和 Kubernetes 服务帐户。
配置托管标识以进行令牌联合身份验证。
配置服务帐户注释和应用程序 Pod 标签以使用工作负载标识。
在 Kubernetes 群集上配置工作负荷标识设置。
在群集上禁用工作负荷标识。

有关此功能的概述，请参阅Azure Arc 启用的 Kubernetes 中的工作负载身份联合（预览）。

重要

Azure Arc 工作负荷标识联合功能目前以预览版提供。有关 beta 版本、预览版或尚未正式发布的版本的 Azure 功能所适用的法律条款，请参阅 Azure 预览版的补充使用条款。

小窍门

本文介绍在已启用 Arc 的 Kubernetes 群集上部署和配置工作负荷标识所需的步骤。若要了解如何在其他类型的群集上启用工作负荷标识，请参阅以下文章：

Azure Kubernetes 服务 (AKS)

先决条件

以下 Kubernetes 分发版支持已启用 Azure Arc 的 Kubernetes 群集（预览版）的工作负荷标识：
- 运行 K3s 的 Ubuntu Linux 群集
- Edge Essentials 上的 AKS
- HCI 23H2 上的 AKS

若要使用工作负荷标识功能，必须具有 Azure CLI 2.64 或更高版本，以及 az connectedk8s 版本 1.10.0 或更高版本。在更新 az connectedk8s 版本之前，请务必更新 Azure CLI 版本。

在群集上启用工作负荷标识

按照相应的步骤为已启用 Arc 的新 Kubernetes 群集或现有群集启用工作负荷标识功能。在这两种情况下，请确保将名称和资源组替换为值，并根据需要配置参数。

参数	DESCRIPTION	必选
`--enable-oidc-issuer`	生成并托管 OIDC 颁发者 URL，这是一个可公开访问的 URL，该 URL 允许 API 服务器查找用于验证令牌的公共签名密钥。	必选
`--enable-workload-identity`	安装一个可变准入 Webhook，该 Webhook 会将已签名的服务帐户令牌投影到一个为人熟知的路径，并根据带注释的服务帐户的设置，将与身份验证相关的环境变量注入到应用程序 Pod 中。对于新群集，如果未启用此参数，则必须在一个为人熟知的路径上挂载投影卷，以便向该路径公开已签名的服务帐户令牌。	可选

设置环境变量。

为方便起见，本文中的示例引用了下面定义的环境变量。将这些值替换为你自己的值：

export RESOURCE_GROUP="myRG"
export LOCATION="chinaeast2"
export CLUSTER_NAME="mycluster"
export SERVICE_ACCOUNT_NAMESPACE="myKubernetesnamespace"
export SERVICE_ACCOUNT_NAME="mysa"
export SUBSCRIPTION="$(az account show --query id --output tsv)"
export USER_ASSIGNED_IDENTITY_NAME="myIdentity"
export FEDERATED_IDENTITY_CREDENTIAL_NAME="myFedIdentity"

若要创建启用了工作负荷标识的已启用 Azure Arc 的群集，请使用以下命令：

az connectedk8s connect --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" --enable-oidc-issuer --enable-workload-identity

若要在已启用 Arc 的现有 Kubernetes 群集上启用工作负荷标识，请使用 update 该命令。

az connectedk8s update --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" --enable-oidc-issuer --enable-workload-identity

检索 OIDC 颁发者 URL

提取 OIDC 颁发者 URL 并将其保存到环境变量。将在以下步骤中使用此颁发者 URL。

export OIDC_ISSUER="$(az connectedk8s show --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" \ 
    --query "oidcIssuerProfile.issuerUrl" \  
    --output tsv)"

若要查看环境变量，请输入 echo ${OIDC_ISSUER}。环境变量应包含类似于以下示例的证书颁发者 URL：

https://northamerica.oic.prod-arc.azure.com/00000000-0000-0000-0000-000000000000/12345678-1234-1234-1234-123456789123/

默认情况下，颁发者被配置为使用基本 URL https://{region}.oic.prod-arc.azure.com/{tenant_id}/{uuid}，其中值 {region} 对应于创建启用 Arc 的 Kubernetes 集群的位置。值 {uuid} 表示 OpenID Connect (OIDC) 密钥，这是每个群集的不可变随机生成全局唯一标识符。

创建托管标识

使用 az identity create 命令创建用户分配的托管标识。使用工作负荷标识时，会在用户分配的管理身份令牌和 Kubernetes 集群的服务帐户令牌之间建立信任关系。

az identity create \ 
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --subscription "${SUBSCRIPTION}"

提取托管标识的客户端 ID，并将其存储在环境变量中。

export USER_ASSIGNED_CLIENT_ID="$(az identity show \ 
    --resource-group "${RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'clientId' \
    --output tsv)"

创建 Kubernetes 服务帐户

创建一个 Kubernetes 服务帐户，并使用在上一步创建的托管标识的客户端 ID 对其进行批注。在两者之间建立信任关系后，与 Kubernetes 服务帐户关联的签名令牌将交换为 Microsoft Entra ID 令牌。

应用以下 YAML 代码片段以创建添加工作负荷标识注释的服务帐户。

apiVersion: v1 
kind: ServiceAccount 
metadata: 
  annotations: 
    azure.workload.identity/client-id: "${USER_ASSIGNED_CLIENT_ID}" 
  name: "${SERVICE_ACCOUNT_NAME}" 
  namespace: "${SERVICE_ACCOUNT_NAMESPACE}"

创建联合标识凭据

使用 az identity federated-credential create 命令在托管标识、服务帐户颁发者和使用者之间创建联合标识凭据。此步骤建立 Kubernetes 群集与用于交换令牌的 Microsoft Entra 之间的信任关系。有关 Azure Entra 中的联合标识凭据的详细信息，请参阅 Microsoft Entra ID 中的联合标识凭据概述。

az identity federated-credential create \ 
    --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} \ 
    --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \ 
    --resource-group "${RESOURCE_GROUP}" \ 
    --issuer "${OIDC_ISSUER}" \ 
    --subject system:serviceaccount:"${SERVICE_ACCOUNT_NAMESPACE}":"${SERVICE_ACCOUNT_NAME}" \ 
    --audience api://AzureADTokenExchange

注释

添加联邦标识凭据后，传播需要几秒钟时间。如果在添加联合标识凭据后立即发出令牌请求，则在刷新缓存之前，请求可能会失败。若要避免此问题，请在添加联合标识凭据后在脚本中添加轻微延迟。

配置服务帐户注释和 Pod 标签

以下服务帐户和 Pod 注释可用于根据应用程序要求配置工作负载标识。如果 --enable-workload-identity 设置为 true，则下面的 Pod 标签是必需的。

服务帐户批注

所有服务帐户注释都是可选的。如果未指定批注，将使用默认值。

注释	DESCRIPTION	违约
`azure.workload.identity/client-id`	Microsoft Entra 应用程序客户端 ID，将与 Pod 一起使用。
`azure.workload.identity/tenant-id`	注册 Microsoft Entra 应用程序的 Azure 租户 ID。	`AZURE_TENANT_ID` 从 `azure-wi-webhook-config` ConfigMap 中提取的环境变量。
`azure.workload.identity/service-account-token-expiration`	投影服务帐户令牌的 `expirationSeconds` 字段。配置以防止服务帐户令牌刷新期间出现错误导致的停机。 Kubernetes 服务帐户令牌过期时间与 Microsoft Entra 令牌无关。 Microsoft Entra 令牌在颁发后 24 小时过期。	3600 （支持的范围为 3600-86400）

Pod 标签

注释	DESCRIPTION	建议的值	必选
`azure.workload.identity/use`	在 Pod 模板规格中必填。如果 `--enable-workload-identity` 设置为 `true`，则可变准入 Webhook 只会对带有此标签的 Pod 执行可变操作，以便注入特定于 Azure 的环境变量以及投影的服务帐户令牌卷。	`true`	是的

Pod 注释

所有 Pod 标注都是可选的。如果未指定批注，将使用默认值。

注释	DESCRIPTION	违约
`azure.workload.identity/service-account-token-expiration`	投影服务帐户令牌的 `expirationSeconds` 字段。配置以防止服务帐户令牌刷新期间出现错误导致的停机。 Kubernetes 服务帐户令牌过期时间与 Microsoft Entra 令牌无关。 Microsoft Entra 令牌在颁发后 24 小时过期。	3600 （支持的范围为 3600-86400）
`azure.workload.identity/skip-containers`	表示一个以分号分隔的容器列表，这些容器将跳过添加投影的服务帐户令牌卷的操作。例如： `container1;container2`。	默认情况下，如果 Pod 带有 `azure.workload.identity/use: true` 标签，那么投影的服务帐户令牌卷将添加到所有容器中。

在 Kubernetes 群集上配置工作负荷标识设置

需要将 Kubernetes 群集上的 API 服务器配置为颁发包含可公开访问的 OIDC 颁发者 URL 的服务帐户令牌（以便 Entra 知道在何处查找用于验证令牌的公钥）。

若要使用 K3 在 Ubuntu Linux 上配置工作负荷标识设置，请执行以下步骤来完成配置：

创建 k3s 配置文件。

编辑 /etc/rancher/k3s/config.yaml 以添加以下设置：

   `kube-apiserver-arg:  
     - 'service-account-issuer=${OIDC_ISSUER}'
     - 'service-account-max-token-expiration=24h'`

保存 config.yaml。
使用命令 systemctl restart k3s重启 k3s API 服务器。

建议经常轮换服务帐户密钥。有关详细信息，请参阅 Service-Account 颁发者密钥轮换。

禁用工作负载标识

若要在已启用 Azure Arc 的 Kubernetes 群集上禁用工作负荷标识功能，请运行以下命令：

az connectedk8s update
    --resource-group "${RESOURCE_GROUP}"
    --name "${CLUSTER_NAME}"
    --disable-workload-identity

后续步骤

浏览一个示例，了解如何将应用程序配置为使用工作负荷标识。

通过