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

發行項
11/19/2024

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

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

如需這項功能的概觀，請參閱已啟用 Azure Arc 的 Kubernetes 中的工作負載身分識別同盟（預覽版）。

重要

Azure Arc 工作負載身分識別同盟功能目前處於預覽狀態。請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

提示

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

必要條件

下列 Kubernetes 散發套件支援已啟用 Azure Arc 的 Kubernetes 叢集工作負載身分識別（預覽版）：
- 執行 K3s 的 Ubuntu Linux 叢集
- Edge Essentials 上的 AKS
- HCI 23H2 上的 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 connectk8s 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`	Microsoft要與 Pod 搭配使用的 Entra 應用程式用戶端識別碼。
`azure.workload.identity/tenant-id`	註冊Microsoft Entra 應用程式的 Azure 租用戶標識碼。	`AZURE_TENANT_ID` 從 `azure-wi-webhook-config` ConfigMap 擷取的環境變數。
`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`	Yes

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 知道要在哪裡尋找公鑰來驗證令牌）。

若要使用 K3 在 Ubuntu Linux 上設定工作負載身分識別設定，請遵循下列步驟來完成設定：

建立 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 伺服器。

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

停用工作負載身分識別

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

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

下一步

探索將應用程式設定為使用工作負載身分識別的範例。

共用方式為

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

必要條件

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

設定環境變數

擷取 OIDC 簽發者 URL

建立受控識別

建立 Kubernetes 服務帳戶

建立同盟身分識別認證

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

服務帳戶註釋

Pod 標籤

Pod 註釋

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

停用工作負載身分識別

下一步

意見反應

其他資源

共用方式為

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

必要條件

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

設定環境變數

擷取 OIDC 簽發者 URL

建立受控識別

建立 Kubernetes 服務帳戶

建立同盟身分識別認證

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

服務帳戶註釋

Pod 標籤

Pod 註釋

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

停用工作負載身分識別

下一步

意見反應

其他資源

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