Workload Identity 叢集驗證

Workload Identity 叢集驗證功能可讓您使用短期權杖和 Workload Identity Federation，為 Distributed Cloud 軟體 (僅限裸機) 建立及保護叢集。這種做法會以 OAuth 2.0 存取權杖取代永久服務帳戶金鑰，減少維護負擔，並消除長期憑證的安全風險。

這項功能只能在建立新叢集時啟用。這項功能適用於 1.33 以上版本，以及 1.30、1.31 和 1.32 的預先發布版。您無法更新現有叢集來使用這項功能。如要瞭解其他限制，請參閱「限制」一節。

Workload Identity 叢集驗證的運作方式

服務帳戶的短期憑證會以 OAuth 2.0 存取權杖的形式提供。存取權杖預設會在 1 小時後失效。同樣地，映像檔提取權杖預設也會在 1 小時後失效。

相較之下，金鑰模式是建立及保護叢集的標準方法，會使用下載的服務帳戶金鑰。建立自行管理的叢集 (管理員、混合式或獨立叢集) 時，請指定下載金鑰的路徑。接著，金鑰會以 Secret 的形式儲存在叢集和任何代管使用者叢集中。根據預設，服務帳戶金鑰不會過期，如果管理不當，可能會產生安全性風險。如要瞭解如何設定服務帳戶金鑰的到期時間，請參閱「使用者自行管理金鑰的到期時間」。

相較於使用服務帳戶金鑰，Workload Identity 叢集驗證有兩大優點：

  • 提升安全性：如未妥善管理服務帳戶金鑰，可能會產生安全性風險，OAuth 2.0 權杖和 Workload Identity Federation 是服務帳戶金鑰的最佳替代方案。如要進一步瞭解服務帳戶權杖，請參閱「短期服務帳戶憑證」。如要進一步瞭解 Workload Identity Federation，請參閱「 Workload Identity Federation」。

  • 減少維護工作：服務帳戶金鑰需要更多維護工作。定期輪替及保護這些金鑰，可能會造成重大的管理負擔。

事前準備

在下列各節中，您將建立服務帳戶，並授予 Workload Identity 叢集驗證所需的角色。本文件中的設定操作說明並非取代「設定 Google Cloud資源」中的操作說明，而是除了標準 Distributed Cloud 軟體專用安裝必要條件外，還需要完成的步驟。Workload Identity 叢集驗證所需的服務帳戶，與「設定Google Cloud 資源」一節所述的服務帳戶類似，但名稱不重複，因此不會干擾使用預設服務帳戶金鑰的叢集。

Workload Identity 叢集驗證所需的服務帳戶，會因預先發布版和正式發布版而異，如下表所示：

1.33 以上版本

服務帳戶 目的 角色
admin-sa 您可以使用這個服務帳戶產生權杖。每個權杖都具備與服務帳戶角色相關聯的權限。 roles/gkehub.admin
roles/iam.serviceAccountAdmin
roles/iam.serviceAccountTokenCreator
roles/iam.workloadIdentityPoolAdmin*
roles/logging.admin
roles/monitoring.admin
roles/resourcemanager.projectIamAdmin
baremetal-gcr Google Distributed Cloud 會使用這個服務帳戶，從 Artifact Registry 下載容器映像檔。 無

*只有 1.34 以上版本才需要 roles/iam.workloadIdentityPoolAdmin IAM 角色。

1.30-1.32

服務帳戶 目的 角色
admin-sa 您可以使用這個服務帳戶產生權杖。每個權杖都具備與服務帳戶角色相關聯的權限。 roles/gkehub.admin
roles/iam.serviceAccountAdmin
roles/iam.serviceAccountTokenCreator
roles/logging.admin
roles/monitoring.admin
baremetal-controller Connect 代理程式會使用這個服務帳戶，維持叢集與 Google Cloud 之間的連線，並向 機群註冊叢集。這個服務帳戶也會重新整理 baremetal-gcr 服務帳戶的權杖。 roles/gkehub.admin
roles/monitoring.dashboardEditor
roles/serviceusage.serviceUsageViewer
baremetal-cloud-ops Stackdriver 代理程式會使用這個服務帳戶，將叢集的記錄檔和指標匯出至 Cloud Logging 和 Cloud Monitoring。 roles/kubernetesmetadata.publisher
roles/logging.logWriter
roles/monitoring.dashboardEditor
roles/monitoring.metricWriter
roles/monitoring.viewer
roles/opsconfigmonitoring.resourceMetadata.writer
roles/serviceusage.serviceUsageViewer
roles/stackdriver.resourceMetadata.writer
baremetal-gcr Google Distributed Cloud 會使用這個服務帳戶，從 Artifact Registry 下載容器映像檔。 無

