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"

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

必要なプラグインをインストールするの説明に従って gke-gcloud-auth-plugin をインストールします。
gcloud CLI を最新バージョンに更新します。
```
gcloud components update
```
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 認証プラグインを使用するようにクライアントに指示します。

テキストエディタでシェルログインスクリプトを開きます。
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 を使用します。

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

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

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

または、~/.bashrc（macOS では ~/.bash_profile）など、シェルの環境変数の格納場所に次の行を追加します。
```
export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/
```
次のコマンドを実行して、更新したファイルを読み込みます。次の例では、.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 がクラスタコントロールプレーンと通信できないことを示しています。

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

$HOME/.kube/config に移動するか、kubectl config view コマンドを実行して、構成ファイルにクラスタコンテキストとコントロールプレーンの外部 IP アドレスが含まれていることを確認します。
クラスタの認証情報を設定します。
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID
```
次のように置き換えます。
- CLUSTER_NAME: クラスタの名前。
- COMPUTE_LOCATION: Compute Engine のロケーション。
- PROJECT_ID: クラスタが作成されたプロジェクトの ID。
クラスタが限定公開 GKE クラスタの場合は、既存の承認済みネットワークのリストに、接続元のマシンの送信 IP が含まれていることを確認します。承認済みネットワークはコンソールまたは次のコマンドで確認できます。
```
gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(masterAuthorizedNetworksConfig.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 プロキシで問題が発生する可能性があります。

ネットワークのファイアウォールルールで、Konnectivity エージェントのコントロールプレーンへのアクセスが許可されていない。

クラスタの作成時に、Konnectivity エージェント Pod がポート 8132 でコントロールプレーンへの接続を確立し、維持している。kubectl コマンドのいずれかが実行されると、API サーバーはこの接続を使用してクラスタと通信します。

ネットワークのファイアウォールルールに下り（外向き）拒否ルールが含まれている場合、エージェントが接続できなくなる可能性があります。

これが問題の原因であることを確認するには、ネットワークのファイアウォールルールで下り（外向き）拒否ルールが含まれているかどうかを確認します。

この問題を解決するには、ポート 8132 でクラスタコントロールプレーンへの下り（外向き）トラフィックを許可します（API サーバーは 443 を使用します）。
クラスタのネットワークポリシーにより、kube-system Namespace から workload Namespace への上り（内向き）トラフィックがブロックされています。

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

これが問題の原因であることを確認するには、次のコマンドを実行して、影響を受ける 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 カスタマーケアにお問い合わせください。

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

認証と認可のエラー

エラー: 401 (Unauthorized)

エラー: Insufficient authentication scopes

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

エラー: No auth provider found

エラー: The gcp auth plugin is deprecated, use gcloud instead

Bash

Zsh

Bash

Zsh

PowerShell

Bash

Zsh

PowerShell

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

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

エラー: kubectl command timed out

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

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

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

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

次のステップ

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

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

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

エラー: `kubectl` command timed out

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

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