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

このページでは、Google Kubernetes Engine(GKE)クラスタを操作するために kubectl コマンドライン ツールをインストールして構成する方法について説明します。

概要

kubectl は、GKE クラスタを操作するために使用できるコマンドライン ツールです。GKE で kubectl を使用するには、ツールをインストールしてクラスタと通信するように構成する必要があります。Google Cloud で複数のクラスタを動作させる場合は、さらに kubectl 構成が必要です。

このページでは、次の項目について説明します。

始める前に

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

  • Google Kubernetes Engine API が有効になっていることを確認します。
  • Google Kubernetes Engine API の有効化
  • Google Cloud CLI がインストールされていることを確認します。
  • 次のいずれかの方法で、プロジェクトにデフォルトの Google Cloud CLI 設定をセットアップします。
    • プロジェクトのデフォルトの設定全般を確認する場合は、gcloud init を使用します。
    • gcloud config を使用して、プロジェクト ID、ゾーン、リージョンを個別に設定します。

    gcloud init

    1. gcloud init を実行して、次の操作を行います。

      gcloud init

      リモート サーバーで SSH を使用している場合は、--console-only フラグを指定して、コマンドがブラウザを起動しないようにします。

      gcloud init --console-only
    2. Google Cloud アカウントを使用できるように、gcloud CLI の承認手順を行います。
    3. 新しい構成を作成するか、既存の構成を選択します。
    4. Google Cloud プロジェクトを選択します。
    5. デフォルトの Compute Engine ゾーンを選択します。
    6. デフォルトの Compute Engine リージョンを選択します。

    gcloud config

    1. デフォルトのプロジェクト ID を設定します。
      gcloud config set project PROJECT_ID
    2. デフォルトの Compute Engine リージョン(例: us-central1)を設定します。
      gcloud config set compute/region COMPUTE_REGION
    3. デフォルトの Compute Engine ゾーン(例: us-central1-c)を設定します。
      gcloud config set compute/zone COMPUTE_ZONE
    4. gcloud を最新バージョンに更新します。
      gcloud components update

    デフォルトの場所を設定することで、gcloud CLI のエラー(One of [--zone, --region] must be supplied: Please specify location など)を防止できます。

kubectl をインストールします。

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

gcloud

  1. kubectl コンポーネントをインストールします。

    gcloud components install kubectl
    
  2. kubectl がインストールされていることを確認します。

    kubectl version
    

apt

  1. 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
    
  2. kubectl コンポーネントをインストールします。

    apt-get update
    apt-get install -y kubectl
    
  3. kubectl が最新バージョンであり、インストール済みであることを確認します。

    kubectl version --short --client
    

yum

  1. cloud-sdk リポジトリがあることを確認します。

    yum repolist | grep "google-cloud-sdk"
    

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

    google-cloud-sdk    Google Cloud SDK    2,205
    
  2. kubectl コンポーネントをインストールします。

    yum install -y kubectl
    
  3. kubectl がインストールされていることを確認します。

    kubectl version --short --client
    

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

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

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

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

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

gke-gcloud-auth-plugin --version

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

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

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 バイナリのインストールを確認します。

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

    gke-gcloud-auth-plugin --version
    
  2. プラグインを使用するように kubectl 構成を更新します。

    gcloud container clusters get-credentials CLUSTER_NAME
    

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

  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 人のユーザー、オプションのデフォルトの名前空間が含まれます。kubectl は、コマンドの実行時にコンテキストを参照します。

kubectl を構成するため、次の作業を完了します。

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

kubeconfig を表示

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

kubectl config view

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

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

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

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

gcloud container clusters create 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 を使用してメンバー自身のパソコンからクラスタを作成する場合、そのメンバーの kubeconfig は更新されますが、あなたのファイルは更新されません。kubeconfig エントリには次のいずれかが格納されます。

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

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

gcloud container clusters get-credentials CLUSTER_NAME

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

注: ターゲット クラスタがデフォルトのゾーンまたはリージョンで実行されていない場合、またはデフォルトのゾーンまたはリージョンを設定しなかった場合は、コマンドにリージョン(--region=REGION)またはゾーン(--zone=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

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

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

gcloud container clusters get-credentials my-cluster

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

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

たとえば、2 つのクラスタ(my-clustermy- 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 インスタンスのスコープを変更する手順については、インスタンスのサービス アカウントの作成と有効化をご覧ください。

エラー: 実行可能な gke-gcloud-auth-plugin が見つかりません

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.25 以降を使用してビルドされている場合に受信されます。この問題は、次の手順で解決できます。

  1. インストール手順の説明に沿って gke-gcloud-auth-plugin をインストールします。

  2. gcloud components update を使用して gcloud CLI を最新バージョンに更新します。

  3. kubeconfig ファイルを更新します。

    gcloud container clusters get-credentials CLUSTER_NAME
    

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

次のステップ

使ってみる

Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオで GKE のパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

GKE の無料トライアル