設定服務帳戶

下列各節說明如何建立必要的服務帳戶，並授予 Workload Identity 叢集驗證所需的角色。如需服務帳戶及其必要角色的清單，請參閱上一節的表格。

建立服務帳戶

如要建立 Workload Identity 叢集驗證的服務帳戶，請按照下列步驟操作：

  1. 在管理員工作站登入 Google Cloud CLI：

    gcloud auth login

  2. 建立 Workload Identity 叢集驗證所需的服務帳戶：

    admin-sa 服務帳戶名稱可任意指定。如果名稱在專案中造成衝突，您可以變更名稱。Workload Identity 叢集驗證的其他服務帳戶有名稱預設值，但您也可以自訂。

    1.33 以上版本

    gcloud iam service-accounts create admin-sa \
    --project=PROJECT_ID

gcloud iam service-accounts create baremetal-gcr \
    --project=PROJECT_ID

    將 PROJECT_ID 替換為Google Cloud 專案 ID。

    1.30-1.32

    ```sh gcloud iam service-accounts create admin-sa
    --project=PROJECT_ID

    gcloud iam service-accounts create baremetal-controller
    --project=PROJECT_ID

    gcloud iam service-accounts create baremetal-cloud-ops
    --project=PROJECT_ID

    gcloud iam service-accounts create baremetal-gcr
    --project=PROJECT_ID ```

    將 PROJECT_ID 替換為Google Cloud 專案 ID。

新增服務帳戶的身分與存取權管理政策繫結

請按照下列步驟，將必要的 Identity and Access Management 政策繫結套用至新的服務帳戶：

1.33 以上版本

  1. 為 admin-sa 服務帳戶新增必要角色的 IAM 政策繫結：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/gkehub.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountAdmin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/logging.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/resourcemanager.projectIamAdmin

1.30-1.32

  1. 為 admin-sa 服務帳戶新增必要角色的 IAM 政策繫結：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/gkehub.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountAdmin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/logging.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.admin

  2. 為 baremetal-controller 服務帳戶新增必要角色的 IAM 政策繫結：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/gkehub.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.dashboardEditor

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageViewer

  3. 為 baremetal-cloud-ops 服務帳戶新增必要角色的 IAM 政策繫結：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/kubernetesmetadata.publisher

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.dashboardEditor

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.metricWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/opsconfigmonitoring.resourceMetadata.writer

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageViewer

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/stackdriver.resourceMetadata.writer

  4. 授予 baremetal-controller 服務帳戶代表 baremetal-gcr 服務帳戶產生存取權杖的能力：

    gcloud iam service-accounts add-iam-policy-binding \
    baremetal-gcr@PROJECT_ID.iam.gserviceaccount.com \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

設定驗證方法

下列步驟會設定驗證流程，使用短期權杖驗證叢集作業：

  1. 在管理員工作站登入 Google Cloud CLI：

    gcloud auth login

  2. 在管理員工作站上，建立並下載 admin-sa 服務帳戶的金鑰：

    您需要這組金鑰，才能授權存取 admin-sa 服務帳戶。

    gcloud iam service-accounts keys create TMP_KEY_FILE_PATH \
    --iam-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com

    將 TMP_KEY_FILE_PATH 替換為下載金鑰檔案的路徑，包括檔案名稱。

  3. 在管理員工作站上，建立 GOOGLE_APPLICATION_CREDENTIALS 環境變數，並將值設為下載的服務帳戶金鑰：

    export GOOGLE_APPLICATION_CREDENTIALS=TMP_KEY_FILE_PATH

  4. 在管理員工作站上，建立 GCP_ACCESS_TOKEN 環境變數，並將值設為 admin-sa 服務帳戶建立的存取權杖：

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    根據預設，存取權杖的生命週期為 1 小時。

  5. 確認權杖是由 admin-sa 服務帳戶產生，且到期時間正確：

    curl "https://oauth2.googleapis.com/tokeninfo?access_token=$GCP_ACCESS_TOKEN"

    回應應包含類似下列內容的行：

    ...
