在已啟用 Azure Arc 的 Kubernetes 中部署和設定工作負載身分識別同盟

您可以使用 Azure CLI，在已啟用 Azure Arc 的 Kubernetes 叢集上啟用工作負載身分識別功能。此流程會遵循下列高階步驟進行：

在新的或現有已啟用 Arc 的 Kubernetes 叢集上啟用工作負載身分識別功能。
建立受控識別 (或應用程式註冊) 和 Kubernetes 服務帳戶。
設定權杖同盟的受控識別。
設定服務帳戶批註和應用程式 Pod 標籤以使用工作負載身分識別。
在 Kubernetes 叢集上設定工作負載身分識別設定。
停用叢集上的工作負載身分識別。

關於此功能的概述，請參閱 Azure Arc 啟用的 Kubernetes 中的工作負載身份聯合。

提示

本文說明在已啟用 Arc 的 Kubernetes 叢集上部署和設定工作負載身分識別所需的步驟。若要了解如何在其他類型的叢集上啟用工作負載身分識別，請參閱下列文章：

先決條件

以下 Kubernetes 發行版本支援 Azure Arc 啟用的 Kubernetes 叢集工作負載身份識別：
- 執行 K3s 的 Ubuntu Linux 叢集
- AKS 由 Azure Arc 啟用
- Red Hat OpenShift
- VMware Tanzu TKGm
- 邊緣程式集上的 AKS

若要使用工作負載身分識別功能，您必須擁有 Azure CLI 2.64 版或更新版本，以及 az connectedk8s 1.10.0 版或更高版本。更新您的 az connectedk8s 版本之前，請務必先更新您的 Azure CLI 版本。如果您使用 Azure Cloud Shell，將會安裝最新版的 Azure CLI。

在您的叢集上啟用工作負載身分識別

請遵循適當的步驟，為新的已啟用 Arc 的 Kubernetes 叢集或現有叢集啟用工作負載身分識別功能。在這兩種情況下，請務必以您的值取代名稱和資源群組，並視需要設定參數。

參數	描述	必要
`--enable-oidc-issuer`	產生並裝載 OIDC 簽發者 URL，這是可公開存取的 URL，可讓 API 伺服器尋找用於驗證權杖的公開簽署金鑰。	必要
`--enable-workload-identity`	安裝變動許可 Webhook，其會將已簽署的服務帳戶權杖投影到已知的路徑，並根據標註的服務帳戶設定，將驗證相關的環境變數插入應用程式 Pod。針對新的叢集，如果未啟用此參數，您必須在已知路徑上掛接投影的磁碟區，以將已簽署的服務帳戶權杖公開至路徑。	選用

設定環境變數

為了方便起見，本文範例會參考以下定義的環境變數。以您自己的值取代這些值：

export RESOURCE_GROUP="myRG"
export LOCATION="eastus"
export CLUSTER_NAME="mycluster"
export SERVICE_ACCOUNT_NAMESPACE="myKubernetesnamespace"
export SERVICE_ACCOUNT_NAME="mysa"
export SUBSCRIPTION="$(az account show --query id --output tsv)"
export USER_ASSIGNED_IDENTITY_NAME="myIdentity"
export FEDERATED_IDENTITY_CREDENTIAL_NAME="myFedIdentity"

若要建立已啟用工作負載身分識別的已啟用 Azure Arc 叢集，請使用下列命令：

az connectedk8s connect --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" --enable-oidc-issuer –-enable-workload-identity

若要在現有已啟用 Arc 的 Kubernetes 叢集上啟用工作負載身分識別，請使用 update 命令。

az connectedk8s update --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" --enable-oidc-issuer --enable-workload-identity

擷取 OIDC 簽發者 URL

擷取 OIDC 簽發者 URL，並將其儲存至環境變數。這個簽發者 URL 將會用於下列步驟。

export OIDC_ISSUER="$(az connectedk8s show --name "${CLUSTER_NAME}" --resource-group "${RESOURCE_GROUP}" \ 
    --query "oidcIssuerProfile.issuerUrl" \  
    --output tsv)"

若要檢視環境變數，請輸入 echo ${OIDC_ISSUER}。環境變數應包含與下列範例類似的簽發者 URL：

https://northamerica.oic.prod-arc.azure.com/00000000-0000-0000-0000-000000000000/12345678-1234-1234-1234-123456789123/

