Connect Gateway の使用

このページでは、Connect Gateway を使用して登録済みクラスタに接続する方法について説明します。このページを読む前に、概要でコンセプトを理解しておいてください。このガイドでは、プロジェクト管理者が Gateway をすでに設定し、必要なロールと権限を付与していることを前提としています。

始める前に

次のコマンドラインツールがインストールされていることを確認します。
- Google Cloud CLI の最新バージョン。 Google Cloudの操作に使用するコマンドラインツールです。
- kubectl
Google Cloudを操作するシェル環境として Cloud Shell を使用する場合は、これらのツールがインストールされます。
プロジェクトで使用する gcloud CLI が初期化されていることを確認します。

Google Cloud アカウントにログインします。

Gateway API を介して接続クラスタを操作する場合は、ご自身の Google Cloud アカウントまたは Google Cloud サービスアカウントを使用してください。

Google Cloud CLI ツールの承認の手順でユーザーアカウントにログインします。Connect Gateway はサービスアカウントの権限借用をサポートしているため、以下のセクションで説明するように、ユーザーアカウントにログインした場合でも、サービスアカウントを使用してクラスタを操作できます。

登録済みのクラスタを選択する

アクセスするクラスタの名前がわからない場合は、次のコマンドを実行することで、フリートに登録されているすべてのクラスタを確認できます。

gcloud container fleet memberships list

これにより、メンバー名と外部 ID を含むフリートのクラスタがすべて一覧表示されます。フリート内の各クラスタには一意のメンバー名が付いています。GKE クラスタの場合、登録時にプロジェクト内で一意のクラスタ名を選択しなかった場合を除き、メンバー名はクラスタの作成時に指定した名前と一致します。

クラスタの Gateway `kubeconfig` を取得します

指定したクラスタとやり取りするために必要な kubeconfig は、次のコマンドを使用して取得します。

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

MEMBERSHIP_NAME は、クラスタのメンバーシップ名に置き換えます。

このコマンドは、特別な Connect Gateway 固有の kubeconfig を返します。これにより、Connect Gateway を介してクラスタに接続できます。

ご自身の Google Cloud アカウントではなくサービスアカウントを使用する場合は、gcloud config を使用して auth/impersonate_service_account をサービスアカウントのメールアドレスに設定します。

サービスアカウントを使用して Connect Gateway を操作するために使用するクラスタ認証情報を取得するコマンドは以下のとおりです。また、次の点に注意してください。

ベアメタルと VMware 用の Google Distributed Cloud（ソフトウェアのみ）クラスタ: メンバーシップ名はクラスタ名と同じです。
GKE on AWS: gcloud container aws clusters get-credentials を使用します。
GKE on Azure: gcloud container azure clusters get-credentials を使用します。

ユーザーによるサービスアカウントの権限借用を許可する方法については、サービスアカウントに対するアクセスを管理するをご覧ください。

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

SA_EMAIL_ADDRESS は、サービスアカウントのメールアドレスに置き換えます。ユーザーによるサービスアカウントの権限借用を許可する方法については、サービスアカウントに対するアクセスを管理するをご覧ください。

クラスタにコマンドを実行する

必要な認証情報を取得すると、通常の Kubernetes クラスタの場合と同様に、kubectl や go-client を使用してコマンドを実行できます。出力は次のようになります。

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

kubectl exec/cp/attach/port-forward コマンド

kubectl の次のコマンドはストリーミングコマンドで、さらに要件があります。

attach
cp
exec
port-forward

次の要件にご注意ください。

コマンド attach、cp、exec を使用する場合はクラスタのバージョンが 1.30 以降、コマンド port-forward を使用する場合は 1.31 以降が必要です。
kubectl クライアントはバージョン 1.31 以降にする必要があります。

クライアントのバージョンは、kubectl version コマンドで確認できます。新しいバージョンの kubectl をインストールするには、ツールをインストールするをご覧ください。

