PerfectScale

kubectl debug:PodとNodeをトラブルシューティングする完全ガイド

kubectl debugは、Kubernetesクラスターで実行中のワークロードをトラブルシューティングするための組み込みコマンドです。シェルやネットワークユーティリティといった基本的なデバッグツールを持たないコンテナ(最小構成の「distroless」イメージでよくあるケース)を調査する場合や、Podがクラッシュループに陥っている場合に使用します。

このページはEnglish、Deutsch、Español、Français、Italiano、Portuguêsでもご覧いただけます。

Sep 25, 202616 min read

About Josh Palmer

Head of Content

I'm Josh Palmer, Head of Content at DoiT, where I split my time across multiple business units including DoiT Cloud Intelligence, PerfectScale (Kubernetes cost optimization), and SELECT (Snowflake, Databricks, and BigQuery cost optimization). Before DoiT, I spent four and a half years at OnBoard building content for a board intelligence platform used by 6,000+ organizations, and before that, two years as Content Marketing Manager at Zylo, a SaaS management platform.

My personal page

要点まとめ

kubectl debug はkubectlに組み込まれた対話型トラブルシューティングコマンドです。実行中のPodへのエフェメラルコンテナの追加、設定を変更したPodのコピーの作成、Node上での特権を付与できるPodの起動という3つの方法で動作します。
kubectl logs や kubectl describe だけでは不十分な場合に使用します。例えば、シェルを持たないdistrolessコンテナや、CrashLoopBackOff 状態から抜け出せないPodなどです。
基本構文は kubectl debug (POD | TYPE/NAME) [flags] で、最もよく使われるのは kubectl debug my-pod -it --image=busybox です。
デバッグセッションはデバッグプロファイル(--profile、現行のkubectlリリースではデフォルトは general)に従って実行され、これによってデバッグコンテナに付与される権限や名前空間が制御されます。デフォルトでは特権モードでは実行されません。
ベストプラクティス:まずlogs/describe/eventsから始め、エフェメラルコンテナは調査のみに使用し(実行中のワークロードへのパッチ適用には使わない)、--copy-to で作成したPodは作業後に必ず削除しましょう。

kubectl debugとは?

kubectl debug は、Kubernetesクラスターで実行中のワークロードをトラブルシューティングするための組み込みコマンドです。主に、シェルやネットワークユーティリティといった基本的なデバッグツールを持たないコンテナ(最小構成の「distroless」イメージでよくあるケース)を調査する場合や、Podがクラッシュループに陥っている場合に使用します。

よく使うコマンド:

詳細な構文については、Kubernetes公式のkubectl debugドキュメントを参照してください。

シナリオ	コマンド例
実行中のPodにシェルを追加	`kubectl debug -it <pod-name> --image=busybox`
プロセス名前空間を共有	`kubectl debug -it <pod-name> --image=busybox --target=<container-name>`
クラッシュするPodをデバッグ	`kubectl debug <pod-name> -it --copy-to=debug-pod --image=ubuntu -- /bin/bash`
クラスターのNodeをデバッグ	`kubectl debug node/<node-name> -it --image=ubuntu`

主なフラグ:

-i / -t(通常は -it として組み合わせて使用):新しいコンテナのコンソールに対話型TTYを即座にアタッチします。
--target:プロセス名前空間を共有するPod内のコンテナを指定します。これにより、ps などのツールで対象コンテナの実行中プロセスを確認できます。
--copy-to:トラブルシューティング用に、元のPodのコピーとして作成する新しいPodの名前を指定します。
--profile:デバッグコンテナに付与するセキュリティコンテキストと名前空間を制御するデバッグプロファイル(general、baseline、restricted、netadmin、sysadmin)を選択します。現行のkubectlリリースではデフォルトは general です。

kubectl debugのユースケース

対象リソースに応じて、このコマンドは主に3つの方法で動作します。

エフェメラルコンテナ: 任意のイメージ(busybox や ubuntu など)の一時的なコンテナを、実行中の既存Podに追加します。Podを再起動せずに診断を実行できます。
Podのコピー: コンテナイメージやコマンドなどの属性を変更したPodのコピーを作成します。起動時にクラッシュして実行中にアクセスできないPodのトラブルシューティングに便利です。
Nodeのデバッグ: Nodeのホスト名前空間で実行され、Nodeのルートファイルシステムをマウントする新しいPodを作成します。クラスターのNode上で直接インフラレベルのトラブルシューティングを行う際に使用します。

