Workload Identity クラスタ認証

このドキュメントでは、ベアメタル上の Google Distributed Cloud（ソフトウェアのみ）で Workload Identity クラスタ認証を設定して使用する方法について説明します。Workload Identity クラスタ認証では、サービス アカウント キーの代わりに有効期間の短いトークンと Workload Identity 連携を使用してクラスタを作成し、保護します。サービス アカウントの有効期間の短い認証情報は、OAuth 2.0 アクセス トークン形式になっています。デフォルトでは、アクセス トークンは 1 時間後に期限切れになります。同様に、イメージプル トークンもデフォルトでは 1 時間後に期限切れになります。

一方、クラスタの作成と保護の標準方法であるキーモードでは、ダウンロードされたサービス アカウント キーが使用されます。セルフマネージド（管理、ハイブリッド、スタンドアロン）クラスタを作成する場合は、ダウンロードしたキーのパスを指定します。キーは、クラスタとマネージド ユーザー クラスタに Secret として保存されます。デフォルトでは、サービス アカウント キーに有効期限はなく、正しく管理しないとセキュリティ上のリスクになります。サービス アカウント キーの有効期限の設定については、ユーザーが管理する鍵の有効期限をご覧ください。

Workload Identity クラスタ認証には、サービス アカウント キーを使用する場合と比べて主に次の 2 つのメリットがあります。

  • セキュリティの強化: サービス アカウント キーは、正しく管理されていないとセキュリティ リスクになります。OAuth 2.0 トークンと Workload Identity 連携は、サービス アカウント キーのベスト プラクティスの代替手段と見なされます。サービス アカウント トークンの詳細については、有効期間の短いサービス アカウント認証情報をご覧ください。Workload Identity 連携の詳細については、Workload Identity 連携をご覧ください。

  • メンテナンスの削減: サービス アカウント キーは、より多くのメンテナンスが必要です。これらのキーを定期的にローテーションして保護することは、管理するうえで非常に負担がかかります。

Workload Identity クラスタ認証は、リリース 1.30 でプレビュー版として導入され、リリース 1.33 以降で一般提供されています。Workload Identity クラスタ認証は、新しいクラスタを作成するときにのみ有効にできます。既存のクラスタの更新時またはアップグレード時に Workload Identity クラスタ認証を使用するように構成することはできません。その他の制限事項については、制限事項をご覧ください。

このページは、基盤となる技術インフラストラクチャのライフサイクルの設定、モニタリング、管理を行う管理者、アーキテクト、オペレーターを対象としています。Google Cloud のコンテンツで参照する一般的なロールとタスク例の詳細については、一般的な GKE ユーザー ロールとタスクをご覧ください。

始める前に

以降のセクションでは、サービス アカウントを作成し、Workload Identity クラスタ認証に必要なロールを付与します。このドキュメントの設定手順は、 Google Cloudリソースを設定するの手順に代わるものではなく、標準の Google Distributed Cloud ソフトウェアのみのインストールの前提条件に加えて必要となります。Workload Identity クラスタ認証に必要なサービス アカウントは、Google Cloud リソースを設定するで説明されているサービス アカウントに似ていますが、一意の名前が付けられているため、デフォルトのサービス アカウント キーを使用するクラスタと競合しません。

Workload Identity クラスタ認証に必要なサービス アカウントは、次の表に示すように、プレビュー版と一般提供版で異なります。

1.33 以降

サービス アカウント 目的 ロール
admin-sa このサービス アカウントを使用してトークンを生成します。各トークンには、サービス アカウントのロールに関連付けられた権限があります。 roles/gkehub.admin
roles/iam.serviceAccountAdmin
roles/iam.serviceAccountTokenCreator
roles/logging.admin
roles/monitoring.admin
roles/resourcemanager.projectIamAdmin
baremetal-gcr Google Distributed Cloud は、このサービス アカウントを使用して Artifact Registry からコンテナ イメージをダウンロードします。 なし

1.30 ～ 1.32

サービス アカウント 目的 ロール
admin-sa このサービス アカウントを使用してトークンを生成します。各トークンには、サービス アカウントのロールに関連付けられた権限があります。 roles/gkehub.admin
roles/iam.serviceAccountAdmin
roles/iam.serviceAccountTokenCreator
roles/logging.admin
roles/monitoring.admin
baremetal-controller Connect Agent は、このサービス アカウントを使用して、クラスタと Google Cloud 間の接続を維持し、 フリートにクラスタを登録します。このサービス アカウントは、baremetal-gcr サービス アカウントのトークンも更新します。 roles/gkehub.admin
roles/monitoring.dashboardEditor
roles/serviceusage.serviceUsageViewer
baremetal-cloud-ops Stackdriver Agent は、このサービス アカウントを使用して、クラスタから 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

    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 ポリシー バインディングを追加する

次の手順に沿って、必要な 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. 管理ワークステーションで、admin-sa サービス アカウントによって作成されたアクセス トークンの値を使用して GCP_ACCESS_TOKEN 環境変数を作成します。

    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 未満にする必要があります。これは、トークンが 1 時間未満で期限切れになることを示します。

クラスタの Workload Identity 連携を構成する

