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 は、次のコマンドを使用して取得します。ここで、MEMBERSHIP_NAME は、クラスタのフリートメンバー名に置き換えます。このコマンドは、特別な Connect Gateway 固有の kubeconfig を返します。これにより、Gateway を介してクラスタに接続できます。

# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

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

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

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

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

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

次の kubectl コマンドは、Gateway ではサポートされていません。

exec
proxy
port-forward
attach

トラブルシューティング

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

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