Connect Gateway の使用

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

始める前に

  • 次のコマンドライン ツールがインストールされていることを確認します。

    • 最新バージョンの Cloud SDK には、Google Cloud とやり取りするためのコマンドライン ツールである gcloud が含まれています。
    • kubectl

    Google Cloud を操作するシェル環境として Cloud Shell を使用する場合は、これらのツールがインストールされます。

  • プロジェクトで使用する gcloud ツールが初期化されていることを確認します。

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

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

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

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

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

gcloud container hub memberships list

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

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

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

# Fetch cluster credential used to interact with Connect gateway
gcloud container hub 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 hub memberships get-credentials MEMBERSHIP_NAME

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

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

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

次の kubectl コマンドは、ゲートウェイではサポート対象外です。

  • exec
  • proxy

トラブルシューティング

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

  • クラスタのアクティブな接続が見つかりません(プロジェクト: 12345、メンバーシップ: my-cluster): Connect Agent が接続を失うか、インストールされていないと、このエラーが表示されることがあります(Cloud Console に登録されている GKE クラスタまたは Terraform / Config Connector で発生する可能性があります)。この問題を解決するには、クラスタに gke-connect Namespace が存在するかどうか確認する必要があります。存在しない場合は、gcloud コマンドライン ツールを使用したクラスタの登録をご覧ください。gke-connect 名前空間がクラスタに存在する場合は、接続のトラブルシューティング ページを参照して接続の問題を解決してください。
  • The server doesn't have a resource type "namespaces": kubectl get ns のような単純なコマンドが失敗すると、このエラー メッセージが表示されることがあります。このエラーには、いくつかの原因が考えられます。kubectl コマンドを詳細モードで実行して、さらに詳しく確認します(例: kubectl get ns -v 10)。
  • リクエストした URL はこのサーバーで見つかりませんでした: このエラーは、kubeconfig に間違ったサーバー アドレスが含まれている場合に発生します。使用している Cloud SDK のバージョンが最新バージョンであることを確認し、もう一度ゲートウェイ kubeconfig を生成してください。予期しないエラーの原因となる kubeconfig ファイルを手動で編集しないでください。
  • ユーザー ID にゲートウェイ API を使用する十分な権限がありません。API を使用するには roles/gkehub.gatewayAdmin または roles/gkehub.gatewayReader のロールが必要です。詳細については、ゲートウェイ設定ガイドの 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 に異常があります: 接続のトラブルシューティング ページを参照して、クラスタが接続されていることを確認します。

次のステップ

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