Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Connect Gateway の使用

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

始める前に

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

必要なロール

接続ゲートウェイを使用してクラスタに接続し、コマンドを実行するために必要な権限を取得するには、クラスタプロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

クラスタの kubeconfig ファイルを取得する: Connect Gateway 閲覧者（roles/gkehub.gatewayReader）
kubectl CLI コマンドを実行する: Connect Gateway 管理者（roles/gkehub.gatewayAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

Connect Gateway 管理者（roles/gkehub.gatewayAdmin）ロールは、attach、exec、port-forward、cp などの kubectl CLI コマンドの実行に必要な gkehub.gateway.stream 権限を含む唯一の事前定義ロールです。

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

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 を使用します。

ユーザーによるサービスアカウントの権限借用を許可する方法については、サービスアカウントに対するアクセスを管理するをご覧ください。

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 exec/cp/attach/port-forward コマンド

kubectl の次のコマンドはストリーミングコマンドで、さらに要件があります。

attach
cp
exec
port-forward

これらのコマンドを実行するには、次の要件を満たす必要があります。

コマンド attach、cp、exec を使用する場合はクラスタのバージョンが 1.30 以降、コマンド port-forward を使用する場合は 1.31 以降が必要です。
kubectl クライアントはバージョン 1.31 以降にする必要があります。クライアントのバージョンは、kubectl version コマンドで確認できます。新しいバージョンの kubectl をインストールするには、ツールをインストールするをご覧ください。
ユーザーとサービスアカウントには、IAM または RBAC を介して Kubernetes API への次の追加アクセス権が必要です。
- IAM: gkehub.gateway.stream 権限を含むロールを付与します。この権限は、roles/gkehub.gatewayAdmin の事前定義ロールに含まれています。この権限をカスタムロールに割り当てることもできます。
- RBAC: 次の例の Role と RoleBinding のように、get アクセスを含む Role または ClusterRole を pods/exec、pods/portforward、pods/attach API サブリソースに付与します。
```
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/portforward"]
  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: Group
  name: EMAIL # Specify the group that should have stream access
```
  次のように置き換えます。
  - NAMESPACE: Role と RoleBinding の Namespace。
  - EMAIL: クラスタがグループを使用した RBAC をサポートしている場合、ストリームアクセス権限を持つグループのメールアドレス。
  cluster-admin デフォルトの ClusterRole にもこれらの権限が含まれています。

トラブルシューティング

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

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

kubectl exec/cp/attach/port-forward のトラブルシューティング

多くの場合、コマンドの実行から返されるエラーは一般的なエラーである 400 Bad Request のため、問題をデバッグするには不十分です。より詳しいエラーメッセージを得るには、kubectl クライアントのバージョン 1.32 以降を使用して、レベル 4 以上の詳細度でコマンドを実行します（例: kubectl exec -v 4 ...）。

返されたログで、次のレスポンスを含むログを探します。

コマンド kubectl exec/cp/attach の場合: RemoteCommand fallback:
コマンド kubectl port-forward の場合: fallback to secondary dialer from primary dialer err:

コマンド kubectl exec -v 4 ... から返される一般的なエラーメッセージのトラブルシューティングについては、次のセクションをご覧ください。

IAM 権限がない

エラーメッセージに generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource と表示される場合は、コマンドを実行するために必要な IAM 権限が付与されていない可能性があります。この機能を使用するには、ユーザーに gkehub.gateway.stream IAM 権限が必要です。この権限は、roles/gkehub.gatewayAdmin ロールにデフォルトで含まれています。手順については、IAM 権限のセクションをご覧ください。

必要な RBAC 権限がない

エラーメッセージに ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden... と表示される場合は、RBAC 権限がありません。これらの kubectl コマンドを実行するには、クラスタに RBAC 権限が必要です。必要な RBAC 権限の設定について詳しくは、必要に応じて追加の RBAC ポリシーを作成して適用するをご覧ください。

エラーメッセージ generic::resource_exhausted: ゲートウェイの active_streams 割り当てが枯渇しました

フリートホストプロジェクトあたりのアクティブストリームの割り当て上限は 10 個です。これは connectgateway.googleapis.com/active_streams 割り当てで定義されます。割り当ての管理手順については、割り当ての表示と管理をご覧ください。

エラーメッセージ generic::failed_precondition: クラスタ内でエラーが発生しました

generic::failed_precondition: error encountered within the cluster エラーが発生した場合は、クラスタの Connect Agent ログを確認して根本原因を特定します。

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

Connect Agent で確認するログは failed to create the websocket connection... です。

エラーメッセージ generic::failed_precondition: エージェントへの接続失敗 / 中断

このコマンドを実行したときにすぐにこのエラーが発生した場合は、クラスタと Google との接続に問題があります。詳しくは、一般的なトラブルシューティングガイドをご覧ください。

セッションがアクティブになってから 20～30 分後にこのエラーが発生した場合は、セキュリティ上の理由による制限が原因です。接続を再確立する必要があります。

`kubectl --raw` のトラブルシューティング

短縮されたエンドポイント（kubectl get --raw /version など）を使用すると、Error from server (NotFound): the server could not find the requested resource というエラーが発生することがあります。完全なサーバーアドレスを指定する必要があります。

kubeconfig からエンドポイントを取得します。

# e.g. https://connectgateway.googleapis.com/v1/projects/1234567/locations/global/gkeMemberships/my-membership
FULL_GATEWAY_ENDPOINT=$(kubectl config view --minify -o jsonpath='{.clusters[*].cluster.server}')
echo $FULL_GATEWAY_ENDPOINT

次に、コマンドにエンドポイントを使用します（/version を使用する場合など）。

kubectl get --raw $FULL_GATEWAY_ENDPOINT/version

次のステップ

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