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

AKS 群集需要 Azure Active Directory (AD) 服务主体托管标识才能与 Azure API 交互。To interact with Azure APIs, an AKS cluster requires either an Azure Active Directory (AD) service principal or a managed identity. 需要服务主体或托管标识才能动态创建和管理其他 Azure 资源,例如 Azure 负载均衡器或容器注册表 (ACR)。A service principal or managed identity is needed to dynamically create and manage other Azure resources such as an Azure load balancer or container registry (ACR).

本文介绍如何创建和使用适用于 AKS 群集的服务主体。This article shows how to create and use a service principal for your AKS clusters.

准备阶段Before you begin

若要创建 Azure AD 服务主体,必须具有相应的权限,能够向 Azure AD 租户注册应用程序,并将应用程序分配到订阅中的角色。To create an Azure AD service principal, you must have permissions to register an application with your Azure AD tenant, and to assign the application to a role in your subscription. 如果没有必需的权限,可能需要请求 Azure AD 或订阅管理员来分配必需的权限,或者预先创建一个可以与 AKS 群集配合使用的服务主体。If you don't have the necessary permissions, you might need to ask your Azure AD or subscription administrator to assign the necessary permissions, or pre-create a service principal for you to use with the AKS cluster.

如果使用来自另一 Azure AD 租户的服务主体,则还需围绕部署群集时可用的权限进行更多的考虑。If you are using a service principal from a different Azure AD tenant, there are additional considerations around the permissions available when you deploy the cluster. 你可能没有读取和写入目录信息的适当权限。You may not have the appropriate permissions to read and write directory information. 有关详细信息,请参阅 Azure Active Directory 中的默认用户权限是什么?For more information, see What are the default user permissions in Azure Active Directory?

还需安装并配置 Azure CLI 2.0.59 或更高版本。You also need the Azure CLI version 2.0.59 or later installed and configured. 运行 az --version 即可查找版本。Run az --version to find the version. 如果需要进行安装或升级,请参阅安装 Azure CLIIf you need to install or upgrade, see Install Azure CLI.

自动创建和使用服务主体Automatically create and use a service principal

通过 Azure 门户或 az aks create 命令创建 AKS 群集时,Azure 可以自动生成服务主体。When you create an AKS cluster in the Azure portal or using the az aks create command, Azure can automatically generate a service principal.

在下述 Azure CLI 示例中,尚未指定服务主体。In the following Azure CLI example, a service principal is not specified. 在此方案中,Azure CLI 为 AKS 群集创建一个服务主体。In this scenario, the Azure CLI creates a service principal for the AKS cluster. 若要成功完成此操作,Azure 帐户必须具有创建服务主体所需的相应权限。To successfully complete the operation, your Azure account must have the proper rights to create a service principal.

az aks create --name myAKSCluster --resource-group myResourceGroup

手动创建服务主体Manually create a service principal

若要通过 Azure CLI 手动创建服务主体,请使用 az ad sp create-for-rbac 命令。To manually create a service principal with the Azure CLI, use the az ad sp create-for-rbac command. 在以下示例中,--skip-assignment 参数阻止系统分配更多的默认分配。In the following example, the --skip-assignment parameter prevents any additional default assignments being assigned:

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

输出类似于以下示例。The output is similar to the following example. 记下你自己的 appIdpasswordMake a note of your own appId and password. 在下一部分创建 AKS 群集时,会使用这些值。These values are used when you create an AKS cluster in the next section.

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

指定适用于 AKS 群集的服务主体Specify a service principal for an AKS cluster

若要在通过 az aks create 命令创建 AKS 群集时使用现有的服务主体,请使用 az ad sp create-for-rbac 命令的输出中的 --service-principal--client-secret 参数来指定 appIdpasswordTo use an existing service principal when you create an AKS cluster using the az aks create command, use the --service-principal and --client-secret parameters to specify the appId and password from the output of the az ad sp create-for-rbac command:

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>


如果使用的是具有自定义机密的现有服务主体,请确保该机密不超过 190 字节。If you're using an existing service principal with customized secret, ensure the secret is no longer than 190 bytes.

