kubectl コマンドライン ツールのトラブルシューティング

Autopilot Standard

---

このページでは、Google Kubernetes Engine（GKE）で作業中に発生する kubectl コマンドライン ツールの問題を解決する方法について説明します。一般的なアドバイスについては、Kubernetes ドキュメントの kubectl のトラブルシューティングをご覧ください。

認証と認可のエラー

kubectl コマンドライン ツールのコマンドの使用時に認証と承認に関連するエラーが発生した場合は、次のセクションで解決策を確認してください。

エラー: 401 (Unauthorized)

GKE クラスタに接続すると、HTTP ステータス コード 401 (Unauthorized) の認証 / 認可エラーが発生することがあります。この問題は、ローカル環境から GKE クラスタで kubectl コマンドを実行しようとしたときに発生することがあります。詳細については、問題: 認証と承認のエラーをご覧ください。

エラー: Insufficient authentication scopes

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 にアクセスしようとすると、このエラーが発生します。

このエラーを解決するには、不足している cloud-platform スコープを付与します。Compute Engine VM インスタンスのスコープを変更する手順については、Compute Engine のドキュメントでインスタンスのサービス アカウントの作成と有効化をご覧ください。

エラー: Executable gke-gcloud-auth-plugin not found

kubectl コマンドまたは GKE を操作するカスタム クライアントの実行中に、次のようなエラー メッセージが表示されることがあります。

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

この問題を解決するには、必要なプラグインをインストールするの説明に従って gke-gcloud-auth-plugin をインストールします。

エラー: No auth provider found

kubectl またはカスタム Kubernetes クライアントが Kubernetes client-go バージョン 1.26 以降を使用してビルドされている場合、次のエラーが発生します。

no Auth Provider found for name "gcp"

この問題を解決するには、次の操作を行います。

1. 必要なプラグインをインストールするの説明に従って gke-gcloud-auth-plugin をインストールします。

2. gcloud CLI を最新バージョンに更新します。

   gcloud components update
   

3. 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 コマンドを実行すると、次の警告メッセージが表示されることがあります。

WARNING: the gcp auth plugin is deprecated in v1.22+, unavailable in v1.25+; use gcloud instead.

このメッセージは、クライアントのバージョンが 1.26 より前の場合に表示されます。

この問題を解決するには、代わりに gke-gcloud-auth-plugin 認証プラグインを使用するようにクライアントに指示します。

1. テキスト エディタでシェル ログイン スクリプトを開きます。

   Bash

   vi ~/.bashrc

   Zsh

   vi ~/.zshrc

   PowerShell を使用している場合は、この手順をスキップします。

2. 次の環境変数を設定します。

   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')
   

3. 環境でこの変数を適用します。

   Bash

   source ~/.bashrc

   Zsh

   source ~/.zshrc
   

   PowerShell

   ターミナルを終了し、新しいターミナル セッションを開きます。

4. gcloud CLI を更新します。

   gcloud components update
   

5. クラスタに対する認証:

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

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

   • CLUSTER_NAME: クラスタの名前。
   • COMPUTE_REGION: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE を使用します。

問題: kubectl コマンドが見つからない

kubectl コマンドが見つからないというメッセージが表示された場合は、kubectl バイナリを再インストールして $PATH 環境変数を設定します。

1. kubectl バイナリをインストールします。

   gcloud components update kubectl
   

2. $PATH 環境変数の変更を求めるメッセージが表示されたら、「y」と入力して続行します。この変数を変更すると、完全なパスを入力せずに kubectl コマンドを使用できます。

   または、~/.bashrc（macOS では ~/.bash_profile）など、シェルの環境変数の格納場所に次の行を追加します。

   export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/
   

3. 次のコマンドを実行して、更新したファイルを読み込みます。次の例では、.bashrc を使用しています。

   source ~/.bashrc
   

   macOS を使用している場合は、.bashrc ではなく ~/.bash_profile を使用します。

問題: kubectl コマンドを実行すると「接続は拒否されました」というエラーが表示される

kubectl コマンドが「接続は拒否されました」というエラーを返す場合は、次のコマンドを使用してクラスタ コンテキストを設定する必要があります。

gcloud container clusters get-credentials CLUSTER_NAME

