Connect Gateway の使用

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

始める前に

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

Google Cloud アカウントにログインする

接続されたクラスタの操作は、所有する Google Cloud アカウントや Google Cloud サービスアカウントを使用し、ゲートウェイ API を介して行えます。

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

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

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

gcloud container fleet memberships list

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

クラスタのゲートウェイ `kubeconfig` を取得します

指定したクラスタとのやり取りに必要な kubeconfig は、次のコマンドを使用して取得します。ここで、MEMBERSHIP_NAME は、クラスタのフリートメンバー名に置き換えます。このコマンドは、特別なConnect Gateway 特有の kubeconfig を返します。これにより、ゲートウェイを介してクラスタに接続できます。

# 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 コマンドは、ゲートウェイではサポート対象外です。

exec
proxy
port-forward
attach

トラブルシューティング

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

サーバーにリソースタイプがありません: kubectl get ns のような単純なコマンドが失敗すると、このエラーメッセージが表示される場合があります。このエラーには、いくつかの原因が考えられます。kubectl コマンドを詳細モードで実行して、さらに詳しく確認します（例: kubectl get ns -v 10）。
クラスタのアクティブな接続が見つかりません（プロジェクト: 12345、メンバーシップ: my-cluster）: Connect Agent が接続を失ったか、正しくインストールされていない場合に、このエラーメッセージが表示される可能性があります。この問題を解決するには、クラスタに gke-connect Namespace が存在するかどうか確認する必要があります。まだない場合は、Google Cloud CLI でクラスタの登録をご覧ください。gke-connect 名前空間がクラスタに存在する場合は、接続のトラブルシューティングページを参照して接続の問題を解決してください。
リクエストした URL はこのサーバーで見つかりませんでした: このエラーは、kubeconfig に間違ったサーバーアドレスが含まれている場合に表示されます。使用している Google Cloud CLI のバージョンが最新バージョンであることを確認し、もう一度ゲートウェイ kubeconfig を生成します。kubeconfig ファイルを手動で編集しないでください。予期しないエラーの原因となります。
ユーザー ID にゲートウェイ API を使用する十分な権限がありません。API を使用するには roles/gkehub.gatewayAdmin、roles/gkehub.gatewayReader または roles/gkehub.gatewayEditor のロールが必要です。詳細については、ゲートウェイ設定ガイドの IAM ロールをユーザーに付与するをご覧ください。
Connect Agent にユーザーのリクエストを送信する権限がありません: Connect Agent がユーザーに代わってリクエストを転送できるようにする必要があります。これは、クラスタの権限借用ポリシーを使用して指定されます。gateway-impersonate ロールをユーザーに追加する方法についての例は、ゲートウェイ設定ガイドの RBAC 認可を構成するをご覧ください。
The user identity does not have sufficient RBAC permissions to perform the operation: 選択した操作を実行するには、クラスタに対する適切な権限が必要です。適切な ClusterRole をユーザーに追加する例については、ゲートウェイ設定ガイドの RBAC 認可を構成するをご覧ください。
Connect Agent に異常があります: 接続のトラブルシューティングページを参照して、クラスタが接続されていることを確認します。
実行可能ファイル 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 でゲートウェイへの接続が失敗する: GKE クラスタでは、Connect エージェントはゲートウェイの機能として必要なくなったため、メンバーシップ登録時にデフォルトでインストールされません。以前のバージョンの Google Cloud CLI（399.0.0 以前）では、クラスタ上に Connect エージェントが存在すると想定しています。これらの古いバージョンでゲートウェイを使用しようとすると、新しいバージョンの Google Cloud CLI で登録されているクラスタが失敗することがあります。この問題を解決するには、Google Cloud CLI クライアントを新しいバージョンにアップグレードするか、--install-connect-agent フラグを指定してメンバーシップ登録コマンドを再実行します。

次のステップ

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