如果使用 Azure 门户来部署 AKS 群集,请在“创建 Kubernetes 群集”对话框的“身份验证”页上选择“配置服务主体”。 If you deploy an AKS cluster using the Azure portal, on the Authentication page of the Create Kubernetes cluster dialog, choose to Configure service principal. 选择“使用现有”并指定以下值:Select Use existing, and specify the following values:

  • 服务主体客户端 ID 是你的 appIdService principal client ID is your appId

  • 服务主体客户端机密 是密码值Service principal client secret is the password value

    浏览到 Azure Vote 的图像

委托对其他 Azure 资源的访问权限Delegate access to other Azure resources

AKS 群集的服务主体可以用来访问其他资源。The service principal for the AKS cluster can be used to access other resources. 例如,如果希望将 AKS 群集部署到现有 Azure 虚拟网络子网或连接到 Azure 容器注册表 (ACR),则需要将对那些资源的访问权限委托给服务主体。For example, if you want to deploy your AKS cluster into an existing Azure virtual network subnet or connect to Azure Container Registry (ACR), you need to delegate access to those resources to the service principal.

若要委托权限,请使用 az role assignment create 命令创建一个角色分配。To delegate permissions, create a role assignment using the az role assignment create command. appId 分配到特定的作用域,例如一个资源组或虚拟网络资源。Assign the appId to a particular scope, such as a resource group or virtual network resource. 然后,通过角色定义服务主体对资源的具体权限,如以下示例所示:A role then defines what permissions the service principal has on the resource, as shown in the following example:

az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

资源的 --scope 需要是完整的资源 ID,例如 /subscriptions/<guid>/resourceGroups/myResourceGroup 或 /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnetThe --scope for a resource needs to be a full resource ID, such as /subscriptions/<guid>/resourceGroups/myResourceGroup or /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet


如果从节点资源组删除了参与者角色分配,则以下操作可能会失败。If you have removed the Contributor role assignment from the node resource group, the operations below may fail.

以下各部分详述了可能需要使用的常见委托。The following sections detail common delegations that you may need to make.

Azure 容器注册表Azure Container Registry

如果使用 Azure 容器注册表 (ACR) 作为容器映像存储,则需要向 AKS 群集的服务主体授予读取和拉取映像的权限。If you use Azure Container Registry (ACR) as your container image store, you need to grant permissions to the service principal for your AKS cluster to read and pull images. 目前,建议的配置是使用 az aks createaz aks update 命令与注册表集成,并为服务主体分配适当的角色。Currently, the recommended configuration is to use the az aks create or az aks update command to integrate with a registry and assign the appropriate role for the service principal. 有关详细步骤,请参阅通过 Azure Kubernetes 服务向 Azure 容器注册表进行身份验证For detailed steps, see Authenticate with Azure Container Registry from Azure Kubernetes Service.


可以使用高级网络,在该网络中,虚拟网络和子网或公共 IP 地址位于另一资源组中。You may use advanced networking where the virtual network and subnet or public IP addresses are in another resource group. 在虚拟网络的子网上分配网络参与者内置角色。Assign the Network Contributor built-in role on the subnet within the virtual network. 或者,可以创建有权访问该资源组中网络资源的自定义角色Alternatively, you can create a custom role with permissions to access the network resources in that resource group. 有关更多详细信息,请参阅 AKS 服务权限See AKS service permissions for more details.


可能需要访问另一资源组中的现有磁盘资源。You may need to access existing Disk resources in another resource group. 分配下列角色权限集之一:Assign one of the following set of role permissions:

  • 创建一个自定义角色,并定义以下角色权限:Create a custom role and define the following role permissions:
    • Microsoft.Compute/disks/readMicrosoft.Compute/disks/read
    • Microsoft.Compute/disks/writeMicrosoft.Compute/disks/write
  • 或者,在资源组中分配存储帐户参与者内置角色Or, assign the Storage Account Contributor built-in role on the resource group

Azure 容器实例Azure Container Instances

如果使用虚拟 Kubelet 与 AKS 集成并选择在与 AKS 群集分开的资源组中运行 Azure 容器实例 (ACI),则必须在 ACI 资源组上授予 AKS 服务主体“参与者”权限。If you use Virtual Kubelet to integrate with AKS and choose to run Azure Container Instances (ACI) in resource group separate to the AKS cluster, the AKS service principal must be granted Contributor permissions on the ACI resource group.

