使用 Azure Kubernetes 服务 (AKS) 的服务主体

项目
01/08/2024

AKS 群集需要 Microsoft Entra 服务主体或托管标识来动态创建和管理其他 Azure 资源，例如 Azure 负载均衡器或 Azure 容器注册表 (ACR)。

注意

建议使用托管标识对 Azure 中的其他资源进行身份验证，这是 AKS 群集的默认身份验证方法。有关如何在群集中使用托管标识的详细信息，请参阅使用系统分配的托管标识。

本文介绍如何创建和使用适用于 AKS 群集的服务主体。

开始之前

要创建 Microsoft Entra 服务主体，必须具有相应的权限，能够向 Microsoft Entra 租户注册应用程序，并将应用程序分配到订阅中的角色。如果没有必需的权限，则需要让 Microsoft Entra 或订阅管理员来分配必要的权限，或者预先创建一个可以与 AKS 群集配合使用的服务主体。

如果使用来自另一 Microsoft Entra 租户的服务主体，则还需围绕部署群集时可用的权限进行更多的考量。你可能没有读取和写入目录信息的适当权限。有关详细信息，请参阅 Microsoft Entra 中的默认用户权限是什么？

先决条件

如果使用的是 Azure CLI，需要 Azure CLI 2.0.59 或更高版本。运行 az --version 即可查找版本。如果需要进行安装或升级，请参阅安装 Azure CLI。
如果使用的是 Azure PowerShell，需要 Azure PowerShell 5.0.0 或更高版本。运行 Get-InstalledModule -Name Az 即可查找版本。如果需要安装或升级，请参阅安装 Azure Az PowerShell 模块。

使用“az ad sp create-for-rbac”命令创建服务主体。

az ad sp create-for-rbac --name myAKSClusterServicePrincipal

输出应类似于以下示例输出：