"exp": "1759512810",
"expires_in": "3589",
...

    到期值以秒為單位，應小於 3600，表示權杖會在不到一小時內到期。

設定叢集的 Workload Identity Federation

如要透過 GKE 適用的 Workload Identity 聯盟提供 Google Cloud 存取權，請建立 IAM 允許政策，將特定Google Cloud 資源的存取權授予與應用程式身分對應的主體。在這種情況下，Workload Identity Federation 會將存取權授予叢集中的特定運算子。如要進一步瞭解 Workload Identity Federation for GKE，請參閱 IAM 說明文件中的「Workload Identity Federation」。

1.33 以上版本

如果叢集版本的 Workload Identity 叢集驗證功能已正式發布，請使用 bmctl configure projects 指令，為叢集設定 Workload Identity Federation。建立管理員叢集和建立使用者叢集的步驟中，已包含這個指令。

使用登錄檔鏡像為叢集提取容器映像檔時，為避免 containerd 不穩定，您必須新增 baremetal.cluster.gke.io/enable-gcr-image-credential-refresh: "false" 叢集註解。這個註解適用於 1.33.200-gke.70 以上版本：

---
...
registryMirrors:
  - endpoint: https://198.51.20.1:5000
    caCertPath: /root/ca.crt
    pullCredentialConfigPath: /root/.docker/config.json
    hosts:
      - somehost.io
      - otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: admin1
  namespace: cluster-admin1
  annotations:
    baremetal.cluster.gke.io/enable-gcr-image-credential-refresh: "false"
spec:
  type: admin
  anthosBareMetalVersion: 1.33.200-gke.70
  ...

1.30-1.32

如果叢集版本的 Workload Identity 叢集驗證功能處於預先發布版，您必須按照下列各節所述，手動為叢集設定 Workload Identity Federation。

為叢集運算子新增 IAM 政策繫結

下列指令會授予 anthos-cluster-operator Kubernetes 服務帳戶模擬 baremetal-controller 服務帳戶的能力，並代表叢集與 Google Cloud 資源互動：

  1. 針對已設定 Workload Identity 叢集驗證 (或計劃使用 Workload Identity 叢集驗證) 的每個叢集 (包括 bootstrap 叢集)，授予叢集中的 anthos-cluster-operator 模擬 baremetal-controller 服務帳戶的能力：

    在下列指令中，principalSet 由 workload identity pool 和 kube-system 命名空間中的 Kubernetes 服務帳戶 anthos-cluster-operator 組成。

    gcloud iam service-accounts add-iam-policy-binding \
    baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/anthos-cluster-operator \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

    更改下列內容：

    • PROJECT_NUM：系統自動產生的專案專屬 ID。

    • REGION：叢集的機群成員資格位置，預設為 global。詳情請參閱「機群成員資格位置」。

    • CLUSTER_NAME：叢集名稱。根據預設，啟動叢集名稱為 bmctl-MACHINE_NAME。

  2. 驗證 baremetal-controller 服務帳戶的政策繫結：

    gcloud iam service-accounts get-iam-policy \
    baremetal-controller@PROJECT_ID.iam.gserviceaccount.com

    回應內容應與下方類似：

    bindings:
- members:
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/anthos-cluster-operator
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/anthos-cluster-operator
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/anthos-cluster-operator
  role: roles/iam.workloadIdentityUser
etag: BwYoN3QLig0=
version: 1

為 Google Cloud Observability 運算子新增 IAM 政策繫結