CLUSTER_NAME は、使用するクラスタの名前に置き換えます。クラスタ名に何を入力すればよいかわからない場合は、次のコマンドを使用してクラスタを一覧取得します。

gcloud container clusters list

エラー: kubectl command timed out

クラスタを作成してクラスタに kubectl コマンドを実行したときに、kubectl コマンドがタイムアウトすると、次のようなエラーが表示されます。

• Unable to connect to the server: dial tcp IP_ADDRESS: connect: connection timed out
• Unable to connect to the server: dial tcp IP_ADDRESS: i/o timeout。

これらのエラーは、kubectl がクラスタ コントロール プレーンと通信できないことを示しています。

この問題を解決するには、クラスタが設定されているコンテキストを確認して設定し、クラスタとの接続性を確保します。

1. $HOME/.kube/config に移動するか、kubectl config view コマンドを実行して、構成ファイルにクラスタ コンテキストとコントロール プレーンの外部 IP アドレスが含まれていることを確認します。

2. クラスタの認証情報を設定します。

   gcloud container clusters get-credentials CLUSTER_NAME \
       --location=COMPUTE_LOCATION \
       --project=PROJECT_ID
   

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

   • CLUSTER_NAME: クラスタの名前。
   • COMPUTE_LOCATION: Compute Engine のロケーション。
   • PROJECT_ID: クラスタが作成されたプロジェクトの ID。

3. クラスタで承認済みネットワークを有効にしている場合は、既存の承認済みネットワークのリストに、接続元のマシンの送信 IP が含まれていることを確認します。承認済みネットワークはコンソールまたは次のコマンドで確認できます。

   gcloud container clusters describe CLUSTER_NAME \
       --location=COMPUTE_LOCATION \
       --project=PROJECT_ID \
       --format "flattened(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetwork
   sConfig.cidrBlocks[])"
   

   上記のコマンドの出力で、マシンの送信 IP が承認済みネットワークのリストにない場合は、次のいずれかの操作を行います。

   • コンソールを使用している場合は、外部エンドポイントのないクラスタのコントロール プレーンに到達できないの手順に沿って操作します。
   • Cloud Shell から接続している場合は、Cloud Shell を使用した外部エンドポイントが無効になっているクラスタへのアクセスの説明に従います。

エラー: kubectl commands return failed to negotiate an api version

kubectl コマンドが failed to negotiate an API version エラーを返す場合は、kubectl に認証情報が設定されていることを確認する必要があります。

gcloud auth application-default login

問題: kubectl logs、attach、exec、port-forward コマンドが応答不能になった

kubectl logs、attach、exec、または port-forward コマンドが応答しなくなった場合、通常は API サーバーがノードと通信できなくなっています。

まず、クラスタにノードが存在するかどうか確認します。クラスタ内のノードの数を減らして 0 にした場合、コマンドは機能しません。この問題を解決するには、クラスタのサイズを変更してノードを 1 つ以上配置します。

クラスタにノードが 1 つ以上ある場合は、SSH トンネルまたは Konnectivity プロキシ トンネルを使用してセキュア通信を実現しているかどうかを確認します。以降のセクションでは、各サービスに固有のトラブルシューティング手順について説明します。

• SSH
• Konnectivity プロキシ

SSH の問題のトラブルシューティング

SSH を使用している場合、GKE は SSH 公開鍵ファイルを Compute Engine プロジェクトのメタデータに保存します。Google 提供のイメージを使用するすべての Compute Engine VM はプロジェクトの共通メタデータとインスタンスのメタデータを定期的にチェックし、承認済みユーザーの VM のリストに追加する SSH 認証鍵がないかどうかを確認します。また、GKE はコントロール プレーンの IP アドレスからクラスタ内の各ノードへの SSH アクセスを許可するファイアウォール ルールを Compute Engine ネットワークに追加します。

次の設定では、SSH 通信で問題が発生する可能性があります。

