このページでは、Google Kubernetes Engine(GKE)クラスタを操作するために kubectl
コマンドライン ツールをインストールして構成する方法について説明します。
概要
kubectl
は、GKE クラスタを操作するために使用できるコマンドライン ツールです。GKE で kubectl
を使用するには、ツールをインストールして、クラスタと通信するように構成する必要があります。Google Cloud で複数のクラスタを実行する場合は、さらに kubectl
構成が必要です。
このページでは次の項目について説明します。
kubectl
の仕組みkubectl
と必要な依存関係をインストールする方法kubectl
のデフォルト クラスタを設定する方法- 特定のクラスタに対して
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
など)を使用してインストールできます。
gcloud
kubectl
コンポーネントをインストールします。gcloud components install kubectl
kubectl
がインストールされていることを確認します。kubectl version
apt
cloud-sdk
リポジトリがあることを確認します。grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"
出力は次のようになります。
deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main
kubectl
コンポーネントをインストールします。apt-get update apt-get install -y kubectl
kubectl
が最新バージョンであり、インストール済みであることを確認します。kubectl version --short --client
yum
cloud-sdk
リポジトリがあることを確認します。yum repolist | grep "google-cloud-sdk"
出力は次のようになります。
google-cloud-sdk Google Cloud SDK 2,205
kubectl
コンポーネントをインストールします。yum install -y kubectl
kubectl
がインストールされていることを確認します。kubectl version --short --client
必要なプラグインをインストールする
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
gke-gcloud-auth-plugin
バイナリをインストールします。
gcloud components install gke-gcloud-auth-plugin
apt
gke-gcloud-auth-plugin
バイナリをインストールします。
apt-get install google-cloud-sdk-gke-gcloud-auth-plugin
yum
gke-gcloud-auth-plugin
バイナリをインストールします。
yum install google-cloud-sdk-gke-gcloud-auth-plugin
gke-gcloud-auth-plugin
バイナリのインストールを確認します。
gke-gcloud-auth-plugin
バイナリのバージョンを確認します。gke-gcloud-auth-plugin --version
プラグインを使用するように
kubectl
構成を更新します。gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
次のように置き換えます。
CLUSTER_NAME
: クラスタの名前。COMPUTE_REGION
: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE
を使用します。
構成を確認します。
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
のクラスタ情報を保存する
Google 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 \
--region=CLUSTER_REGION
次のように置き換えます。
CLUSTER_NAME
: クラスタの名前。COMPUTE_REGION
: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE
を使用します。
限定公開クラスタの内部 IP アドレスを使用して kubeconfig
エントリを生成する
すべてのクラスタには正規のエンドポイントがあります。エンドポイントは、kubectl
や他のサービスとクラスタ コントロール プレーンとの通信に使用される Kubernetes API サーバーを公開します。
限定公開クラスタには、2 つの別個のエンドポイント IP アドレス(内部 IP アドレスである privateEndpoint
と外部 IP アドレスである publicEndpoint
)があります。
endpoint
フィールドは、エンドポイントへのパブリック アクセスが無効になっていない限り、外部 IP アドレスを参照します。無効の場合、プライベート IP アドレスが使用されます。
限定公開クラスタで、エンドポイントとして内部 IP アドレスを使用する場合は、次のコマンドを実行します。
gcloud container clusters get-credentials CLUSTER_NAME --internal-ip
CLUSTER_NAME
は、使用するクラスタの名前に置き換えます。
get-credentials
を実行すると、endpoint
フィールドに指定された IP がデフォルトで使用されます。
kubectl
コマンドのデフォルト クラスタを設定する
以前にクラスタの kubeconfig エントリを生成している場合は、次のコマンドを実行して、kubectl
の現在のコンテキストをそのクラスタに切り替えることができます。
gcloud container clusters get-credentials CLUSTER_NAME \
--region=COMPUTE_REGION
次のように置き換えます。
CLUSTER_NAME
: クラスタの名前。COMPUTE_REGION
: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE
を使用します。
たとえば、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
トラブルシューティング
その他のトラブルシューティングについては、一般的な問題のトラブルシューティングをご覧ください。
認証スコープが不十分
gcloud container clusters get-credentials
を実行すると、次のエラーが表示されます。
ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.
cloud-platform
スコープのない Compute Engine VM から Kubernetes Engine API にアクセスしようとすると、このエラーが発生します。Compute Engine VM インスタンスのスコープを変更する手順については、インスタンスのサービス アカウントの作成と有効化をご覧ください。
エラー: executable gke-gcloud-auth-plugin not found
kubectl
または GKE を操作するカスタム クライアントの実行を試みている間に、次のエラーが発生した場合は、インストール手順の説明に従って gke-gcloud-auth-plugin
をインストールします。次のようなエラー メッセージが返されます。
- エラーサンプル
Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found
It looks like you are trying to use a client-go credential plugin that is not installed.
To learn more about this feature, consult the documentation available at:
https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins
Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.
- エラーサンプル
Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory
エラー: panic: no Auth Provider found for name gcp
エラー no Auth Provider found for name "gcp"
は、その機能で説明されているように、kubectl
またはカスタム Kubernetes クライアントが Kubernetes client-go
バージョン 1.26 以降を使用してビルドされている場合に受信されます。この問題は、次の手順で解決できます。
インストール手順の説明に沿って
gke-gcloud-auth-plugin
をインストールします。gcloud components update
を使用して gcloud CLI を最新バージョンに更新します。kubeconfig
ファイルを更新します。gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
次のように置き換えます。
CLUSTER_NAME
: クラスタの名前。COMPUTE_REGION
: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE
を使用します。
警告: the gcp auth plugin is deprecated, use gcloud instead
この警告メッセージは、gke-gcloud-auth-plugin
をインストールして GKE クラスタに対して kubectl
コマンドを実行した後に表示される場合があります。このメッセージは、クライアントのバージョンが 1.26 より前の場合に表示されます。
代わりに gke-gcloud-auth-plugin
認証プラグインを使用するようにクライアントに指示するには、次の操作を行います。
テキスト エディタでシェル ログイン スクリプトを開きます。
Bash
vi ~/.bashrc
Zsh
vi ~/.zshrc
PowerShell を使用している場合は、この手順をスキップします。
次の環境変数を設定します。
Bash
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
Zsh
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
PowerShell
[Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')
環境でこの変数を適用します。
Bash
source ~/.bashrc
Zsh
source ~/.zshrc
PowerShell
ターミナルを終了し、新しいターミナル セッションを開きます。
gcloud CLI を更新します。
gcloud components update
クラスタに対する認証:
gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
次のように置き換えます。
CLUSTER_NAME
: クラスタの名前。COMPUTE_REGION
: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE
を使用します。
次のステップ
- GKE クラスタ内のリソースへのアクセスを認可する方法を学習する。
- サービス アカウントを使用して Google Cloud サービスの認証を行う方法を学習する。
kubectl
のクイック リファレンスを読む。
使ってみる
Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオで GKE のパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
GKE の無料トライアル