下列指令會授予下列 Google Cloud Observability Kubernetes 服務帳戶模擬baremetal-cloud-ops服務帳戶的能力，並代表叢集與 Google Cloud 資源互動：

  • cloud-audit-logging
  • gke-metrics-agent
  • kubestore-collector
  • metadata-agent
  • stackdriver-log-forwarder

  1. 針對每個已設定或預計使用 Workload Identity 叢集驗證功能的叢集 (包括 bootstrap 叢集)，授予叢集中的 Google Cloud Observability 運算子模擬 baremetal-cloud-ops 服務帳戶的能力：

    在下列各指令中，principalSet 是由 workload identity pool 和 Kubernetes 服務帳戶 (例如 kube-system 命名空間中的 cloud-audit-logging) 組成。

    gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/cloud-audit-logging \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/gke-metrics-agent \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/kubestore-collector \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/metadata-agent \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/stackdriver-log-forwarder \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

  2. 驗證 baremetal-cloud-ops 服務帳戶的政策繫結：

    gcloud iam service-accounts get-iam-policy \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com

    回應內容應與下方類似：

    bindings:
- members:
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/cloud-audit-logging
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/gke-metrics-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/kubestore-collector
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/metadata-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/stackdriver-log-forwarder
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/cloud-audit-logging
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/gke-metrics-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/kubestore-collector
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/metadata-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/stackdriver-log-forwarder
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/cloud-audit-logging
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/gke-metrics-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/kubestore-collector
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/metadata-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/stackdriver-log-forwarder
  role: roles/iam.workloadIdentityUser
etag: BwYhT4gL-dY=
version: 1

建立管理員叢集

建立管理員叢集的步驟會因預先發布版 (1.30-1.32 版) 和正式發布版 (1.33 以上版本) 而略有不同。正式發布版步驟會使用 bmctl configure projects 指令，為叢集設定 Workload Identity Federation。

1.33 以上版本

對於使用 Workload Identity 叢集驗證的叢集，最明顯的叢集設定差異在於您不必指定下載的服務帳戶金鑰路徑。

  1. 在設定檔中填寫叢集設定時，請將憑證部分的服務帳戶金鑰路徑留空，如下例所示：

    gcrKeyPath:
sshPrivateKeyPath: /home/USERNAME/.ssh/id_rsa
gkeConnectAgentServiceAccountKeyPath:
gkeConnectRegisterServiceAccountKeyPath:
cloudOperationsServiceAccountKeyPath:
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-ADMIN_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: ADMIN_CLUSTER_NAME
  namespace: cluster-ADMIN_CLUSTER_NAME
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

  2. 將 baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true" 註解新增至叢集設定檔：

    gcrKeyPath:
sshPrivateKeyPath: /home/USERNAME/.ssh/id_rsa
gkeConnectAgentServiceAccountKeyPath:
gkeConnectRegisterServiceAccountKeyPath:
cloudOperationsServiceAccountKeyPath:
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-ADMIN_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: ADMIN_CLUSTER_NAME
  namespace: cluster-ADMIN_CLUSTER_NAME
  annotations:
    baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

  3. 在管理員工作站上，使用新擷取的存取權杖更新 GCP_ACCESS_TOKEN 環境變數：

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    根據預設，存取權杖的生命週期為 3600 秒 (1 小時)。使用 Workload Identity 叢集驗證時，bmctl 會檢查權杖到期時間。如果權杖在 1800 秒 (30 分鐘) 內到期，bmctl 會回報錯誤並結束。

  4. 為要建立的叢集設定 Workload Identity Federation：

    bmctl configure projects --project-id=PROJECT_ID \
    --admin-cluster=ADMIN_CLUSTER_NAME

  5. 執行 bmctl create cluster 指令，建立管理員叢集。

1.30-1.32

對於使用 Workload Identity 叢集驗證的叢集，最明顯的叢集設定差異在於，您不必指定下載的服務帳戶金鑰路徑。

  1. 在設定檔中填寫叢集設定時，請將憑證部分的服務帳戶金鑰路徑留空，如下例所示：

    gcrKeyPath:
sshPrivateKeyPath: /home/USERNAME/.ssh/id_rsa
gkeConnectAgentServiceAccountKeyPath:
gkeConnectRegisterServiceAccountKeyPath:
cloudOperationsServiceAccountKeyPath:
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-ADMIN_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: ADMIN_CLUSTER_NAME
  namespace: cluster-ADMIN_CLUSTER_NAME
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

  2. 在管理員工作站上，建立並下載 admin-sa 服務帳戶的金鑰：

    這組金鑰用於授權 admin-sa 服務帳戶的存取權，您會在服務帳戶獲得授權後立即刪除金鑰。

    gcloud iam service-accounts keys create TMP_KEY_FILE_PATH \
    --iam-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com

    將 TMP_KEY_FILE_PATH 替換為下載金鑰檔案的路徑，包括檔案名稱。

  3. 使用 admin-sa 服務帳戶授權存取 Google Cloud ：

    gcloud auth activate-service-account admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --key-file=TMP_KEY_FILE_PATH

  4. 刪除下載的 JSON 金鑰檔案：

    rm TMP_KEY_FILE_PATH

    存取權杖的效期很短，因此在執行 bmctl 指令來執行叢集作業 (例如建立、升級或重設叢集) 之前，通常需要重新產生權杖。

  5. 在管理員工作站上，建立 GCP_ACCESS_TOKEN 環境變數，並將值設為 admin-sa 服務帳戶建立的存取權杖：

    export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com)

    根據預設，存取權杖的生命週期為 3600 秒 (1 小時)。

  6. 執行 bmctl create cluster 指令，建立管理員叢集。

建立使用者叢集

建立管理員叢集的步驟會因預先發布版 (1.30-1.32 版) 和正式發布版 (1.33 以上版本) 而略有不同。正式發布版步驟會使用 bmctl configure projects 指令，為叢集設定 Workload Identity Federation。

1.33 以上版本

  1. 將 baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true" 註解新增至叢集設定檔：

    apiVersion: v1
kind: Namespace
metadata:
  name: cluster-USER_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: USER_CLUSTER_NAME
  namespace: cluster-USER_CLUSTER_NAME
  annotations:
    baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

    存取權杖的效期很短，因此您通常需要重新產生權杖，才能執行 bmctl 指令來執行叢集作業，例如建立、升級或重設叢集。

  2. 在管理員工作站上，使用新擷取的存取權杖更新 GCP_ACCESS_TOKEN 環境變數：

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    根據預設，存取權杖的生命週期為 3600 秒 (1 小時)。

  3. 為要建立的叢集設定 Workload Identity Federation：

    bmctl configure projects --project-id=PROJECT_ID \
    --user-clusters=USER_CLUSTER_NAME

  4. 使用 kubectl 部署使用者叢集資訊清單：

    kubectl apply -f USER_CLUSTER_CONFIG \
    --kubeconfig ADMIN_KUBECONFIG

更改下列內容：

  • USER_CLUSTER_CONFIG：使用者叢集設定檔的路徑。

  • ADMIN_KUBECONFIG：管理員叢集的 kubeconfig 檔案路徑。

1.30-1.32

  1. 在管理員工作站上，建立並下載 admin-sa 服務帳戶的金鑰：

    這組金鑰用於授權 admin-sa 服務帳戶的存取權，您會在服務帳戶獲得授權後立即刪除金鑰。

    gcloud iam service-accounts keys create TMP_KEY_FILE_PATH \
    --iam-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com

    將 TMP_KEY_FILE_PATH 替換為下載金鑰檔案的路徑，包括檔案名稱。

  2. 使用 admin-sa 服務帳戶授權存取 Google Cloud ：

    gcloud auth activate-service-account admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --key-file=TMP_KEY_FILE_PATH

  3. 刪除下載的 JSON 金鑰檔案：

    rm TMP_KEY_FILE_PATH

    存取權杖的效期很短，因此在執行 bmctl 指令來執行叢集作業 (例如建立、升級或重設叢集) 之前，通常需要重新產生權杖。

  4. 在管理員工作站上，建立 GCP_ACCESS_TOKEN 環境變數，並將值設為 admin-sa 服務帳戶建立的存取權杖：

    export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com)

    根據預設，存取權杖的生命週期為 3600 秒 (1 小時)。

  5. 執行 bmctl create cluster 指令，建立使用者叢集。

其他叢集作業

如果叢集使用 Workload Identity 叢集驗證，下列 bmctl 指令會要求您將 GCP_ACCESS_TOKEN 環境變數設為有效、有效的存取權杖：

  • bmctl configure projects
  • bmctl create cluster
  • bmctl register bootstrap
  • bmctl reset cluster
  • bmctl upgrade cluster