kubectl debugによる3つのデバッグ方法

kubectl debugの構文

kubectl debug コマンドは、Podへのエフェメラルコンテナの追加、トラブルシューティング用のPodコピーの作成、Nodeのデバッグなど、複数のデバッグワークフローをサポートしています。

kubectl debug (POD | TYPE/NAME) [flags]

よく使われるフラグオプションは以下のとおりです。

オプション	説明
`-it`	対話型のターミナルセッションを開始
`--image`	デバッグに使用するコンテナイメージを指定
`--target`	Pod内の特定のコンテナを対象に指定
`--copy-to`	デバッグ用にPodのコピーを作成
`--share-processes`	コピーしたPodでプロセス名前空間の共有を有効化
`--profile`	デバッグコンテナのセキュリティコンテキストと名前空間を設定するデバッグプロファイルを選択(デフォルトは `general`)
`node/NODE_NAME`	Nodeに対するデバッグセッションを開始

kubectl debugの主なコマンド

1. 実行中のPodにシェルを追加する

この例では、既存のPodにシェル付きのエフェメラルコンテナを追加します。デバッグコンテナは元のコンテナに変更を加えることなく、その横で実行されます。

kubectl debug my-pod -it --image=busybox

Podに複数のコンテナが含まれる場合は、特定のコンテナを対象に指定できます。

kubectl debug my-pod -it --image=busybox --target=my-container

--target フラグは指定したコンテナとプロセス名前空間を共有するため、デバッグコンテナから対象コンテナの実行中プロセスを確認(および操作)できます。

2. プロセス名前空間の共有

デフォルトでは、エフェメラルコンテナから他のコンテナで実行中のプロセスが見えない場合があります。--share-processes フラグを使うと、コピーしたPodでプロセス名前空間の共有が有効になり、コンテナをまたいで実行中のプロセスを調査できます。

kubectl debug my-pod --copy-to=my-pod-debug --share-processes -it --image=busybox

プロセスレベルの問題を調査する際に、ps、top、strace といったツールと組み合わせて活用できます。

3. クラッシュするPodのデバッグ

コンテナが繰り返しクラッシュする場合、調査する前に終了してしまうことがあります。--copy-to オプションを使うと、設定を変更したPodのコピーを作成してトラブルシューティングできます。

kubectl debug my-pod --copy-to=my-pod-debug -it --image=ubuntu

元のPodに影響を与えることなく、マウントされたボリューム、環境変数、設定ファイル、アプリケーションバイナリなどを調査できます。

4. クラスターNodeのデバッグ

kubectl debug は、NodeレベルのトラブルシューティングのためにNodeにアタッチされた一時的なPodを作成することもできます。kubeletの問題、ネットワークの問題、ディスク使用量の調査に便利です。

kubectl debug node/my-node -it --image=ubuntu

デフォルトでは、Nodeのデバッグは general プロファイルを使用します。デバッグPodはNodeのホスト名前空間(hostPID、hostNetwork、hostIPC)で実行され、Nodeのルートファイルシステムを /host にマウントしますが、特権セキュリティコンテキストでは実行されません。この状態から、ホストのファイルシステムやシステムサービスを調査できます。カーネルモジュールのロードやrawソケットの使用など、Node上で完全なルートレベル(特権)アクセスが必要な場合は、--profile=sysadmin で明示的に指定してください。

kubectl debug、kubectl logs、kubectl describeの違い

kubectl debug、kubectl logs、kubectl describe はいずれもトラブルシューティング用のコマンドですが、それぞれ目的が異なります。kubectl logs はアプリケーションの出力を取得し、kubectl describe はKubernetesリソースの詳細とイベントを表示し、kubectl debug はリアルタイムに調査するための対話型アクセスを提供します。

コマンド	主な目的	典型的なユースケース
`kubectl logs`	コンテナのログを表示	アプリケーションの出力とエラーメッセージの確認
`kubectl describe`	リソースの状態とイベントを確認	スケジューリング、設定、ライフサイクルの問題の診断
`kubectl debug`	対話型デバッグの実行	実行中のコンテナ、Node、ネットワークの問題の調査

kubectl logs

kubectl logs コマンドは、コンテナのstdoutとstderrの出力を表示します。アプリケーションのクラッシュ、起動失敗、ランタイムエラーの特定によく使われます。

kubectl logs my-pod

