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 を使用します。

所有する Google Cloud アカウントではなく、サービス アカウントを使用する場合は、gcloud config を使用して auth/impersonate_service_account をサービス アカウントのメールアドレスに設定します。ユーザーによるサービス アカウントの権限借用を許可する方法については、サービス アカウントに対するアクセスを管理するをご覧ください。

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 コマンドは、gcloud container fleet memberships get-credentials コマンドを使用する Gateway ではサポートされていません。

  • attach
  • cp
  • exec
  • port-forward

コマンドのプレビュー サポート

attach、cp、exec コマンドは（port-forward は除く）、ベータ版コマンド gcloud beta container fleet memberships get-credentials でサポートされています。このコマンドを使用すると、Connect Gateway のプレビュー版の機能を使用できます。

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

  • Google Cloud 上の GKE はプレビュー版でサポートされていません。

  • クラスタはバージョン 1.30 以降にする必要があります。

  • kubectl クライアントはバージョン 1.29 以降にする必要があります。バージョン 1.29 を使用する場合は、次の環境変数を設定する必要があります。

    export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

    kubectl バージョン 1.30 以降では、環境変数は必要ありません。

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

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

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

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

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

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

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

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

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach"]
  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

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

多くの場合、コマンドの実行から返されるエラーは、問題をデバッグするには不十分です。この場合は、詳細なロギングレベル（kubectl exec -v 5 ... など）でコマンドを再実行します。

Connect Gateway のベータ版トラックが使用されていない

400 Bad Request エラーが発生した場合は、gcloud CLI ベータ版トラックを使用して connect ゲートウェイの kubeconfig ファイルを再生成し、エラーが解決するかどうかを確認します。

gcloud beta container fleet memberships get-credentials my-membership`

それでも 400 Bad Request エラーが発生する場合は、次のセクションの手順に沿って操作します。

kubectl 環境フラグが設定されていない

使用している kubectl クライアント バージョンが 1.29 の場合は、環境変数 KUBECTL_REMOTE_COMMAND_WEBSOCKETS を有効にする必要があります。これが有効になっていない場合、400 Bad Request エラーが発生します。環境変数が有効かどうかを確認するには、次のコマンドを実行します。

 echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`

変数が設定されていない場合は、次の環境変数を設定して有効にします。

export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

kubectl バージョン 1.30 以降では、デフォルトで有効になっているため、このフラグは必要ありません。

kubectl バージョンが 1.29 より前の場合、この機能は動作しません。

IAM 権限がない

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

エラー メッセージ 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... です。

必要な RBAC 権限がない

Connect エージェントのログのエラー メッセージに 403 Forbidden が含まれている場合は、RBAC 権限がありません。クラスタには、これらの kubectl コマンドを実行するための RBAC 権限が設定されています。必要な RBAC 権限の設定については、RBAC ポリシーのセクションをご覧ください。

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

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

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

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

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

トラブルシューティング

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

  • サーバーにリソースタイプがありません: コマンド kubectl get ns が失敗すると、このエラー メッセージが表示される場合があります。このエラーには、いくつかの原因が考えられます。kubectl コマンドを詳細モードで実行して、さらに詳しく確認します（例: kubectl get ns -v 10）。
  • クラスタにアクティブな接続が見つかりません（プロジェクト: 12345、メンバーシップ: my-cluster）: Connect Agent が接続を失ったか、正しくインストールされていない場合に、このエラー メッセージが表示される可能性があります（クラスタが Google Cloud の外部にある場合のみ）。この問題を解決するには、クラスタに gke-connect Namespace が存在するかどうか確認する必要があります。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 フラグを使用してメンバーシップ登録コマンドを再実行します。

次のステップ

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