使用服務主體搭配 Azure Kubernetes Service (AKS)

發行項
03/20/2024

AKS 叢集需要 Microsoft Entra 服務主體或受控識別，才能動態建立和管理其他 Azure 資源，例如 Azure Load Balancer 或 Azure Container Registry (ACR)。

注意

建議使用受控識別向 Azure 中其他資源進行驗證，而且這是 AKS 叢集的預設驗證方法。如需搭配叢集使用受控識別的詳細資訊，請參閱使用系統指派的受控識別。

此文章說明如何為您的 AKS 叢集建立及管理服務主體。

開始之前

若要建立 Microsoft Entra 服務主體，您必須有足夠權限向 Microsoft Entra 租用戶註冊應用程式，並將應用程式指派給您訂用帳戶中的角色。如果您沒有必要的權限，您需要要求您的 Microsoft Entra ID 或訂用帳戶系統管理員指派必要權限，或要求其預先建立服務主體以供您搭配 AKS 叢集使用。

如果您正在使用來自不同 Microsoft Entra 租用戶的服務主體，則部署叢集時可用的權限會有其他考量。您可能沒有讀取和寫入目錄資訊的適當權限。如需詳細資訊，請參閱 Microsoft Entra ID 中的預設使用者權限是什麼？

必要條件

如果使用 Azure CLI，您需要 Azure CLI 2.0.59 版或更新版本。執行 az --version 以尋找版本。如果您需要安裝或升級，請參閱安裝 Azure CLI。
如果使用 Azure PowerShell，您需要 Azure PowerShell 5.0.0 版或更新版本。執行 Get-InstalledModule -Name Az 以尋找版本。如果您需要安裝或升級，請參閱安裝 Azure 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 Container Registry(ACR)，則必須將這些資源的存取權委派給服務主體。使用系統指派的受控識別授與叢集的權限，可能需要 60 分鐘才能填入。

Azure CLI
Azure PowerShell

使用 az role assignment create 命令建立角色指派。將 appId 指派給特定範圍，例如資源群組或虛擬網路資源。角色會定義資源上的服務主體可擁有哪些權限。

注意

資源的 --scope 必須是完整的資源識別碼，例如 /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 必須是完整的資源識別碼，例如 /subscriptions/<guid>/resourceGroups/myResourceGroup 或 /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet
```
New-AzRoleAssignment -ApplicationId <ApplicationId> -Scope <resourceScope> -RoleDefinitionName Contributor
```

下列各節將詳細說明您可能需要指派的一般委派。

Azure Container Registry

Azure CLI
Azure PowerShell

如果您使用 Azure Container Registry(ACR) 作為您的容器映像存放區，則必須針對 AKS 叢集將可讀取和提取映像的權限授與服務主體。我們建議使用 az aks create 或 az aks update 命令來與登錄整合，並為服務主體指派適當的角色。如需詳細步驟，請參閱從 Azure Kubernetes Service 對 Azure Container Registry 進行驗證。

網路

您可以使用進階網路功能，其中虛擬網路和子網路或公用 IP 位址都在另一個資源群組中。指派虛擬網路內子網路上的網路參與者內建角色。或者，您也可以建立對於該資源群組中的網路資源擁有存取權限的自訂角色。如需詳細資訊，請參閱 AKS 服務權限。

儲存體

如果您需要存取另一個資源群組中的現有磁碟資源，請指派下列其中一組角色權限：

建立自訂角色並定義 Microsoft.Compute/disks/read 和 Microsoft.Compute/disks/write 角色權限，或
在資源群組上指派虛擬機器參與者內建角色。

Azure 容器執行個體

如果您使用 Virtual Kubelet 來與 AKS 整合，並選擇在不同於 AKS 叢集的資源群組中執行「Azure 容器執行個體」(ACI)，就必須將 ACI 資源群組的「參與者」權限授與 AKS 叢集服務主體。

其他考量

Azure CLI
Azure PowerShell

使用 AKS 和 Microsoft Entra 服務主體時，請考量下列事項：

Kubernetes 的服務主體是叢集設定的一部分，但不會使用此身分識別來部署叢集。
根據預設，此服務主體認證的有效期限為一年。您可以隨時更新或輪替服務主體認證。
每個服務主體都會與 Microsoft Entra 應用程式相關聯。您可以將 Kube 叢集的服務主體與任何有效的 Microsoft Entra 應用程式名稱產生關聯 (例如：https://www.contoso.org/example)。應用程式的 URL 不一定是實際端點。
當您指定服務主體用戶端識別碼時，請使用 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 應用程式相關聯。您可以將 Kube 叢集的服務主體與任何有效的 Microsoft Entra 應用程式名稱產生關聯 (例如：https://www.contoso.org/example)。應用程式的 URL 不一定是實際端點。
當您指定服務主體用戶端識別碼時，請使用 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 可以在數個殼層環境中執行，但格式稍有不同。如果使用 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 服務主體的詳細資訊，請參閱應用程式和服務主體物件。

如需如何更新認證的資訊，請參閱更新或輪替 AKS 中服務主體的認證。