複数コンテナのPodでは、コンテナ名を指定します。

kubectl logs my-pod -c app-container

このコマンドはPodを変更したり新しいコンテナを作成したりしないため、軽量かつ安全です。

kubectl describe

kubectl describe コマンドは、ラベル、コンディション、マウントされたボリューム、最近のイベントなど、Kubernetesリソースに関する詳細な情報を提供します。

kubectl describe pod my-pod

このコマンドは、次のような問題の診断に役立ちます。

スケジューリングの失敗
イメージのpullエラー
probeの失敗
リソース制約
CrashLoopBackOffイベント

kubectl logs とは異なり、アプリケーションの出力ではなくKubernetesオブジェクトの状態に焦点を当てています。

kubectl debug

kubectl debug コマンドは、エフェメラルコンテナのアタッチや一時的なデバッグPodの作成により、対話型のトラブルシューティングを可能にします。

kubectl debug my-pod -it --image=busybox

ログやdescribeの情報だけでは不十分な場合に有効です。例えば、次のようなことができます。

ネットワーク接続の確認
ファイルシステムの内容の調査
プロセス調査ツールの実行
シェルを持たない最小構成コンテナのデバッグ
Nodeレベルの問題の調査

一時的なデバッグ環境を作成するため、kubectl debug は本番ワークロードへの変更を最小限に抑えながら、他のコマンドよりも深いアクセスを提供します。

実践的なkubectl debugの活用例

ネットワーク接続のデバッグ

デバッグコンテナを使って、Podのネットワーク名前空間からDNS、サービスディスカバリ、外部へのネットワークアクセスをテストします。

kubectl debug my-pod -it --image=busybox --target=my-container

デバッグコンテナ内で、次のようなコマンドを実行します。

nslookup kubernetes.default
wget -qO- http://my-service.default.svc.cluster.local
ping 10.0.0.10

アプリケーションのイメージに nslookup、curl、ping などのツールが含まれていない場合に便利です。

CrashLoopBackOff状態のPodのデバッグ

再起動を繰り返すPodには、調査用のコピーを作成しましょう。これにより、元のワークロードを変更せずに済みます。

kubectl debug my-pod --copy-to=my-pod-debug -it --image=ubuntu

コピーしたPodから、環境変数、マウントされたファイル、設定、ネットワークアクセスを調査できます。

env
ls -la /etc/config
cat /etc/config/app.conf

ファイルの欠落、不正な環境変数の値、ランタイム依存関係の特定に役立ちます。

プロセス名前空間の共有によるデバッグ

Pod内の別のコンテナのプロセスを調査する必要がある場合は、プロセス名前空間の共有を使用します。

kubectl debug my-pod \
  --copy-to=my-pod-debug \
  --share-processes \
  -it \
  --image=ubuntu

デバッグコンテナ内で、実行中のプロセスを確認します。

ps aux
top

スタックしたプロセス、ゾンビプロセス、想定外の子プロセスの調査に便利です。

カスタムイメージを使ったデバッグ

標準的なイメージに必要なツールが含まれていない場合は、カスタムのデバッグイメージを使用します。

kubectl debug my-pod -it \
  --image=my-registry.example.com/debug-tools:latest \
  --target=my-container

カスタムイメージには、curl、dig、tcpdump、strace、データベースクライアントなどのツールを含めることができます。これにより、本番イメージを小さく保ちながら、必要なときにはより深いトラブルシューティングが可能になります。

kubectl debugのベストプラクティス

このコマンドを使用する際に押さえておきたいプラクティスを紹介します。

1. Podに入る前にオブザーバビリティから始める

対話型のデバッグセッションを開始する前に、kubectl logs、kubectl describe、イベント、メトリクス、トレースを活用しましょう。これらのツールはより高速かつ安全で、多くの場合これだけで問題を特定できます。

kubectl logs my-pod
kubectl describe pod my-pod
kubectl get events --sort-by=.metadata.creationTimestamp

これにより、問題の原因がアプリケーション、スケジューリング、probe、リソース制限、ネットワーク、Kubernetesの設定のいずれにあるかを確認できます。例えば kubectl describe は、コンテナを直接調査する前に、イメージのpull失敗、readiness probeの失敗、ボリュームマウントのエラーを表示してくれます。

kubectl debug は、得られたシグナルでは問題を説明できない場合や、Podの環境内部からランタイムの状態を調査する必要がある場合に使用しましょう。