{
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

复制输出中 appId 和 password 的值。在下一个部分创建 AKS 群集时会用到这两个值。

使用“New-AzADServicePrincipal”命令创建服务主体。

New-AzADServicePrincipal -DisplayName myAKSClusterServicePrincipal -OutVariable sp

输出应类似于以下示例输出：

Secret                : System.Security.SecureString
ServicePrincipalNames : {559513bd-0c19-4c1a-87cd-851a26afd5fc, http://myAKSClusterServicePrincipal}
ApplicationId         : 559513bd-0c19-4c1a-87cd-851a26afd5fc
ObjectType            : ServicePrincipal
DisplayName           : myAKSClusterServicePrincipal
Id                    : 559513bd-0c19-4c1a-87cd-851a26afd5fc
Type                  :

这些值存储在在下一个部分创建 AKS 群集时使用的变量中。

使用以下命令，解密存储在“机密”安全字符串中的值。

$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
[System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

指定适用于 AKS 群集的服务主体

Azure CLI
Azure PowerShell

为使用“az aks create”命令新建的 AKS 群集使用现有服务主体，并使用 --service-principal 和 --client-secret 参数指定上一个部分得到的输出中的 appId 和 password。
```
az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>
```
注意

如果使用的是具有自定义机密的现有服务主体，请确保该机密不超过 190 字节。

使用以下命令将服务主体 ApplicationId 和 Secret 转换为“PSCredential”对象。

$Cred = New-Object -TypeName System.Management.Automation.PSCredential ($sp.ApplicationId, $sp.Secret)

使用“New-AzAksCluster”命令为新 AKS 群集使用现有服务主体，并使用之前创建的“PSCredential”对象指定为参数“ServicePrincipalIdAndSecret”的值。
```
New-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -ServicePrincipalIdAndSecret $Cred
```
注意

如果使用的是具有自定义机密的现有服务主体，请确保该机密不超过 190 字节。

委托对其他 Azure 资源的访问权限

AKS 群集的服务主体可以用来访问其他资源。例如，如果希望将 AKS 群集部署到现有 Azure 虚拟网络子网或连接到 Azure 容器注册表 (ACR)，则需要将对那些资源的访问权限委托给服务主体。使用系统分配的托管标识向群集授予的权限可能需要 60 分钟才能填充完毕。

Azure CLI
Azure PowerShell

使用 az role assignment create 命令创建角色分配。将 appId 分配到特定的作用域，例如一个资源组或虚拟网络资源。该角色定义服务主体在资源上拥有哪些权限。

注意

资源的 --scope 需要是完整的资源 ID，例如 /subscriptions/<guid>/resourceGroups/myResourceGroup 或 /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet。
```
az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor
```

使用 New-AzRoleAssignment 命令创建角色分配。将 ApplicationId 分配到特定的作用域，例如一个资源组或虚拟网络资源。该角色定义服务主体在资源上拥有哪些权限。

注意

资源的 Scope 需要是完整的资源 ID，例如 /subscriptions/<guid>/resourceGroups/myResourceGroup 或 /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet
```
New-AzRoleAssignment -ApplicationId <ApplicationId> -Scope <resourceScope> -RoleDefinitionName Contributor
```

以下各部分详述了可能需要分配的常见委派。

Azure 容器注册表

Azure CLI
Azure PowerShell

如果使用 Azure 容器注册表 (ACR) 作为容器映像存储，则需要向 AKS 群集的服务主体授予读取和拉取映像的权限。建议使用 az aks create 或 az aks update 命令与注册表集成，并为服务主体分配适当角色。有关详细步骤，请参阅通过 Azure Kubernetes 服务向 Azure 容器注册表进行身份验证。

网络

可以使用高级网络，在该网络中，虚拟网络和子网或公共 IP 地址位于另一资源组中。在虚拟网络的子网上分配网络参与者内置角色。或者，可以创建有权访问该资源组中网络资源的自定义角色。有关详细信息，请参阅 AKS 服务权限。

存储

如果需要访问另一个资源组中的现有磁盘资源，请分配以下角色权限集之一：

创建自定义角色，并定义 Microsoft.Compute/disks/read 和 Microsoft.Compute/disks/write 角色权限，或者
在资源组中分配虚拟机参与者内置角色。

Azure 容器实例

如果使用虚拟 Kubelet 与 AKS 集成，并选择在与 AKS 群集分开的资源组中运行 Azure 容器实例 (ACI)，则必须在 ACI 资源组上向 AKS 群集服务主体授予“参与者”权限。

其他注意事项

Azure CLI
Azure PowerShell

使用 AKS 和 Microsoft Entra 服务主体时，请考虑以下几点：

Kubernetes 的服务主体是群集配置的一部分，但不要使用此标识来部署群集。
默认情况下，服务主体凭据的有效期为一年。可以随时更新或轮换服务主体凭据。
每个服务主体都与一个 Microsoft Entra 应用程序相关联。 Kubernetes 群集的服务主体可以与任何有效的 Microsoft Entra 应用程序名称（例如 https://www.contoso.org/example）相关联。应用程序的 URL 不一定是实际的终结点。
指定服务主体客户端 ID 时，请使用 appId 的值。
在 Kubernetes 群集的代理节点 VM 中，服务主体凭据存储在 /etc/kubernetes/azure.json 文件中。
在删除使用“az aks create”命令创建的 AKS 群集时，不会删除自动创建的服务主体。
- 若要删除服务主体，请查询群集 servicePrincipalProfile.clientId，使用“az ad sp delete”命令将其删除。替换资源组名称的 -g 参数的值，以及群集名称的 -n 参数的值：
```
az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)
```

使用 AKS 和 Microsoft Entra 服务主体时，请考虑以下几点：

Kubernetes 的服务主体是群集配置的一部分，但不要使用此标识来部署群集。
默认情况下，服务主体凭据的有效期为一年。可以随时更新或轮换服务主体凭据。
每个服务主体都与一个 Microsoft Entra 应用程序相关联。 Kubernetes 群集的服务主体可以与任何有效的 Microsoft Entra 应用程序名称（例如 https://www.contoso.org/example）相关联。应用程序的 URL 不一定是实际的终结点。
指定服务主体客户端 ID 时，请使用 ApplicationId 的值。
在 Kubernetes 群集的代理节点 VM 中，服务主体凭据存储在 /etc/kubernetes/azure.json 文件中。
在删除使用“New-AzAksCluster”创建的 AKS 群集时，不会删除自动创建的服务主体。
- 若要删除服务主体，请查询群集 ServicePrincipalProfile.ClientId，使用“Remove-AzADServicePrincipal”命令将其删除。替换资源组名称的 -ResourceGroupName 参数的值，以及群集名称的 -Name 参数的值：
```
$ClientId = (Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster ).ServicePrincipalProfile.ClientId
Remove-AzADServicePrincipal -ApplicationId $ClientId
```

故障排除

Azure CLI
Azure PowerShell

Azure CLI 会缓存 AKS 群集的服务主体凭据。如果这些凭据过期，会在 AKS 群集部署期间遇到错误。如果运行“az aks create”命令并收到类似于以下内容的错误消息，则可能表示缓存的服务主体凭据有问题：

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

可以结合使用 az ad app credential list 命令与 "[].endDateTime" 查询，检查服务主体凭据的到期日期。

az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv

服务主体凭据的默认过期时间为一年后。如果凭据超过一年，可以重置现有凭据或创建新服务主体。

常规 Azure CLI 故障排除

Azure CLI 可以在多个 shell 环境中运行，但格式略有变化。如果 Azure CLI 命令出现意外结果，请参阅如何成功使用 Azure CLI。

Azure PowerShell 会缓存 AKS 群集的服务主体凭据。如果这些凭据过期，会在 AKS 群集部署期间遇到错误。如果运行“New-AzAksCluster”命令并收到类似于以下内容的错误消息，则可能表示缓存的服务主体凭据有问题：

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

可以使用 Get-AzADAppCredential 命令，检查服务主体凭据的到期日期。输出将显示凭据的 StartDateTime。

Get-AzADAppCredential -ApplicationId <ApplicationId>

服务主体凭据的默认过期时间为一年后。如果凭据超过一年，可以重置现有凭据或创建新服务主体。

后续步骤

有关 Microsoft Entra 服务主体的详细信息，请参阅 Application Objects and Service Principal Objects（应用程序对象和服务主体对象）。

有关如何更新凭据的信息，请参阅为 AKS 中的服务主体更新或轮换凭据。