服務主體與 Azure Kubernetes Service (AKS)Service principals with Azure Kubernetes Service (AKS)

若要使用 Azure Api 互動,AKS 叢集需要Azure Active Directory (AD) 服務主體To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. 需要服務主體才能動態建立及管理其他 Azure 資源,例如 Azure 負載平衡器或容器登錄 (ACR)。The service principal 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

當您建立 AKS 叢集在 Azure 入口網站或使用az 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 建立-針對-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

輸出類似於下列範例: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": "azure-cli-2019-03-04-21-35-28",
  "name": "http://azure-cli-2019-03-04-21-35-28",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"

為 AKS 叢集指定服務主體Specify a service principal for an AKS cluster

若要使用現有的服務主體,當您建立 AKS 叢集使用az aks 建立命令,使用--service-principal--client-secret參數來指定appIdpassword從的輸出az ad sp 建立-針對-rbac命令:To 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>

若使用 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:

  • 服務主體用戶端識別碼是您的 appIdService principal client ID is your appId
  • 服務主體用戶端祕密passwordService principal client secret is the password value

瀏覽至 Azure 投票的影像

將存取權委派給其他 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 Container Registry (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 角色指派建立命令。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 必須是完整的資源識別碼,例如 /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

下列各節將詳細說明您可能需要執行的一般委派。The following sections detail common delegations that you may need to make.

Azure Container RegistryAzure Container Registry

如果您使用 Azure Container Registry (ACR) 作為您的容器映像存放區,則必須對 AKS 叢集授與可讀取和提取映像的權限。If you use Azure Container Registry (ACR) as your container image store, you need to grant permissions for your AKS cluster to read and pull images. AKS 叢集的服務主體必須獲派登錄上的「讀者」 角色。The service principal of the AKS cluster must be delegated the Reader role on the registry. 如需詳細步驟,請參閱 < 授與 AKS 存取 ACRFor detailed steps, see Grant AKS access to ACR.


您可以使用進階網路功能,其中虛擬網路和子網路或公用 IP 位址都在另一個資源群組中。You may use advanced networking where the virtual network and subnet or public IP addresses are in another resource group. 指派下列一組角色權限:Assign one of the following set of role permissions:

  • 建立自訂角色並定義下列角色權限:Create a custom role and define the following role permissions:
    • Microsoft.Network/virtualNetworks/subnets/join/actionMicrosoft.Network/virtualNetworks/subnets/join/action
    • Microsoft.Network/virtualNetworks/subnets/readMicrosoft.Network/virtualNetworks/subnets/read
    • Microsoft.Network/virtualNetworks/subnets/writeMicrosoft.Network/virtualNetworks/subnets/write
    • Microsoft.Network/publicIPAddresses/join/actionMicrosoft.Network/publicIPAddresses/join/action
    • Microsoft.Network/publicIPAddresses/readMicrosoft.Network/publicIPAddresses/read
    • Microsoft.Network/publicIPAddresses/writeMicrosoft.Network/publicIPAddresses/write
  • 或者,您也可以指派網路參與者虛擬網路內的子網路上的內建角色Or, assign the Network Contributor built-in role on the subnet within the virtual network


您可能需要存取另一個資源群組中的現有磁碟資源。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 Container InstancesAzure Container Instances

如果您使用 Virtual 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.
  • 當您指定服務主體用戶端識別碼時,請使用 appId 的值。When you specify the service principal Client ID, use the value of the appId.
  • 在 Kubernetes 叢集中的代理程式節點 Vm,服務主體認證會儲存在檔案中 /etc/kubernetes/azure.jsonOn the agent node VMs in the Kubernetes cluster, the service principal credentials are stored in the file /etc/kubernetes/azure.json
  • 當您使用az aks 建立服務主體認證會寫入檔案的命令自動產生服務主體~/.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 叢集az 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 deleteTo delete the service principal, query for your cluster servicePrincipalProfile.clientId and then delete with az ad app 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)


Azure CLI,AKS 叢集中的服務主體認證會快取。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 建立可能表示發生問題的快取的服務主體認證: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.