サードパーティの ID を使用して Connect Gateway を設定する

このガイドは、Google ID がなく Google Workspace に属していないユーザーが含まれるプロジェクトで、Connect Gateway を設定する必要のあるプラットフォーム管理者を対象としています。このガイドでは、これらの ID を「サードパーティの ID」と呼びます。このガイドを読む前に、Connect Gateway の概要のコンセプトを理解しておく必要があります。個々の Google アカウントを承認するには、Connect Gateway の設定をご覧ください。Google グループのサポートについては、Google グループでの Connect Gateway の設定をご覧ください。

このガイドの設定では、ユーザーは Google Cloud CLI、Connect Gateway、Google Cloud コンソールを使用してフリートクラスタにログインできます。

サポートされるクラスタタイプ

次の登録済みのクラスタタイプに対して、Connect Gateway を介したサードパーティの ID によるアクセス制御を設定できます。

GKE クラスタ
GKE Enterprise 1.13 以降の GKE on VMware と GKE on Bare Metal
Kubernetes バージョン 1.25 以降の GKE on AWS と GKE on Azure。
接続されたクラスタ（GKE Enterprise 1.16 以降）

この機能を使用するためにオンプレミスクラスタをアップグレードする必要がある場合は、VMWare 用 GKE Enterprise クラスタのアップグレードとベアメタル用 GKE Enterprise クラスタのアップグレードをご覧ください。

上記以外の GKE クラスタ環境のユースケースがある場合は、Cloud カスタマーケアまたは Connect Gateway チームにお問い合わせください。

仕組み

概要で説明されているように、ユーザーは Google Workspace と Cloud Identity 以外の ID プロバイダを使用している可能性があります。Workforce Identity 連携を使用すると、ユーザーは Okta や Azure Active Directory などのサードパーティ ID プロバイダを使用して Connect Gateway 経由でクラスタにアクセスできます。Google アカウントとは異なり、サードパーティのユーザーは Identity and Access Management（IAM）の次の形式で表されます。

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE

WORKFORCE_POOL_ID は、関連するサードパーティの ID プロバイダを含む Workforce プールの名前です。
SUBJECT_VALUE は、サードパーティの ID の Google サブジェクトへのマッピングです。

サードパーティグループの場合、IAM プリンシパルは次の形式になります。

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_VALUE

次に、サードパーティのユーザーがこのサービスを有効にして Anthos クラスタの認証を行い、コマンドを実行する一般的なフローを示します。このフローを成功させるには、ユーザーまたはグループのいずれかのロールベースアクセス制御（RBAC）ポリシーをクラスタに適用する必要があります。

個々のユーザーの場合、ユーザーの完全な IAM プリンシパル名を使用する RBAC ポリシーがクラスタに存在する必要があります。

グループ機能を使用する場合、完全な IAM プリンシパル名を使用する RBAC ポリシーが、次のグループのクラスタに存在する必要があります。

ユーザー alice@example.com をメンバーに含むグループ。
Alice の Google Cloud 組織にある Workforce プール内の ID プロバイダのマッピングに含まれているグループ。

Gateway のサードパーティ ID フローを示す図

ユーザー alice@example.com がサードパーティのブラウザベースのログインを使用して、サードパーティの ID で gcloud にログインします。コマンドラインからクラスタを使用するため、Connect Gateway の使用で説明されているように、ユーザーがクラスタの Gateway kubeconfig を取得します。
ユーザーが kubectl コマンドを実行するか、Google Cloud コンソールで Google Kubernetes Engine の [ワークロード] または [オブジェクトブラウザ] ページを開いてリクエストを送信します。
リクエストが Connect Gateway によって受信されます。Connect Gateway は、Workforce Identity 連携を使用してサードパーティの認証を処理します。
Connect Gateway で IAM による承認チェックが実行されます。
Connect Service が、クラスタで動作している Connect Agent にリクエストを転送します。このリクエストには、クラスタの認証と認可で使用するためのユーザーの認証情報が含まれています。
Connect Agent が、リクエストを Kubernetes API サーバーに転送します。
Kubernetes API サーバーでリクエストを GKE Identity Service に転送すると、GKE Identity Service でリクエストが検証されます。
GKE Identity Service によって、サードパーティのユーザーとグループの情報が Kubernetes API サーバーに返されます。Kubernetes API サーバーでこの情報を使用して、クラスタの構成済み RBAC ポリシーに基づいてリクエストを承認できます。