• ネットワークのファイアウォール ルールで、コントロール プレーンからの SSH アクセスが許可されていない。

  すべての Compute Engine ネットワークは default-allow-ssh というファイアウォール ルールを使用して作成されます。このルールでは有効な秘密鍵を持つすべての IP アドレスからの SSH アクセスが許可されます。また、GKE は一般公開クラスタごとに gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh 形式の SSH ルールも挿入します。このルールでは、クラスタのコントロール プレーンからクラスタのノードへの SSH アクセスが個別に許可されます。

  どちらのルールも存在しない場合、コントロール プレーンは SSH トンネルを開くことができません。

  これが問題の原因であることを確認するには、構成にこれらのルールが含まれているかどうかを確認します。

  この問題を解決するには、クラスタのすべてのノードにあるタグを特定し、コントロール プレーンの IP アドレスからそのタグを持つ VM へのアクセスを許可するファイアウォール ルールを再度追加します。

• プロジェクトの ssh-keys 用の共通メタデータ エントリがいっぱいになっている。

  プロジェクトの ssh-keys というメタデータ エントリが最大サイズの上限に近い場合、GKE は SSH トンネルを開くための独自の SSH 認証鍵を追加できません。

  これが問題かどうかを確認するには、ssh-keys のリスト内の長さを確認します。プロジェクトのメタデータを表示するには、次のコマンドを実行します。必要に応じて、--project フラグを含めます。

  gcloud compute project-info describe [--project=PROJECT_ID]
  

  この問題を解決するには、不要になった SSH 認証鍵を削除します。

• クラスタ内の VM でメタデータ フィールドにキー ssh-keys を設定している。

  VM のノード エージェントではプロジェクト全体の SSH 認証鍵よりもインスタンスごとの SSH 認証鍵が優先されるため、クラスタのノードで SSH 認証鍵を個別に設定している場合、ノードはプロジェクトのメタデータ内にあるコントロール プレーンの SSH 認証鍵を無視します。

  これが問題であることを確認するには、gcloud compute instances describe VM_NAME を実行して、メタデータで ssh-keys フィールドを探します。

  この問題を解決するには、インスタンスのメタデータからインスタンスごとの SSH 認証鍵を削除します。

Konnectivity プロキシの問題のトラブルシューティング

次のシステム Deployment を確認して、クラスタが Konnectivity プロキシを使用しているかどうかを判断できます。

kubectl get deployments konnectivity-agent --namespace kube-system

クラスタが Konnectivity プロキシを使用している場合、出力は次のようになります。

NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
konnectivity-agent   3/3     3            3           18d

Konnectivity プロキシを使用していることを確認したら、Konnectivity エージェントに必要なファイアウォール アクセス権があることと、ネットワーク ポリシーが正しく設定されていることを確認します。

必要なファイアウォール アクセスを許可する

ネットワークのファイアウォール ルールで、次のポートへのアクセスが許可されていることを確認します。

• コントロール プレーン ポート: クラスタの作成時に、Konnectivity エージェントはポート 8132 でコントロール プレーンとの接続を確立します。kubectl コマンドを実行すると、API サーバーはこの接続を使用してクラスタと通信します。ポート 8132 でクラスタ コントロール プレーンへの下り（外向き）トラフィックを許可していることを確認します（API サーバーは 443 を使用します）。下り（外向き）アクセスを拒否するルールがある場合は、ルールを変更するか、例外を作成する必要があります。

• kubelet ポート: Konnectivity エージェントはクラスタノードにデプロイされるシステム Pod であるため、ファイアウォール ルールで次の種類のトラフィックを許可するようにしてください。

  • Pod 範囲からのワークロードへの受信トラフィック（ポート 10250）。
  • Pod 範囲からの送信トラフィック。

  ファイアウォール ルールでこのタイプのトラフィックが許可されていない場合は、ルールを変更します。

ネットワーク ポリシーを調整する

クラスタのネットワーク ポリシーにより、kube-system Namespace から workload Namespace への上り（内向き）トラフィックがブロックされている場合、Konnectivity プロキシで問題が発生する可能性があります。

これらの機能はクラスタの正常な動作に必須ではありません。クラスタのネットワークを外部アクセスから完全に遮断した場合、これらのような機能が動作しなくなることに注意してください。

これが問題の原因であることを確認するには、次のコマンドを実行して、影響を受ける Namespace のネットワーク ポリシーを見つけます。

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

この問題を解決するには、ネットワーク ポリシーの spec.ingress フィールドに次の行を追加します。

- from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: kube-system
    podSelector:
      matchLabels:
        k8s-app: konnectivity-agent

次のステップ

さらにサポートが必要な場合は、Cloud カスタマーケアにお問い合わせください。