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
は、次のコマンドを使用して取得します。
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
MEMBERSHIP_NAME
は、クラスタのメンバーシップ名に置き換えます。
このコマンドは、特別な Connect Gateway 固有の kubeconfig
を返します。これにより、Connect Gateway を介してクラスタに接続できます。
所有する Google Cloud アカウントではなく、サービス アカウントを使用する場合は、gcloud config
を使用して auth/impersonate_service_account
をサービス アカウントのメールアドレスに設定します。
サービス アカウントを使用して Connect Gateway を操作するために使用するクラスタ認証情報を取得するには、次のコマンドを実行します。次の点に注意してください。
- ベアメタルと VMware 用の Google Distributed Cloud(ソフトウェアのみ)クラスタ: メンバーシップ名はクラスタ名と同じです。
GKE on AWS:
gcloud container aws clusters get-credentials
を使用します。GKE on Azure:
gcloud container azure clusters get-credentials
を使用します。
所有する Google Cloud アカウントではなく、サービス アカウントを使用する場合は、gcloud config
を使用して auth/impersonate_service_account
をサービス アカウントのメールアドレスに設定します。ユーザーによるサービス アカウントの権限借用を許可する方法については、サービス アカウントに対するアクセスを管理するをご覧ください。
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
SA_EMAIL_ADDRESS
は、サービス アカウントのメールアドレスに置き換えます。ユーザーによるサービス アカウントの権限借用を許可する方法については、サービス アカウントに対するアクセスを管理するをご覧ください。
クラスタにコマンドを実行する
必要な認証情報を取得すると、通常の Kubernetes クラスタの場合と同様に、kubectl
や go-client
を使用してコマンドを実行できます。出力は次のようになります。
# Get namespaces in the Cluster.
kubectl get namespaces
NAME STATUS AGE
default Active 59d
gke-connect Active 4d
制限事項
次の kubectl
コマンドは、gcloud container fleet memberships get-credentials
コマンドを使用する Gateway ではサポートされていません。
attach
cp
exec
port-forward
コマンドのプレビュー サポート
attach
、cp
、exec
コマンドは(port-forward
は除く)、ベータ版コマンド gcloud beta container fleet memberships get-credentials
でサポートされています。このコマンドを使用すると、Connect Gateway のプレビュー版の機能を使用できます。
次の要件に注意してください。
GKE はプレビュー版ではサポートされていません。
クラスタはバージョン 1.30 以降にする必要があります。
kubectl
クライアントはバージョン 1.29 以降にする必要があります。バージョン 1.29 を使用する場合は、次の環境変数を設定する必要があります。export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
kubectl
バージョン 1.30 以降では、環境変数は必要ありません。クライアントのバージョンは、
kubectl version
コマンドの出力で確認できます。kubectl
の新しいバージョンをインストールするには、ツールをインストールするをご覧ください。
roles/gkehub.gatewayAdmin
IAM ロールと cluster-admin
ClusterRole
を持つユーザーとサービス アカウントには、attach
、cp
、exec
コマンドを実行するために必要な権限があります。ユーザーとサービス アカウントにカスタム IAM ロールまたはカスタム RBAC ロールが付与されている場合は、追加の権限の付与が必要になる場合があります。詳細については、以下のセクションをご覧ください。
必要に応じて追加の権限を付与する
Connect Gateway を介して attach
、cp
、exec
コマンドを実行するには、gkehub.gateway.stream
IAM 権限が必要です。この権限は roles/gkehub.gatewayAdmin
に含まれています。
プロジェクト オーナーでないユーザー、またはプロジェクトで roles/gkehub.gatewayAdmin
が付与されていないユーザーまたはサービス アカウントには、roles/gkehub.gatewayAdmin
を付与するか、その他の必須ロールと gkehub.gateway.stream
権限を含むカスタムロールを作成する必要があります。カスタムロールの作成方法については、IAM ドキュメントのカスタムロールの作成と管理をご覧ください。
必要に応じて追加の RBAC ポリシーを作成して適用する
cluster-admin
ClusterRole
を持つユーザーとサービス アカウントには、attach
、cp
、exec
コマンドを実行するために必要な権限があります。
コマンドを実行するには、少なくとも次のルールが必要です。
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: stream-role
namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
resources: ["pods/exec", "pods/attach", "pods/cp"]
verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: stream-rolebinding
namespace: NAMESPACE # Specify the namespace
roleRef:
apiGroup: "rbac.authorization.k8s.io"
kind: Role
name: stream-role
subjects:
- kind: User
name: EMAIL # Specify the user that should have stream access
namespace: NAMESPACE # Specify the namespace
トラブルシューティング
Gateway を介したクラスタへの接続に問題がある場合、次の一般的な問題については、お客様や管理者が確認できます。
- サーバーにリソースタイプがありません: コマンド
kubectl get ns
が失敗すると、このエラー メッセージが表示される場合があります。このエラーには、いくつかの原因が考えられます。kubectl
コマンドを詳細モードで実行して、さらに詳しく確認します(例:kubectl get ns -v 10
)。 - クラスタにアクティブな接続が見つかりません(プロジェクト: 12345、メンバーシップ: my-cluster): Connect Agent が接続を失ったか、正しくインストールされていない場合に、このエラー メッセージが表示される可能性があります(クラスタが Google Cloud の外部にある場合のみ)。この問題を解決するには、クラスタに
gke-connect
Namespace が存在するかどうか確認する必要があります。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 を使用する方法の例を確認する。