2. エフェメラルコンテナは調査に使い、アプリケーションの変更には使わない

エフェメラルコンテナはトラブルシューティングのためのものです。実行中のワークロードに対して、ファイルへのパッチ適用、サービスの再起動、依存関係のインストール、アプリケーションの動作変更に使用してはいけません。

状態の調査、診断コマンドの実行、証拠となる情報の収集に使用しましょう。

kubectl debug my-pod -it --image=busybox --target=my-container

例えば、DNSの名前解決の確認、マウントされたファイルの調査、サービスへの接続テスト、実行中プロセスの確認などが可能です。これらの操作は、ワークロードを変更することなく、何が起きているかを把握するのに役立ちます。

修正はすべて、ソースコード、コンテナイメージ、マニフェスト、デプロイパイプラインで行うべきです。これにより本番環境の動作の再現性が保たれ、Podの再起動後に消えてしまうその場限りの手動変更を防げます。

3. 本番イメージへのツール追加よりデバッグコンテナを優先する

トラブルシューティングのためだけに、本番イメージにシェル、パッケージマネージャー、ネットワークツールをインストールすることは避けましょう。これらのツールはイメージサイズを増やし、コンテナの攻撃対象領域を広げる可能性があります。

代わりに、アプリケーションのイメージは小さく保ち、必要に応じて別のデバッグイメージを使用します。

kubectl debug my-pod -it --image=nicolaka/netshoot --target=my-container

シェルを含まないことが多いdistrolessやscratchベースのコンテナといった最小構成イメージでは、特に有効です。デバッグコンテナを使えば、本番イメージを変更することなく curl、dig、tcpdump、ss、ip などのツールを利用できます。

このアプローチには、役割の境界を明確に保てるという利点もあります。アプリケーションのイメージはワークロードの実行に専念し、デバッグイメージは統制されたトラブルシューティングセッション中にのみ使用します。

4. 承認済みの安全なデバッグイメージを使用する

デバッグイメージには、tcpdump、strace、curl、dig、パッケージマネージャー、シェルユーティリティといった強力なツールが含まれていることが少なくありません。信頼できるレジストリの承認済みイメージのみを使用しましょう。

可変タグではなく、イメージのバージョンを固定します。

kubectl debug my-pod -it --image=registry.example.com/debug-tools:1.4.2

承認済みイメージは脆弱性スキャンを行い、常に最新の状態に保つべきです。不要なパッケージを含めず、チームが実際に必要とするツールだけを含めるようにしましょう。

アクセスもRBACで制御すべきです。エフェメラルコンテナの作成、機密性の高いワークロードへのアタッチ、Nodeレベルのデバッグセッションの開始を、すべてのユーザーに許可するべきではありません。Nodeのデバッグはホストのファイルシステムやシステムレベルの情報を露出させる可能性があるため、信頼できるオペレーターに限定してください。可能であれば --profile フラグ(restricted または baseline)と組み合わせて、セッションに必要以上のアクセス権を付与しないようにしましょう。

5. デバッグPodをクリーンアップし、セッションを記録する

トラブルシューティングが終わったら、コピーしたデバッグPodを削除し、不要なPodが残ってリソースを無駄に消費しないようにしましょう。

kubectl delete pod my-pod-debug

既存のPodに追加したエフェメラルコンテナはPod specから削除できませんが、デバッグセッションの終了とともに実行を停止します。一方、コピーしたPodは削除するまでクラスターに残り続けます。

何を確認し、どのコマンドを実行し、何が判明したかを記録しましょう。インシデントのレビューが容易になり、今後の問題に備えたランブックの改善にも役立ちます。

記録には、影響を受けたPodやNode、使用したデバッグイメージ、重要なコマンド出力、最終的な原因を含めましょう。これにより、他のエンジニアが後で同じ調査を繰り返さずに済みます。

PerfectScaleでレジリエンスリスクを事前に修正し、手動デバッグを削減

kubectl debug のようなコマンドは、クラッシュするPod、スタックしたプロセス、Nodeレベルの問題をリアルタイムで調査する際に不可欠ですが、こうしたインシデントの多くは、もっと早い段階で検出できたはずのリソース設定ミスに起因しています。PerfectScaleは、ワークロードのライトサイジング、ダウンタイムの防止、99.99%の可用性を実現するリソース最適化により、Kubernetesのレジリエンスとパフォーマンスを自律的に向上させます。その結果、チームが対話型のデバッグセッションを開く時間を減らし、開発に集中する時間を増やせます。Podの障害を待ってからエフェメラルコンテナに頼るのではなく、PerfectScaleはそもそも障害の原因となるレジリエンスリスクを特定し、修復します。