IAM ロール roles/gkehub.gatewayAdmin のほか cluster-admin ClusterRole を持つユーザーとサービスアカウントには、attach、cp、exec、port-forward コマンドを実行するために必要な権限があります。ユーザーとサービスアカウントにカスタム IAM ロールまたはカスタム RBAC ロールが付与されている場合は、その他の権限の付与が必要になる場合があります。詳しくは、以下のセクションをご覧ください。

必要に応じて追加の権限を付与する

Connect Gateway を介してコマンド attach、cp、exec、port-forward を実行するには、IAM 権限 gkehub.gateway.stream が必要です。この権限は roles/gkehub.gatewayAdmin に含まれています。

プロジェクトオーナーでないユーザー、またはプロジェクトで roles/gkehub.gatewayAdmin が付与されていないユーザーまたはサービスアカウントには、roles/gkehub.gatewayAdmin を付与するか、その他の必須ロールと gkehub.gateway.stream 権限を含むカスタムロールを作成する必要があります。カスタムロールの作成方法については、IAM ドキュメントのカスタムロールの作成と管理をご覧ください。

必要に応じて追加の RBAC ポリシーを作成して適用する

cluster-admin ClusterRole を持つユーザーとサービスアカウントには、コマンド attach、cp、exec、port-forward を実行するために必要な権限があります。

コマンドを実行するには、少なくとも次のルールが必要です。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE  # Specify the namespace
roleRef:
   apiGroup: "rbac.authorization.k8s.io"
   kind: Role
   name: stream-role
subjects:
- kind: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

トラブルシューティング

Gateway を介したクラスタへの接続に問題がある場合、次の一般的な問題については、お客様や管理者が確認できます。

サーバーにリソースタイプがありません: コマンド kubectl get ns が失敗すると、このエラーメッセージが表示される場合があります。このエラーには、いくつかの原因が考えられます。kubectl コマンドを詳細モードで実行して、さらに詳しく確認します（例: kubectl get ns -v 10）。
クラスタにアクティブな接続が見つかりません（プロジェクト: 12345、メンバーシップ: my-cluster）: Connect Agent が接続を失ったか、正しくインストールされていない場合に、このエラーメッセージが表示されることがあります（ Google Cloud 外のクラスタのみ）。この問題を解決するには、クラスタに名前空間 gke-connect が存在するかどうか確認する必要があります。gke-connect Namespace がクラスタに存在する場合は、Connect トラブルシューティングページを参照して、接続の問題を解決してください。
リクエストした URL はこのサーバーで見つかりませんでした: このエラーは、kubeconfig に間違ったサーバーアドレスが含まれている場合に発生します。使用している Google Cloud CLI のバージョンが最新バージョンであることを確認し、もう一度 Gateway kubeconfig を生成します。kubeconfig ファイルは手動で編集しないでください。予期しないエラーの原因となります。
ユーザー ID に Gateway API を使用する十分な権限がありません。API を使用するには roles/gkehub.gatewayAdmin、roles/gkehub.gatewayReader または roles/gkehub.gatewayEditor のロールが必要です。詳細については、Gateway 設定ガイドの IAM ロールをユーザーに付与するをご覧ください。
Connect Agent にユーザーのリクエストを送信する権限がありません: Connect Agent がユーザーに代わってリクエストを転送できるようにする必要があります。これは、クラスタの権限借用ポリシーを使用して指定されます。gateway-impersonate ロールをユーザーに追加する方法についての例は、Gateway 設定ガイドの RBAC 認可を構成するをご覧ください。
ユーザー ID に十分な RBAC 権限がないため、処理を実行できません: 選択した操作を実行するには、クラスタに対する適切な権限が必要です。適切な ClusterRole をユーザーに追加する例については、Gateway 設定ガイドの RBAC 認可を構成するをご覧ください。
ユーザー ID に十分な権限がないため、Google グループまたはサードパーティサポートの使用時に処理を実行できません: 関連するログを調べる方法については、GKE Identity Service のログの収集をご覧ください。
Connect Agent に異常があります: Connect トラブルシューティングページを参照して、クラスタが接続されていることを確認してください。
実行可能ファイル gke-gcloud-auth-plugin が見つかりません、または gcp という名前に認証プロバイダが見つかりません: GKE v1.26 から kubectl 認証が変更されたため、kubectl バージョン 1.26 以降ではこのエラーが表示される場合があります。gke-gcloud-auth-plugin をインストールし、最新バージョンの Google Cloud CLI で gcloud container fleet memberships get-credentials MEMBERSHIP_NAME を再実行します。
古いバージョンの Google Cloud CLI で Gateway への接続が失敗します: GKE クラスタでは、Connect Agent は Gateway の機能に必要なくなったため、メンバーシップ登録時にデフォルトでインストールされません。以前のバージョンの Google Cloud CLI（399.0.0 以前）では、クラスタ上に Connect Agent が存在することを想定しています。これらの以前のバージョンを使用して Gateway を使用しようとすると、新しいバージョンの Google Cloud CLI で登録されたクラスタで失敗する可能性があります。この問題を解決するには、Google Cloud CLI クライアントを新しいバージョンにアップグレードするか、フラグ --install-connect-agent を使用してメンバーシップ登録コマンドを再実行します。
返されたグループが多すぎます。グループ階層を編成しなおしてもう一度お試しください: グループ gke-security-groups のユーザーに対して返されるグループの数は、HTTP ヘッダーサイズの上限（8 KB）によって制限されます。グループの数に厳密な上限はありませんが、グループ名が長すぎるとリクエストがこの上限を超える原因となり、エラーが発生してグループ階層の再構築が必要になることがあります。

