kubectl をインストールしてクラスタ アクセスを構成する

このページでは、Google Kubernetes Engine（GKE）クラスタの管理とアクセスに使用される kubectl コマンドライン ツールのインストール手順について説明します。 Trusted Cloud by S3NSで複数のクラスタを実行する場合は、kubectl 構成が必要です。

次のことについて学習します。

• kubectl の仕組み
• kubectl と必要な依存関係をインストールする方法
• kubectl のデフォルト クラスタを設定する方法
• 特定のクラスタに対して kubectl コマンドを実行する方法

このページは、クラウド リソースのプロビジョニングと構成など、クラウド インフラストラクチャの設定、モニタリング、管理を行う IT 管理者、オペレーター、デベロッパーを対象としています。 Trusted Cloud by S3NS のドキュメントで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE Enterprise ユーザーロールとタスクをご覧ください。

このページを読む前に、Kubernetes kubectl について理解しておいてください。

始める前に

作業を始める前に、次のことを確認してください。

• Google Kubernetes Engine API を有効にする。
Google Kubernetes Engine API の有効化
• このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。

kubectl をインストールする

kubectl は、Google Cloud CLI または外部パッケージ マネージャー（apt、yum など）を使用してインストールできます。

必要なプラグインをインストールする

kubectl などの Kubernetes クライアントには認証プラグイン gke-gcloud-auth-plugin が必要です。このプラグインは、Client-go Credential Plugins フレームワークを使用して、GKE クラスタと通信するための認証トークンを提供します。

Kubernetes バージョン 1.26 がリリースされる前に gcloud CLI を起動する場合は、gke-gcloud-auth-plugin バイナリのインストールが必要になります。プラグインがインストールされていない場合、kubectl などのカスタム Kubernetes クライアントの既存のインストールは機能しなくなります。

kubectl などのクライアントで GKE を操作するには、このプラグインをインストールする必要があります。プラグインがインストールされていなければ、既存のクライアントにエラー メッセージが表示されます。

始める前に、プラグインがインストール済みであるかどうかを確認します。

gke-gcloud-auth-plugin --version

出力にバージョン情報が表示される場合は、このセクションをスキップします。

認証プラグインは、gcloud CLI または外部パッケージ マネージャー（apt、yum など）を使用してインストールできます。

  gcloud components install gke-gcloud-auth-plugin

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

gke-gcloud-auth-plugin バイナリのインストールを確認します。

1. gke-gcloud-auth-plugin バイナリのバージョンを確認します。

   gke-gcloud-auth-plugin --version
   

2. プラグインを使用するように kubectl 構成を更新します。

   gcloud container clusters get-credentials CLUSTER_NAME \
       --location=CONTROL_PLANE_LOCATION
   

   次のように置き換えます。

   • CLUSTER_NAME: クラスタの名前。
   • CONTROL_PLANE_LOCATION: クラスタのコントロール プレーンの Compute Engine のロケーション。リージョン クラスタの場合はリージョン、ゾーンクラスタの場合はゾーンを指定します。

3. 次のコマンドを実行して構成を検証します。

   kubectl get namespaces
   

   出力は次のようになります。

   NAME              STATUS   AGE
   default           Active   51d
   kube-node-lease   Active   51d
   kube-public       Active   51d
   kube-system       Active   51d
   

このプラグインの詳細については、Kubernetes KEP をご覧ください。

kubectl を操作する

Kubernetes は、kubeconfig という名前の YAML ファイルを使用して、kubectl のクラスタ認証情報を格納します。デフォルトで、このファイルは $HOME/.kube/config に保存されます。

kubeconfig には、コンテキストと呼ばれるアクセス パラメータのグループが含まれています。各コンテキストには 1 つの Kubernetes クラスタ、1 人のユーザー、任意のデフォルトの Namespace が含まれます。kubectl は、コマンドの実行時にコンテキストを参照します。

必要に応じて、次のタスクを使用して kubectl を構成できます。

• kubectl が通信するクラスタを選択します。
• kubeconfig ファイルで現在のコンテキストを設定して、kubectl のデフォルト クラスタを設定します。
• --cluster フラグを使用して、特定のクラスタに対して kubectl コマンドを実行します。

kubeconfig を表示する

環境の kubeconfig を表示するには、次のコマンドを実行します。

kubectl config view

このコマンドは、すでに kubeconfig エントリが生成されているすべてのクラスタのリストを返します。GKE クラスタがリストされた場合、現在の環境でその GKE クラスタに対して kubectl コマンドを実行できます。それ以外の場合は、kubectl のクラスタ情報を保存する必要があります。

kubectl の現在のコンテキストを表示する