bmctl register bootstrap 支援使用 GCP_ACCESS_TOKEN 環境變數，為 Workload Identity 叢集驗證，但僅限 Google Distributed Cloud 1.34.0 以上版本。如果是 1.34.0 之前的版本，您必須使用服務帳戶金鑰檔案來驗證 bmctl register bootstrap。

如果 bmctl 偵測到 GCP_ACCESS_TOKEN 環境變數已設定，就會執行權杖驗證：

  • 如果權杖有效，bmctl 會使用權杖執行叢集作業。

  • 如果權杖無效，請擷取新的權杖：

    存取權杖的效期很短，因此您通常需要重新產生權杖，才能執行 bmctl 指令來執行叢集作業，例如建立、升級或重設叢集。在管理員工作站上，使用新擷取的存取權杖更新 GCP_ACCESS_TOKEN 環境變數：

    1.33 以上版本

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    1.30-1.32

    sh export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token \ --impersonate-service-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com)

    根據預設，存取權杖的生命週期為 3600 秒 (1 小時)。使用 Workload Identity 叢集驗證時，bmctl 會檢查權杖到期時間。如果權杖在 1800 秒 (30 分鐘) 內到期，bmctl 會回報錯誤並結束。

自訂

只要服務帳戶繫結了必要角色，您就能使用名稱不重複的服務帳戶，進行 Workload Identity 叢集驗證。

1.33 以上版本

根據預設，1.33 以上版本的叢集會使用 Workload Identity 叢集驗證，且僅使用 baremetal-gcr 服務帳戶。因此，只有這個服務帳戶可以自訂。

  1. 確認您要使用的服務帳戶具備「事前準備」表格中列出的角色。

  2. 為叢集設定檔加上註解，指定 Workload Identity 叢集驗證服務帳戶的自訂名稱：

    apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: my-cluster
  namespace: cluster-my-cluster
  annotations:
    ...
    baremetal.cluster.gke.io/gcr-service-account: "CUSTOM_AR_GSA"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

將 CUSTOM_AR_GSA 替換為 Google Distributed Cloud 用來從 Artifact Registry 下載容器映像檔的服務帳戶電子郵件名稱。

1.30-1.32

  1. 確認您要使用的服務帳戶具備「事前準備」表格中列出的角色。

  2. 為叢集設定檔加上註解，指定 Workload Identity 叢集驗證服務帳戶的自訂名稱：

    指定自訂名稱後，即可使用現有的服務帳戶。請務必指定不同的自訂服務帳戶名稱。我們不支援使用單一服務帳戶取代兩個以上的預設服務帳戶。

    apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: my-cluster
  namespace: cluster-my-cluster
  annotations:
    ...
    baremetal.cluster.gke.io/controller-service-account: "CUSTOM_CONTROLLER_GSA"
    baremetal.cluster.gke.io/cloud-ops-service-account: "CUSTOM_CLOUD_OPS_GSA"
    baremetal.cluster.gke.io/gcr-service-account: "CUSTOM_AR_GSA"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.30.0-gke.1930
  ...

更改下列內容：

  • CUSTOM_CONTROLLER_GSA：Connect 代理程式使用的服務帳戶電子郵件名稱，用於維持叢集與 Google Cloud之間的連線，以及註冊叢集。

  • CUSTOM_CLOUD_OPS_GSA：Stackdriver 代理程式使用的服務帳戶電子郵件名稱，用於將叢集的記錄和指標匯出至 Cloud Logging 和 Cloud Monitoring。

  • CUSTOM_AR_GSA：Google Distributed Cloud 用來從 Artifact Registry 下載容器映像檔的服務帳戶電子郵件名稱。

限制

如果僅針對裸機使用 Distributed Cloud 軟體的 Workload Identity 叢集驗證，則不支援下列功能：

  • 使用 Proxy 伺服器
  • VPC Service Controls
  • 更新現有的金鑰模式叢集，改用 Workload Identity 叢集驗證
  • 使用 GKE On-Prem API 用戶端 (例如 Google Cloud CLI、Terraform 或 Google Cloud 控制台) 管理叢集生命週期

後續步驟