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

發行項
08/02/2024

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

為了實現最佳安全性和易用性，Microsoft 建議使用受控識別，而不是服務主體，來授權從 AKS 叢集存取 Azure 中的其他資源。受控識別是一種特殊的服務主體，可用來取得 Microsoft Entra 認證，而不需要管理和保護認證。如需有關搭配叢集使用受控識別的詳細資訊，請參閱在 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 模組。

建立服務主體

建立叢集前，請先建立服務主體。

Azure CLI
Azure PowerShell

使用 az ad sp create-for-rbac 命令建立服務主體。

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

輸出應該類似下列範例輸出：

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

從輸出中複製 appId 和 password 的值。在下一節中建立 AKS 叢集時，您會使用這些叢集。

使用 New-AzADServicePrincipal 命令建立服務主體。

New-AzADServicePrincipal -DisplayName myAKSClusterServicePrincipal -OutVariable sp

輸出應該類似下列範例輸出：

Secret                : System.Security.SecureString
ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://myAKSClusterServicePrincipal}
ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ObjectType            : ServicePrincipal
DisplayName           : myAKSClusterServicePrincipal
Id                    : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Type                  :

這些值會儲存在下一節中建立 AKS 叢集時所使用的變數。

使用下列命令，解密儲存在祕密安全字串中的值。

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

使用 az aks create 命令為新的 AKS 叢集使用現有的服務主體，並使用 --service-principal 和 --client-secret 參數來指定您在上一節收到的輸出 appId 和 password。
```
az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password> \
    --generate-ssh-keys
```
注意

如果您是使用現有的服務主體搭配自訂祕密，請確定祕密不超過 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)，或從叢集存取金鑰保存庫中的金鑰或祕密，接著必須將這些資源的存取權委派給該服務主體。若要委派存取權，請將 Azure 角色型存取控制 (Azure RBAC) 角色指派給該服務主體。

重要

授與給與叢集相關聯之服務主體的權限，可能需要 60 分鐘的時間才能傳播。

Azure CLI
Azure PowerShell

使用 az role assignment create 命令建立角色指派。為 appId 參數提供該服務主體的 appID 值。指定角色指派的範圍，例如資源群組或虛擬網路資源。角色指派會決定服務主體在資源上擁有哪些權限以及範圍為何。

例如，若要指派服務主體權限以存取金鑰保存庫中的祕密，您可以使用下列命令：
```
az role assignment create \
    --assignee <appId> \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" \
    --role "Key Vault Secrets User"
```
注意

資源的 --scope 必須是完整的資源識別碼，例如 /subscriptions/<guid>/resourceGroups/myResourceGroup 或 /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet。

使用 New-AzRoleAssignment 命令建立角色指派。為 ApplicationId 參數提供該服務主體的 appID 值。指定角色指派的範圍，例如資源群組或虛擬網路資源。角色指派會決定服務主體在資源上擁有哪些權限以及範圍為何。

例如，若要指派服務主體權限以存取金鑰保存庫中的祕密，您可以使用下列命令：
```
New-AzRoleAssignment -ApplicationId <ApplicationId> `
    -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" `
    -RoleDefinitionName "Key Vault Secrets User"
```
注意

資源的 Scope 必須是完整的資源識別碼，例如 /subscriptions/<guid>/resourceGroups/myResourceGroup 或 /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet

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

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 \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query servicePrincipalProfile.clientId \
  --output 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" \
    --output 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>