根據預設，簽發者會設定為使用基底 URL https://{region}.oic.prod-arc.azure.com/{tenant_id}/{uuid}，其中 {region} 的值會符合已啟用 Arc 的 Kubernetes 叢集建立位置。值 {uuid} 代表 OpenID Connect (OIDC) 索引鍵，這是每個叢集不可變、隨機產生的 GUID。

建立受控識別

使用 az identity create 命令建立使用者指派的受控識別。使用工作負載身分識別時，會在使用者指派的管理身分識別的權杖與 Kubernetes 叢集的服務帳戶權杖之間建立信任關係。

az identity create \ 
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --subscription "${SUBSCRIPTION}"

擷取受控識別的用戶端識別碼，並儲存在環境變數中。

export USER_ASSIGNED_CLIENT_ID="$(az identity show \ 
    --resource-group "${RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'clientId' \
    --output tsv)"

建立 Kubernetes 服務帳戶

建立 Kubernetes 服務帳戶，並使用在上一個步驟中建立之受控識別的用戶端識別碼加以標註。與 Kubernetes 服務帳戶相關聯的已簽署權杖，將會交換為 Microsoft Entra ID 權杖，在兩者之間建立信任關係之後。

套用下列 YAML 程式碼片段，以建立已新增工作負載身分識別批註的服務帳戶。

apiVersion: v1 
kind: ServiceAccount 
metadata: 
  annotations: 
    azure.workload.identity/client-id: "${USER_ASSIGNED_CLIENT_ID}" 
  name: "${SERVICE_ACCOUNT_NAME}" 
  namespace: "${SERVICE_ACCOUNT_NAMESPACE}"

建立同盟身分識別認證

使用 az identity federated-credential create 命令，在受控識別、服務帳戶簽發者和主體之間建立同盟身分識別認證。此步驟會建立 Kubernetes 叢集與 Microsoft Entra 之間的信任關係，以交換權杖。如需 Microsoft Entra 中同盟身分識別認證的詳細資訊，請參閱 Microsoft Entra ID 中的同盟身分識別認證概觀。

az identity federated-credential create \ 
    --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} \ 
    --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \ 
    --resource-group "${RESOURCE_GROUP}" \ 
    --issuer "${OIDC_ISSUER}" \ 
    --subject system:serviceaccount:"${SERVICE_ACCOUNT_NAMESPACE}":"${SERVICE_ACCOUNT_NAME}" \ 
    --audience api://AzureADTokenExchange

附註

新增同盟身分識別認證之後，需要幾秒鐘的時間才能散佈。如果在新增同盟身分識別認證後立即提出權杖要求，在重新整理快取之前，要求可能會失敗。若要避免此問題，請在新增同盟身分識別認證之後，在指令碼中新增稍微延遲。

設定服務帳戶批註和 Pod 標籤

下列服務帳戶和 Pod 批注可用來根據應用程式需求來設定工作負載身分識別。如果 –-enable-workload-identity 設定為 true，則下列指定的 Pod 標籤是強制性的。

服務帳戶批註

所有服務帳戶批註都是選擇性的。如果未指定批註，則會使用預設值。

批註	描述	預設
`azure.workload.identity/client-id`	要與 Pod 搭配使用的 Microsoft Entra 應用程式用戶端識別碼。
`azure.workload.identity/tenant-id`	註冊 Microsoft Entra 應用程式的 Azure 租用戶識別碼。	從 `AZURE_TENANT_ID` ConfigMap 擷取的 `azure-wi-webhook-config` 環境變數。
`azure.workload.identity/service-account-token-expiration`	投影服務帳戶權杖的 `expirationSeconds` 欄位。設定以防止服務帳戶權杖重新整理期間發生錯誤造成的停機時間。 Kubernetes 服務帳戶權杖到期與 Microsoft Entra 權杖無關。 Microsoft Entra 權杖在發行後 24 小時到期。	3600 (支援的範圍是 3600-86400)

Pod 標籤

批註	描述	建議值	必要
`azure.workload.identity/use`	Pod 範本規格中的必要項目。如果 `–-enable-workload-identity` 設定為 `true`，則只有具有此標籤的 Pod 會由變動許可 Webhook 來變動，以插入 Azure 特定的環境變數和投影的服務帳戶權杖磁碟區。	`true`	是的

Pod 批註

所有 Pod 批註都是選擇性的。如果未指定批註，則會使用預設值。