現在のコンテキストとは、現在 kubectl のデフォルトとなっているクラスタのことです。すべての kubectl コマンドはこのクラスタに対して実行されます。

gcloud container clusters create-auto を使用してクラスタを作成すると、1 つのエントリが自動的に環境内の kubeconfig ファイルに追加され、現在のコンテキストがそのクラスタに変更されます。次に例を示します。

gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

kubectl の現在のコンテキストを表示するには、次のコマンドを実行します。

kubectl config current-context

kubectl のクラスタ情報を保存する

Trusted Cloud コンソールを使用してクラスタを作成する場合、または別のパソコンから gcloud CLI を使用してクラスタを作成する場合には、環境の kubeconfig ファイルが更新されません。また、あるプロジェクト チームメンバーが gcloud CLI を使用してメンバー自身のパソコンからクラスタを作成する場合、そのメンバーの kubeconfig だけが更新されます。kubeconfig エントリには次のいずれかが格納されます。

• gcloud auth list に示すような認証情報、または
• アプリケーションのデフォルト認証情報（構成されている場合）

使用中の環境で kubeconfig コンテキストを生成するには、container.clusters.get 権限が付与されていることを確認します。この権限を付与する最も権限の少ない IAM ロールは container.clusterViewer です。

特定のクラスタの kubeconfig コンテキストを生成するには、次のコマンドを実行します。

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

次のように置き換えます。

• CLUSTER_NAME: クラスタの名前。
• CONTROL_PLANE_LOCATION: クラスタのコントロール プレーンの Compute Engine のロケーション。リージョン クラスタの場合はリージョン、ゾーンクラスタの場合はゾーンを指定します。

クラスタの内部 IP アドレスを使用して kubeconfig エントリを生成する

すべてのクラスタには、特性が異なる複数のエンドポイント アドレスがあります。これらのエンドポイントの 1 つは、kubectl や他のサービスがクラスタ コントロール プレーンと通信するために使用する正規エンドポイントとして機能します。GKE は、次の順序に基づいてエンドポイントを自動的に選択します。

• 外部 IP アドレス（外部エンドポイントを有効にしている場合）
• 内部 IP アドレス
• DNS アドレス（IP アクセスが無効な場合）。デフォルトで正規エンドポイントを使用するには、get-credentials コマンドを実行します。kubectl が使用するエンドポイントをさらに制御するには、--internal-ip フラグまたは --dns-endpoint フラグを使用します。内部 IP アドレスを使用するように kubeconfig ファイルを更新するには、次のコマンドを実行します。

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

DNS アドレスを使用するように kubeconfig ファイルを更新するには、次のコマンドを実行します。

gcloud container clusters get-credentials CLUSTER_NAME --dns-endpoint

CLUSTER_NAME は、使用するクラスタの名前に置き換えます。

デフォルトでは、get-credentials の実行時に endpoint フィールドに指定された IP アドレスが使用されます。

kubectl コマンドのデフォルト クラスタを設定する

以前にクラスタの kubeconfig エントリを生成している場合は、次のコマンドを実行して、kubectl の現在のコンテキストをそのクラスタに切り替えることができます。

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

次のように置き換えます。

• CLUSTER_NAME: クラスタの名前。
• CONTROL_PLANE_LOCATION: クラスタのコントロール プレーンの Compute Engine のロケーション。リージョン クラスタの場合はリージョン、ゾーンクラスタの場合はゾーンを指定します。

たとえば、2 つのクラスタ（my-cluster と my-new-cluster）からなるプロジェクトを考えてみましょう。現在のコンテキストは my-new-cluster ですが、すべての kubectl コマンドを my-cluster に対して実行する必要があるとします。現在のコンテキストを my-new-cluster から my-cluster に切り替えるには、次のコマンドを実行します。

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

特定のクラスタに個別の kubectl コマンドを実行する

特定のクラスタに対して個々の kubectl コマンドを実行するには、--cluster=CLUSTER_NAME を使用します。

たとえば、2 つのクラスタ（my-cluster と my-new-cluster）からなる環境があり、現在のコンテキストが my-cluster であるとします。アプリケーションを my-new-cluster にデプロイする必要が生じましたが、現在のコンテキストを変更したくありません。現在のコンテキストを変更せずにアプリケーションを my-new-cluster にデプロイするには、次のコマンドを実行します。

kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster

次のステップ

• GKE クラスタ内のリソースへのアクセスを認可する方法を学習する。
• GKE ワークロードから Trusted Cloud サービスに対して認証を行う。
• kubectl のクイック リファレンスを読む。
• kubectl コマンドライン ツールのトラブルシューティングを行う。