Connect Gateway の使用

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

始める前に

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

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

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

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

Google Cloud アカウントにログインします。

独自の Google Cloud アカウントまたは Google Cloud サービス アカウントを使用して、ゲートウェイ API を介して接続されたクラスタを操作できます。

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

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

アクセスするクラスタの名前が不明な場合、次のコマンドを実行して、Environ の登録済みクラスタをすべて確認できます。

gcloud container hub memberships list

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

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

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

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

トラブルシューティング

ゲートウェイ経由でクラスタに接続する際に問題が発生する場合は、次の一般的な問題を確認してください。

  • サーバーにリソースタイプ「namespaces」がありません: kubectl get ns などの単純なコマンドが失敗すると、このエラー メッセージが表示されることがあります。このエラーにはいくつかの原因が考えられます。詳細モードで kubectl コマンドを実行し、詳細を確認します(例: kubectl get ns -v 10)。
  • リクエストされた URL はこのサーバーで見つかりませんでした: kubeconfig に不適切なサーバー アドレスが含まれている場合に、このエラーが表示されることがあります。使用している Cloud SDK のバージョンが最新バージョンであることを確認し、ゲートウェイ kubeconfig の生成を再試行します。kubeconfig ファイルは、手動で編集しないでください。予期しないエラーが発生します。
  • ユーザー ID にゲートウェイ API を使用する十分な権限がありません。API を使用するには role/gkehub.gatewayAdmin ロールが必要です。詳細については、ゲートウェイ設定ガイドの IAM 権限の付与をご覧ください。
  • Connect Agent にユーザーのリクエストを送信する権限がありません: Connect Agent がユーザーに代わってリクエストを転送できるようにする必要があります。これは、クラスタの権限借用ポリシーを使用して指定されます。gateway-impersonate ロールをユーザーに追加する方法についての例は、ゲートウェイ設定ガイドの RBAC ポリシーを構成するをご覧ください。
  • ユーザー ID にはオペレーションを実行する十分な RBAC 権限がありません: 選択したオペレーションを実行するには、クラスタに対する適切な権限が必要です。ユーザーを適切な ClusterRole に追加する方法についての例は、ゲートウェイ設定ガイドの RBAC ポリシーを構成するをご覧ください。
  • Connect Agent に異常があります: 接続のトラブルシューティング ページを参照して、クラスタが接続されていることを確認します。

次のステップ

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