始める前に

次のコマンドラインツールがインストールされていることを確認します。
- Google Cloud CLI の最新バージョン。Google Cloud の操作に使用するコマンドラインツールです。
- Kubernetes コマンドラインツール kubectl。クラスタとのやり取りに使用します。
Google Cloud を操作するシェル環境として Cloud Shell を使用する場合は、これらのツールがインストールされます。
プロジェクトで使用する gcloud CLI が初期化されていることを確認します。
このガイドでは、プロジェクトに roles/owner があることを前提としています。プロジェクトオーナーでない場合は、設定手順を行うために追加の権限が必要になる場合があります。
Google Cloud 外部のクラスタの場合、GKE Identity Service は、認証を完了するために、クラスタから Google API を呼び出す必要があります。ネットワークポリシーでアウトバウンドトラフィックがプロキシを経由する必要があるかどうかを確認します。

Workforce Identity を使用してサードパーティの ID 属性のマッピングを設定する

ID プロバイダに対応する手順に沿って、Google Cloud 組織用に Workforce プールと ID プロバイダが設定されていることを確認します。

API を有効にする

Gateway をプロジェクトに追加するには、Connect Gateway API と必要な依存関係 API を有効にします。ユーザーが Google Cloud コンソールを使用してクラスタに対する認証のみを行う場合、connectgateway.googleapis.com を有効にする必要はありませんが、他の API を有効にする必要があります。

gcloud services enable --project=PROJECT_ID  \
connectgateway.googleapis.com \
anthos.googleapis.com \
gkeconnect.googleapis.com \
gkehub.googleapis.com \
cloudresourcemanager.googleapis.com

GKE Identity Service を設定する

Connect Gateway のサードパーティ ID サポート機能は、GKE Identity Service を使用して Google からサードパーティのグループメンバーシップ情報を取得します。GKE Identity Service の詳細については、GKE Identity Service の概要をご覧ください。

GKE Identity Service がインストールされていることを確認する

GKE Identity Service は、バージョン 1.7 以降の GKE クラスタにデフォルトでインストールされています（ただし、サードパーティ ID のサポートにはバージョン 1.13 以降が必要です）。次のコマンドを実行すると、クラスタに正しくインストールされていることを確認できます。

kubectl --kubeconfig CLUSTER_KUBECONFIG get all -n anthos-identity-service

CLUSTER_KUBECONFIG は、クラスタの kubeconfig のパスに置き換えます。

グループにサードパーティの ID サポートを構成する

クラスタまたはフリートがすでに Google グループのサポート用に構成されている場合は、追加の手順はありません。IAM ロールをサードパーティのユーザーとグループに付与するまでスキップできます。

GKE on Bare Metal または GKE on VMware を使用している場合、GKE Identity Service の設定方法に応じて、サードパーティのグループ機能の構成方法が決まります。

GKE Identity Service を初めて使用する場合は、サードパーティグループのサポートを構成するときに Fleet API（推奨）または kubectl のいずれを使用するかを選択できます。

GKE Identity Service の使用が初めてでない場合は、次の点に留意してください。

別の ID プロバイダ用にすでにフリートレベルで GKE Identity Service を設定している場合、サードパーティのグループ機能はデフォルトで有効になっています。詳細と必要な追加設定については、以下の「フリート」をご覧ください。
クラスタごとに別の ID プロバイダに GKE Identity Service をすでに設定している場合は、以下の「Kubectl」で、サードパーティのグループ機能の構成を更新する手順を確認してください。

フリート

Google Cloud コンソールまたはコマンドラインを使用して、Fleet Feature API を使用するサードパーティグループへのアクセスを構成できます。

コンソール

フリートに GKE Identity Service をまだ設定していない場合は、GKE Identity Service のクラスタを構成するの説明に従って設定します。

クラスタを選択して構成を更新する

Google Cloud コンソールで、GKE Enterprise の [機能] ページに移動します。