其他注意事项Additional considerations

使用 AKS 和 Azure AD 服务主体时,请牢记以下注意事项。When using AKS and Azure AD service principals, keep the following considerations in mind.

  • Kubernetes 的服务主体是群集配置的一部分。The service principal for Kubernetes is a part of the cluster configuration. 但是,请勿使用标识来部署群集。However, don't use the identity to deploy the cluster.
  • 默认情况下,服务主体凭据的有效期为一年。By default, the service principal credentials are valid for one year. 可以随时更新或轮换服务主体凭据You can update or rotate the service principal credentials at any time.
  • 每个服务主体都与一个 Azure AD 应用程序相关联。Every service principal is associated with an Azure AD application. Kubernetes 群集的服务主体可以与任何有效的 Azure AD 应用程序名称(例如 https://www.contoso.org/example )相关联。The service principal for a Kubernetes cluster can be associated with any valid Azure AD application name (for example: https://www.contoso.org/example). 应用程序的 URL 不一定是实际的终结点。The URL for the application doesn't have to be a real endpoint.
  • 指定服务主体 客户端 ID 时,请使用 appId 的值。When you specify the service principal Client ID, use the value of the appId.
  • 在 Kubernetes 群集的代理节点 VM 中,服务主体凭据存储在 /etc/kubernetes/azure.json 文件中On the agent node VMs in the Kubernetes cluster, the service principal credentials are stored in the file /etc/kubernetes/azure.json
  • 使用 az aks create 命令自动生成服务主体时,会将服务主体凭据写入用于运行命令的计算机上的 ~/.azure/aksServicePrincipal.json 文件中。When you use the az aks create command to generate the service principal automatically, the service principal credentials are written to the file ~/.azure/aksServicePrincipal.json on the machine used to run the command.
  • 如果没有在其他 AKS CLI 命令中明确传递服务主体,则将使用位于 ~/.azure/aksServicePrincipal.json 的默认服务主体。If you do not specifically pass a service principal in additional AKS CLI commands, the default service principal located at ~/.azure/aksServicePrincipal.json is used.
  • 也可以选择删除 aksServicePrincipal.json 文件,AKS 将创建新的服务主体。You can also optionally remove the aksServicePrincipal.json file, and AKS will create a new service principal.
  • 删除通过 az aks create 创建的 AKS 群集时,不会删除自动创建的服务主体。When you delete an AKS cluster that was created by az aks create, the service principal that was created automatically is not deleted.
    • 若要删除服务主体,请查询群集 servicePrincipalProfile.clientId,然后使用 az ad app delete 进行删除。To delete the service principal, query for your cluster servicePrincipalProfile.clientId and then delete with az ad sp delete. 将以下资源组和群集名称替换为你自己的值:Replace the following resource group and cluster names with your own values:

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)


AKS 群集的服务主体凭据由 Azure CLI 缓存。The service principal credentials for an AKS cluster are cached by the Azure CLI. 如果这些凭据已过期,则会在部署 AKS 群集时遇到错误。If these credentials have expired, you encounter errors deploying AKS clusters. 运行 az aks create 时,如果出现以下错误消息,则可能表示缓存的服务主体凭据出现问题:The following error message when running az aks create may indicate a problem with the cached service principal credentials:

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'.

请使用以下命令检查凭据文件的存在时间:Check the age of the credentials file using the following command:

ls -la $HOME/.azure/aksServicePrincipal.json

服务主体凭据的默认过期时间为一年后。The default expiration time for the service principal credentials is one year. 如果 aksServicePrincipal.json 文件的存在时间已超出一年,请删除该文件,然后尝试再次部署 AKS 群集。If your aksServicePrincipal.json file is older than one year, delete the file and try to deploy an AKS cluster again.

后续步骤Next steps

若要详细了解 Azure Active Directory 服务主体,请参阅应用程序和服务主体对象For more information about Azure Active Directory service principals, see Application and service principal objects.

有关如何更新凭据的信息,请参阅为 AKS 中的服务主体更新或轮换凭据For information on how to update the credentials, see Update or rotate the credentials for a service principal in AKS.