kubectl exec/cp/attach/port-forward のトラブルシューティング

多くの場合、コマンドの実行から返されるエラーは一般的なエラーである 400 Bad Request のため、問題をデバッグするには不十分です。より詳しいエラーメッセージを得るには、kubectl クライアントのバージョン 1.32 以降を使用して、レベル 4 以上の詳細度でコマンドを実行します（例: kubectl exec -v 4 ...）。

返されたログで、次のレスポンスを含むログを探します。

コマンド kubectl exec/cp/attach の場合: RemoteCommand fallback:
コマンド kubectl port-forward の場合: fallback to secondary dialer from primary dialer err:

コマンド kubectl exec -v 4 ... から返される一般的なエラーメッセージのトラブルシューティングについては、次のセクションをご覧ください。

IAM 権限がない

エラーメッセージに generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource と表示される場合は、コマンドを実行するために必要な IAM 権限が付与されていない可能性があります。この機能を使用するには、ユーザーに gkehub.gateway.stream IAM 権限が必要です。この権限は、roles/gkehub.gatewayAdmin ロールにデフォルトで含まれています。手順については、IAM 権限のセクションをご覧ください。

必要な RBAC 権限がない

エラーメッセージに ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden... と表示される場合は、RBAC 権限がありません。これらの kubectl コマンドを実行するには、クラスタに RBAC 権限が必要です。必要な RBAC 権限の設定について詳しくは、必要に応じて追加の RBAC ポリシーを作成して適用するをご覧ください。

エラーメッセージ generic::resource_exhausted: ゲートウェイの active_streams 割り当てが枯渇しました

フリートホストプロジェクトあたりのアクティブストリームの割り当て上限は 10 個です。これは connectgateway.googleapis.com/active_streams 割り当てで定義されます。割り当ての管理手順については、割り当ての表示と管理をご覧ください。

エラーメッセージ generic::failed_precondition: クラスタ内でエラーが発生しました

generic::failed_precondition: error encountered within the cluster エラーが発生した場合は、クラスタの Connect Agent ログを確認して根本原因を特定します。

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

Connect Agent で確認するログは failed to create the websocket connection... です。

エラーメッセージ generic::failed_precondition: エージェントへの接続失敗 / 中断

このコマンドを実行したときにすぐにこのエラーが発生した場合は、クラスタと Google との接続に問題があります。詳しくは、一般的なトラブルシューティングガイドをご覧ください。

セッションがアクティブになってから 20～30 分後にこのエラーが発生した場合は、セキュリティ上の理由による制限が原因です。接続を再確立する必要があります。

次のステップ

Cloud Build との統合のチュートリアルで、DevOps 自動化の一環として Connect Gateway を使用する方法の例を確認する。