GKE Enterprise の [機能] に移動
[機能] テーブルの [Identity Service] 行の [詳細] をクリックします。プロジェクトのクラスタの詳細が表示されます。
[Identity Service の更新] をクリックして、設定ペインを開きます。
構成するクラスタを選択します。個々のクラスタを選択するか、すべてのクラスタを同じ ID 構成にするように指定できます。
[Configure Identity Providers] セクションで、ID プロバイダの保持、追加、更新、削除を選択できます。
[続行] をクリックして、次の構成ステップに進みます。この設定に対して少なくとも 1 つの有効なクラスタを選択した場合は、[Google 認証] セクションが表示されます。
選択したクラスタで Google 認証を有効にするには、[有効にする] を選択します。プロキシ経由で Google ID プロバイダにアクセスする必要がある場合は、[プロキシ] に詳細を入力します。
[構成の更新] をクリックします。これにより、選択したクラスタに ID 構成が適用されます。

gcloud

フリートに GKE Identity Service をまだ設定していない場合は、GKE Identity Service のクラスタを構成するの説明に従って設定します。auth-config.yaml ファイルでは次の構成のみを指定します。

spec:
  authentication:
  - name: google-authentication-method
    google:
      disable: false

プロキシを使用してサードパーティのグループアクセスを構成する

プロキシ経由で ID プロバイダにアクセスする必要がある場合は、auth-config.yaml ファイルの proxy フィールドを使用します。たとえば、クラスタがプライベートネットワークにあり、パブリック ID プロバイダに接続する必要がある場合に設定する必要があります。別のプロバイダ用に GKE Identity Service をすでに構成している場合でも、この構成を追加する必要があります。

proxy を構成するために、既存の構成ファイル auth-config.yaml の authentication セクションを更新する方法は次のとおりです。

  spec:
    authentication:
    - name: authentication-method
      google:
        disable: false
      proxy: PROXY_URL

ここで

disable（省略可）は、クラスタのサードパーティのグループ機能を有効にするかどうかを指定します。このオプションはデフォルトで false に設定されています。この機能を無効にする場合は、true に設定します。
PROXY_URL（省略可）は、Google ID に接続するプロキシサーバーアドレスです。例: http://user:password@10.10.10.10:8888

構成を適用する

この構成をクラスタに適用するには、次のコマンドを実行します。

gcloud container fleet identity-service apply \
--membership=CLUSTER_NAME \
--config=/path/to/auth-config.yaml

ここで

CLUSTER_NAME は、フリート内のクラスタの一意のメンバーシップ名です。

一度適用されると、この構成は GKE Identity Service コントローラによって管理されます。GKE Identity Service のクライアント構成にローカルで加えられた変更は、コントローラにより、この設定に指定された構成に戻されます。

Kubectl

サードパーティのグループ機能を使用して、GKE Identity Service を使用するようにクラスタを構成するには、クラスタの GKE Identity Service ClientConfig を更新する必要があります。これは、クラスタ構成に使用される Kubernetes カスタムリソースタイプ（CRD）です。各 GKE Enterprise クラスタには、構成の詳細で更新する kube-public Namespace に default という名前の ClientConfig リソースがあります。

構成を編集するには、次のコマンドを使用します。

kubectl --kubeconfig CLUSTER_KUBECONFIG -n kube-public edit clientconfig default

kubeconfig に複数のコンテキストがある場合は、現行のコンテキストが使用されます。コマンドを実行する前に、現在のコンテキストを正しいクラスタにリセットすることが必要になる場合があります。

次の例では、タイプ google の構成を持つ新しい認証方法を使用して ClientConfig を更新し、サードパーティのグループ機能を有効にする方法を示します。internalServer フィールドが空の場合は、次のように https://kubernetes.default.svc に設定されていることを確認します。

spec:
  authentication:
  - google:
      audiences:
      - "CLUSTER_IDENTIFIER"
    name: google-authentication-method
    proxy: PROXY_URL
  internalServer: https://kubernetes.default.svc

ここで

CLUSTER_IDENTIFIER（必須）はクラスタのメンバーシップの詳細を示します。次のコマンドを使用して、クラスタのメンバーシップの詳細を取得できます。

kubectl --kubeconfig CLUSTER_KUBECONFIG get memberships membership -o yaml

ここで

CLUSTER_KUBECONFIG は、クラスタの kubeconfig ファイルのパスです。レスポンスの spec.owner.id フィールドを参照して、クラスタのメンバーシップの詳細を取得します。

