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 ではサポートされていません。
attach
cp
exec
port-forward
トラブルシューティング
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 のバージョンが最新バージョンであることを確認し、もう一度 Gatewaykubeconfig
を生成します。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 を使用する方法の例を確認する。