Workload Identity Federation for GKE を使用して Google Cloud のアクセス権を付与するには、アプリケーションの ID に対応するプリンシパルに特定のGoogle Cloud リソースに対するアクセス権を付与する IAM 許可ポリシーを作成します。この場合、Workload Identity 連携はクラスタ内の特定のオペレーターにアクセス権を付与します。Workload Identity Federation for GKE の詳細については、IAM ドキュメントの Workload Identity 連携をご覧ください。

1.33 以降

Workload Identity クラスタ認証が一般提供されているクラスタ バージョンでは、bmctl configure projects コマンドを使用してクラスタの Workload Identity 連携を構成します。このコマンドは、管理クラスタの作成とユーザー クラスタの作成の手順に組み込まれています。

1.30 ～ 1.32

Workload Identity クラスタ認証がプレビュー版であるクラスタ バージョンの場合は、次のセクションで説明するように、クラスタの Workload Identity 連携を手動で構成する必要があります。

クラスタ オペレーターの IAM ポリシー バインディングを追加する

次のコマンドは、anthos-cluster-operator Kubernetes サービス アカウントに、baremetal-controller サービス アカウントの権限を借用する権限と、クラスタに代わって Google Cloud リソースの操作を行う権限を付与します。

  1. Workload Identity クラスタ認証用に構成されているクラスタ（または Workload Identity クラスタ認証を使用する予定のクラスタ）ごとに（ブートストラップ クラスタを含む）、クラスタ内の anthos-cluster-operator に baremetal-controller サービス アカウントの権限を借用する権限を付与します。

    次のコマンドでは、principalSet は Workload Identity プールと、kube-system Namespace 内の 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

    次のように置き換えます。

  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 クラスタ認証用に構成されているクラスタ（または Workload Identity クラスタ認証を使用する予定のクラスタ）ごとに（ブートストラップ クラスタを含む）、クラスタ内の Google Cloud Observability オペレーターに baremetal-cloud-ops サービス アカウントの権限を借用する権限を付与します。

    次の各コマンドでは、principalSet は Workload Identity プールと、kube-system Namespace 内の Kubernetes サービス アカウント（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 連携を構成します。

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)

    デフォルトでは、アクセス トークンの有効期間は 3, 600 秒（1 時間）です。Workload Identity クラスタ認証を使用している場合、bmctl はトークンの有効期限を確認します。トークンの有効期限が 1,800 秒（30 分）以内の場合、bmctl はエラーを報告して終了します。

  4. 作成するクラスタの Workload Identity 連携を構成します。

    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. 管理ワークステーションで、admin-sa サービス アカウントによって作成されたアクセス トークンの値を使用して GCP_ACCESS_TOKEN 環境変数を作成します。

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

    デフォルトでは、アクセス トークンの有効期間は 3, 600 秒（1 時間）です。

  6. bmctl create cluster コマンドを実行して、管理クラスタを作成します。

ユーザー クラスタを作成する

管理クラスタの作成手順は、プレビュー（バージョン 1.30 ～ 1.32）と一般提供（バージョン 1.33 以降）で若干異なります。一般提供の手順では、bmctl configure projects コマンドを使用してクラスタの Workload Identity 連携を構成します。

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)

    デフォルトでは、アクセス トークンの有効期間は 3, 600 秒（1 時間）です。

  3. 作成するクラスタの Workload Identity 連携を構成します。

    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. 管理ワークステーションで、admin-sa サービス アカウントによって作成されたアクセス トークンの値を使用して GCP_ACCESS_TOKEN 環境変数を作成します。

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

    デフォルトでは、アクセス トークンの有効期間は 3, 600 秒（1 時間）です。

  5. bmctl create cluster コマンドを実行して、ユーザー クラスタを作成します。

その他のクラスタ オペレーション

Workload Identity クラスタ認証を使用するクラスタの場合、次の bmctl コマンドでは、GCP_ACCESS_TOKEN 環境変数を有効かつアクティブなアクセス トークンに設定する必要があります。

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

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

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

    デフォルトでは、アクセス トークンの有効期間は 3, 600 秒（1 時間）です。Workload Identity クラスタ認証を使用している場合、bmctl はトークンの有効期限を確認します。トークンの有効期限が 1,800 秒（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 クラスタ認証のサービス アカウントのカスタム名を指定します。

    カスタム名を指定すると、既存のサービス アカウントを使用できます。指定するカスタム サービス アカウント名が互いに異なることを確認してください。単一のサービス アカウントを使用して 2 つ以上のデフォルトのサービス アカウントを置き換えることはできません。

    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 Agent がクラスタと Google Cloud間の接続の維持とクラスタの登録のために使用するサービス アカウントのメール名。

  • CUSTOM_CLOUD_OPS_GSA: Stackdriver Agent がクラスタのログと指標を Cloud Logging と Cloud Monitoring にエクスポートするために使用するサービス アカウントのメール名。

  • CUSTOM_AR_GSA: Google Distributed Cloud が Artifact Registry からコンテナ イメージをダウンロードするために使用するサービス アカウントのメール名。

制限事項

ベアメタル上の Google Distributed Cloud（ソフトウェアのみ）で Workload Identity クラスタ認証を使用する場合、次の機能はサポートされていません。

  • プロキシ サーバーの使用
  • VPC Service Controls
  • 既存のキーモード クラスタを更新して Workload Identity クラスタ認証を使用する
  • Google Cloud CLI、Terraform、 Google Cloud コンソールなどの GKE On-Prem API クライアントを使用したクラスタのライフサイクル管理

次のステップ