以下に、クラスタのメンバーシップの詳細を示すレスポンスの例を示します。

id: //gkehub.googleapis.com/projects/123456789/locations/global/memberships/xy-ab12cd34ef

これは、//gkehub.googleapis.com/projects/PROJECT_NUMBER/locations/global/memberships/MEMBERSHIP という形式に対応します。

サードパーティのユーザーとグループに IAM のロールを付与する

Gateway 経由で接続されたクラスタを操作するには、グループに次の Google Cloud の追加ロールが必要です。

roles/gkehub.gatewayAdmin: このロールを付与すると、ユーザーは Connect Gateway API にアクセスできるようになります。
- ユーザーが、接続されたクラスタへの読み取り専用アクセスのみを必要とする場合は、代わりに roles/gkehub.gatewayReader を使用できます。
- ユーザーが接続されたクラスタへの読み取り / 書き込みアクセスを必要とする場合は、代わりに roles/gkehub.gatewayEditor を使用できます。
roles/gkehub.viewer: このロールを使用すると、ユーザーは登録済みクラスタメンバーシップを表示できます。

個々の ID とマッピングされたグループに必要なロールを追加する方法は、次のとおりです。

単一の ID

プロジェクト PROJECT_ID の単一の ID に必要なロールを付与するには、次のコマンドを実行します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

ここで

PROJECT_ID はプロジェクト ID です。
GATEWAY_ROLE は、roles/gkehub.gatewayAdmin、roles/gkehub.gatewayReader、gkehub.gatewayEditor のいずれかにします。
WORKFORCE_POOL_ID は、Workforce Identity プール ID です。
SUBJECT_VALUE は、ユーザー ID です。

グループ

プロジェクト PROJECT_ID の特定のグループ内のすべての ID に必要なロールを付与するには、次のコマンドを実行します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

ここで

PROJECT_ID はプロジェクト ID です。
GATEWAY_ROLE は、roles/gkehub.gatewayAdmin、roles/gkehub.gatewayReader、gkehub.gatewayEditor のいずれかにします。
WORKFORCE_POOL_ID は、Workforce プール ID です。
GROUP_ID は、マッピングされた google.groups クレーム内のグループです。

RBAC ポリシーを適用する際に部門属性を指定するなど、その他のカスタマイズについては、Workforce Identity を使用してサードパーティマッピングを設定するに記載されている ID プロバイダの設定をご覧ください。

IAM の権限とロールの付与については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。

ロールベースアクセス制御（RBAC）ポリシーを構成する

最後に、各クラスタの Kubernetes API サーバーは、指定したサードパーティのユーザーとグループから Gateway を経由する kubectl コマンドを許可する必要があります。各クラスタに対して、クラスタ上でサブジェクトが持つ権限を指定する RBAC 権限ポリシーを追加する必要があります。

RBAC ポリシーの対象者は IAM バインディングと同じ形式を使用する必要があります。サードパーティのユーザーは principal://iam.googleapis.com/ で始まり、サードパーティのグループは principalSet://iam.googleapis.com/ で始まります。GKE Identity Service がクラスタに構成されていない場合は、サードパーティのユーザーロール / クラスタロールに加えて、権限借用ポリシーが必要です。その場合は、RBAC 設定手順に沿って、principal://iam.googleapis.com/ で始まるサードパーティのプリンシパルをユーザーとして追加します。

次の例は、GKE Identity Service が構成されているクラスタで、サードパーティのグループのメンバーに cluster-admin 権限を付与する方法を示しています。ポリシーファイルを /tmp/admin-permission.yaml として保存し、現在のコンテキストに関連付けられているクラスタに適用できます。

cat <<EOF > /tmp/admin-permission.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gateway-cluster-admin-group
subjects:
- kind: Group
  name: "principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP"
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
EOF
# Apply permission policy to the cluster.
kubectl apply --kubeconfig=KUBECONFIG_PATH -f /tmp/admin-permission.yaml

RBAC 権限の指定についての詳細は、RBAC 認証の使用をご覧ください。

次のステップ

Connect Gateway を使用して、コマンドラインからクラスタに接続する方法を学習する。
Cloud Build との統合のチュートリアルで、DevOps 自動化の一環として Connect Gateway を使用する方法の例を確認する。