kubectl 用のクラスタ アクセスの構成

このページでは、Google Kubernetes Engine で kubectl コマンドライン ツール用にクラスタ アクセスを設定する方法について説明します。

概要

Google Cloud プロジェクト内で複数のクラスタを実行する場合は、どのクラスタが kubectl と通信するかを選択する必要があります。Kubernetes の kubeconfig ファイル内で現在のコンテキストを設定することで、kubectl 用のデフォルト クラスタを設定できます。加えて、--cluster フラグを使用すると特定のクラスタに対して kubectl コマンドを実行できます。

以降のセクションでは、kubeconfig の仕組み、kubectl のデフォルト クラスタを設定する方法、特定のクラスタに対して個別の kubectl コマンドを実行する方法について説明します。

始める前に

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

次のいずれかの方法で gcloud のデフォルトの設定を指定します。

  • gcloud init。デフォルトの設定全般を確認する場合に使用します。
  • gcloud config。プロジェクト ID、ゾーン、リージョンを個別に設定する場合に使用します。

gcloud init の使用

エラー One of [--zone, --region] must be supplied: Please specify location を受信した場合は、このセクションの内容を実施します。

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

    gcloud init

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

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

gcloud config の使用

  • デフォルトのプロジェクト ID を設定します。
    gcloud config set project project-id
  • ゾーンクラスタを使用する場合は、デフォルトのコンピューティング ゾーンを設定します。
    gcloud config set compute/zone compute-zone
  • リージョン クラスタを使用する場合は、デフォルトのコンピューティング リージョンを設定します。
    gcloud config set compute/region compute-region
  • gcloud を最新バージョンに更新します。
    gcloud components update

Kubernetes の構成ファイル

Kubernetes は、kubeconfig という名前の YAML ファイルを使用して、kubectl のクラスタ認証情報を格納します。kubeconfig には、コマンドの実行時に kubectl が参照するコンテキストのリストが含まれています。デフォルトで、このファイルは $HOME/.kube/config に保存されます。

コンテキストとは、アクセス パラメータからなるグループのことです。各コンテキストには 1 つの Kubernetes クラスタ、1 人のユーザー、1 つの名前空間が含まれます。現在のコンテキストとは、現在 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

Google Cloud Console を使用して、または別のパソコンから gcloud を使用してクラスタを作成する場合には、環境の kubeconfig が更新されません。加えて、プロジェクト チームのメンバーがそのメンバーのパソコンから gcloud を使ってクラスタを作成する場合には、メンバーの kubeconfig だけが更新されます。このようなクラスタをローカルの kubeconfig に追加するには、下記の手順に従ってください。

クラスタ エンドポイントについて

すべてのクラスタには正規のエンドポイントがあります。エンドポイントは、kubectl や他のサービスとクラスタ コントロール プレーン(マスター)との通信に使用される Kubernetes API サーバーの IP アドレスです。エンドポイントは、Cloud Console のクラスタの [詳細] タブの [エンドポイント] フィールドと、gcloud container clusters describe の出力(endpoint フィールド内)に表示されます。

gcloud container clusters get-credentials を実行すると、このコマンドで kubeconfig の更新の一部としてクラスタ エンドポイントが取得されたことが示されます。

限定公開クラスタには、privateEndpointpublicEndpoint の 2 つの固有エンドポイント値があります。前者は内部 IP アドレスで、後者は外部 IP アドレスです。限定公開クラスタに対して get-credentials を実行すると、デフォルトで外部 IP アドレスがエンドポイントとして設定されます。内部 IP をエンドポイントとして使用するには、限定公開クラスタの内部 IP アドレスを使用して kubeconfig エントリを生成するをご覧ください。

kubectl の認証について

すべての GKE クラスタは、Google Cloud ユーザー/サービス アカウント ID を受け入れるように設定されています。受け入れる際には、kubectl から提供された認証情報を検証し、ユーザー/サービス アカウント ID に関連付けられたメールアドレスを取得します。したがって、認証に成功するには、これらのアカウントの認証情報に userinfo.email OAuth スコープが含まれている必要があります。

gcloud を使用して新しいまたは既存のクラスタ用の環境の kubeconfig をセットアップするとき、gcloud は、gcloud 自体で使用されるものと同じ認証情報を kubectl に渡します。たとえば gcloud auth login を使用する場合、userinfo.email スコープを含め、そのユーザー個人の認証情報が kubectl に渡されます。これにより、GKE クラスタは kubectl クライアントを認証できます。

または、Compute Engine インスタンス上で動作しながら、Google Cloud サービス アカウントの認証情報を使用するように kubectl を設定する方法もあります。ただし、デフォルトでは、Compute Engine インスタンスによって作成される認証情報に userinfo.email スコープが含まれません。したがって、このスコープを明示的に追加する必要があります。そうするには、たとえば Compute Engine インスタンスの作成時に --scopes フラグを使用します。

ユーザーまたは Google Cloud サービス アカウントが認証された後、GKE クラスタに対してアクションを実行できるようアカウントが承認される必要もあります。認証の構成方法については、ロールベースのアクセス制御をご覧ください。

Kubernetes API サーバーへの接続時にサポートされている認証方法については、Kubernetes API サーバーの認証をご覧ください。

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

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

kubectl config current-context

kubeconfig の表示

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

kubectl config view

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

kubeconfig エントリの生成

Cloud Console から、別のコンピュータから、またはプロジェクトの別のメンバーによって作成されたクラスタに対して kubectl コマンドを実行するには、環境で kubeconfig エントリを生成する必要があります。

次のコマンドを実行して、kubeconfig エントリを生成します。

gcloud container clusters get-credentials cluster-name

ここで、cluster-name はクラスタ名です。

このコマンドを使用するには、container.clusters.get 権限が必要です。この権限を付与する最も権限の少ない IAM ロールは container.clusterViewer です。

kubeconfig エントリには次のいずれかが格納されます。

限定公開クラスタの内部 IP アドレスを使用した kubeconfig エントリの生成

get-credentials を実行するときには、--internal-ip を指定して、限定公開クラスタの内部 IP アドレスを kubeconfig に書き込むことができます。

gcloud container clusters get-credentials --internal-ip cluster-name

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

過去にクラスタ用の kubeconfig エントリを生成したことがある場合は、次に示すように実行することで、kubectl の現在のコンテキストをそのクラスタに切り替えることができます。

gcloud container clusters get-credentials

たとえば、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 コマンドを実行するには、kubeconfig に示されているクラスタの名前を --cluster フラグの引数として渡します。

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

kubectl run my-app --image gcr.io/my-bucket/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 インスタンスのスコープを変更する手順については、インスタンスのサービス アカウントの作成と有効化をご覧ください。

次のステップ