批註	描述	預設
`azure.workload.identity/service-account-token-expiration`	投影服務帳戶權杖的 `expirationSeconds` 欄位。設定以防止服務帳戶權杖重新整理期間發生錯誤造成的停機時間。 Kubernetes 服務帳戶權杖到期與 Microsoft Entra 權杖無關。 Microsoft Entra 權杖在發行後 24 小時到期。	3600 (支援的範圍是 3600-86400)
`azure.workload.identity/skip-containers`	分號分隔清單表示要略過新增投影服務帳戶權杖磁碟區的容器。例如：`container1;container2`。	根據預設，如果 Pod 標記為 `azure.workload.identity/use: true`，則會將投影服務帳戶權杖磁碟區新增至所有容器。

在 Kubernetes 叢集上設定工作負載身分識別設定

Kubernetes 叢集上的 API 伺服器必須設定為發出服務帳戶權杖，其中包含可公開存取的 OIDC 簽發者 URL (讓 Entra 知道要在哪裡尋找公開金鑰來驗證權杖)。

要在各種 Kubernetes 發行版上設定工作負載身份設定，請依照以下步驟完成設定。

K3s 叢集

建立你的 k3s 設定檔。

編輯 /etc/rancher/k3s/config.yaml 以新增這些設定：

   `kube-apiserver-arg:  
     - 'service-account-issuer=${OIDC_ISSUER}'
     - 'service-account-max-token-expiration=24h'`

儲存 config.yaml。
使用 systemctl restart k3s 命令重新啟動 k3s API 伺服器。

我們建議經常輪替服務帳戶金鑰。如需詳細資訊，請參閱服務帳戶簽發者金鑰輪替。

Red Hat OpenShift 叢集

編輯叢集的認證設定：
1. 開啟叢集的認證設定：
```
kubectl edit authentications cluster
```
2. 找到發行人價值的區塊並更新。
3. 儲存檔案並結束編輯器。

在所需的命名空間中重新啟動相關部署：

kubectl rollout restart deployment -n azure-arc
kubectl rollout restart deployment -n arc-workload-identity

或者，透過補丁指令套用變更，無需手動編輯即可更新發行者值：

kubectl patch authentication cluster \ 
--type merge \ 
-p '{"spec":{"serviceAccountIssuer":"<NEW_ISSUER_VALUE>"}}' \ 
--kubeconfig /etc/kubernetes/admin.conf

確認您的變更：

確認發行人價值：
```
kubectl get authentications cluster
```

請檢查重新啟動部署的狀態：

kubectl get pods -n azure-arc
kubectl get pods -n arc-workload-identity

VMware Tanzu TKGm 叢集

將你的叢集連接到 Azure Arc 以啟用工作負載識別。
1. 在 Arc 連線過程中啟用工作負載識別。
2. 連線後，取得 OIDC 發行者的 URL。
編輯工作負載叢集配置：
1. 切換到管理叢集：
```
kubectl config use-context mgmt-cluster-admin@mgmt-cluster 
```
2. 查看該群組：
```
kubectl get cluster
```
3. 編輯目標叢集配置：
  1. 搜尋 apiServerExtraArgs
  2. 如果有該值，請更新以包含發行者的網址。
  3. 如果不存在，請依照圖示的方式，在spec:topology:variables下面新增。
```
name: apiServerExtraArgs
value:
  - 'service-account-issuer=<OIDC_ISSUER_URL>'
```

將內容切換回工作負載叢集：

kubectl config use-context <WORKLOAD_CLUSTER_CONTEXT>

建立服務帳號並測試令牌：
1. 為服務帳號建立一個代幣：
```
kubectl create token <SERVICE_ACCOUNT_NAME> -n <NAMESPACE>
```
2. 確認憑證發行者是否與預期的 OIDC URL 相符。

重新啟動部署以套用您的變更：

kubectl rollout restart deployment -n azure-arc

停用工作負載身分識別

若要在已啟用 Azure Arc 的 Kubernetes 叢集上停用工作負載身分識別功能，請執行下列命令：

az connectedk8s update
    --resource-group "${RESOURCE_GROUP}"
    --name "${CLUSTER_NAME}"
    --disable-workload-identity

後續步驟

探索將應用程式設定為使用工作負載身分識別的範例。
遵循已啟用 Azure Arc 的 Kubernetes 安全性手冊中的指引，協助以其他方式保護您的叢集。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19