PerfectScaleの主な機能:

問題の自動修復: レジリエンスリスクを即座に特定・修正して稼働時間を最大化し、レイテンシを排除します。設定ミス(CPUリクエスト未設定、メモリリクエスト未設定、メモリリミット未設定)や、OOM、CPUスロットリング、evictionといったリソース不足の問題を防ぎます。
インフラの強化: Node全体を横断する包括的な可視性により設定ミスを事前に検出し、正確なメモリリミットの推奨でNodeのオーバーコミットを防止し、Node affinityやtaintを検証し、Podに最適なNodeタイプを選択します。
影響度に基づく優先順位付け: 高度な自動優先順位付けにより、チームが最も重要な問題にリアルタイムで集中できるようにし、SLAやSLOに合わせたアラートでサービスレベルを目標どおりに維持します。
リアルタイムアラートとチケット連携: Slack、MS Teams、Datadogを通じて即時通知を送信し、ワンクリックでチケットを作成して、あらゆる問題を既存のワークフローにエスカレーションできます。
幅広いリスクカバレッジ: eviction、メモリ不足(OOM)、メモリリークの疑い、CPUスロットリング、Podの再起動、HPAの最大レプリカ数への到達、CPU・メモリのリクエストとリミットの不足や未設定を継続的に検出します。

PerfectScaleがクラスターの安定性を維持し、手動トラブルシューティングの必要性を削減する方法については、Kubernetesパフォーマンス最適化プラットフォームをご覧ください。

よくある質問

kubectl debugコマンドは何のために使いますか?

kubectl debug は、KubernetesのワークロードやNodeを対話的にトラブルシューティングするために使います。実行中のPodへのエフェメラルコンテナのアタッチ、クラッシュするPodの設定を変更したコピーの作成、Node上でのデバッグPodの起動が可能です。いずれも、対象のイメージにデバッグツールがあらかじめ含まれている必要はありません。

Podに対してkubectl debugを使うには?

kubectl debug <pod-name> -it --image=busybox を実行すると、実行中のPodにエフェメラルなデバッグコンテナをアタッチできます。--target=<container-name> を追加すると特定のコンテナとプロセス名前空間を共有でき、--copy-to=<new-pod-name> を使えば稼働中のPodではなくコピーをデバッグできます(起動時にクラッシュするPodに便利です)。

Nodeに対してkubectl debugを使うには?

kubectl debug node/<node-name> -it --image=ubuntu を実行すると、Nodeのホスト名前空間で実行され、Nodeのルートファイルシステムが /host にマウントされたデバッグPodを作成できます。デフォルトは general プロファイルで、特権アクセスは付与されません。完全なルートレベルの権限が必要な場合は --profile=sysadmin を使用してください。

kubectl debugコマンドの構文は?

一般的な形式は kubectl debug (POD | TYPE/NAME) [flags] です。最もよく使われるのは、デバッグコンテナのイメージを指定する --image、対話型ターミナルのための -it、特定のコンテナを対象にする --target、Podのコピーをデバッグするための --copy-to です。

kubectl debugとkubectl execの違いは?

kubectl exec は、Pod自身のイメージ内の既存のコンテナでコマンドを実行するため、そのイメージに必要なツールが含まれている場合にのみ機能します。kubectl debug は任意のイメージで別のコンテナ(またはPod)をアタッチできるため、シェルをまったく持たない最小構成やdistrolessのコンテナには不可欠です。

kubectl debugは元のPodやコンテナを変更しますか?

kubectl debug でエフェメラルコンテナを追加しても、Podの既存のコンテナが再起動または変更されることはありません。既存コンテナの横に一時的なコンテナが追加されるだけです。--copy-to を使えばさらに一歩進んで別のPodが作成されるため、元のPodにはまったく手が加えられません。

kubectl debugで作成したPodはクリーンアップが必要ですか?

はい、--copy-to で作成したPodはクリーンアップが必要です。これらのPodは kubectl delete pod <debug-pod-name> で削除するまでクラスターに残り続けます。既存のPodに直接追加したエフェメラルコンテナは、個別のクリーンアップは不要です。セッションの終了とともに実行を停止しますが、Pod specには表示されたまま残ります。