kubectl-debugging

kubectl debug - Kubernetes の対話型デバッグ

kubectl debug を使用して Kubernetes リソースをデバッグするための専門知識です。エフェメラルコンテナー、Pod のコピー、ノードへのアクセスを扱います。

このスキルを使用する場面

次の場合にこのスキルを使用します…	次の場合は を使用します…
kubectl debug で実行中の Pod にエフェメラルデバッグコンテナーをアタッチする	一般的な kubectl ワークフロー（apply、get、describe、logs）には kubernetes-operations を使用します
対話型トラブルシューティングのために、異なるイメージやコマンドを使った Pod のコピーを作成する	障害が実行中のコンテナーではなく、テンプレートのレンダリングやチャートの設定にある場合は helm-debugging を使用します
ホストの名前空間やファイルシステムを調査するため、ノードレベルのデバッグセッションを開始する	復旧操作が Pod ごとのデバッグではなく Helm のロールバックである場合は helm-release-recovery を使用します

主な機能

kubectl debug は、一般的なデバッグタスクを自動化します。

• エフェメラルコンテナー：再起動せずに、実行中の Pod にデバッグコンテナーを追加します
• Pod のコピー：デバッグ用に変更したコピーを作成します（異なるイメージやコマンド）
• ノードのデバッグ：ノードのホスト名前空間とファイルシステムにアクセスします

コンテキストの安全性（重要）

すべての kubectl コマンドで、常に --context を明示的に指定してください。

# CORRECT: Explicit context
kubectl --context=prod-cluster debug mypod -it --image=busybox

# WRONG: Relying on current context
kubectl debug mypod -it --image=busybox  # Which cluster?

クイックリファレンス

エフェメラルデバッグコンテナーの追加

# Interactive debugging with busybox
kubectl --context=my-context debug mypod -it --image=busybox

# Target specific container's process namespace
kubectl --context=my-context debug mypod -it --image=busybox --target=mycontainer

# Use a specific debug profile
kubectl --context=my-context debug mypod -it --image=busybox --profile=netadmin

デバッグ用の Pod コピー

# Create debug copy
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --image=busybox

# Copy and change container image
kubectl --context=my-context debug mypod --copy-to=mypod-debug --set-image=app=busybox

# Copy and modify command
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --container=myapp -- sh

# Copy on same node
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --same-node --image=busybox

ノードのデバッグ

# Interactive node debugging (host namespaces, filesystem at /host)
kubectl --context=my-context debug node/mynode -it --image=busybox

# With sysadmin profile for full capabilities
kubectl --context=my-context debug node/mynode -it --image=ubuntu --profile=sysadmin

デバッグプロファイル

プロファイル	用途	機能
legacy	デフォルト、制限なし	フルアクセス（後方互換）
general	汎用	中程度の制限
baseline	最小限の制限	Pod セキュリティのベースライン
netadmin	ネットワークのトラブルシューティング	NET_ADMIN 機能
restricted	高セキュリティ環境	最も厳しい制限
sysadmin	システム管理	SYS_PTRACE、SYS_ADMIN

# Network debugging (tcpdump, netstat, ss)
kubectl --context=my-context debug mypod -it --image=nicolaka/netshoot --profile=netadmin

# System debugging (strace, perf)
kubectl --context=my-context debug mypod -it --image=ubuntu --profile=sysadmin

一般的なデバッグイメージ

イメージ	サイズ	用途
busybox	~1MB	基本的なシェルと一般的なユーティリティ
alpine	~5MB	apk パッケージマネージャーを備えたシェル
ubuntu	~77MB	apt を備えた完全な Linux
nicolaka/netshoot	~350MB	ネットワークのデバッグ（tcpdump、dig、curl、netstat）
gcr.io/k8s-debug/debug	さまざま	Kubernetes 公式デバッグイメージ

デバッグのパターン

ネットワーク接続の問題

# Add netshoot container for network debugging
kubectl --context=my-context debug mypod -it \
  --image=nicolaka/netshoot \
  --profile=netadmin

# Inside container:
# - tcpdump -i any port 80
# - dig kubernetes.default
# - curl -v http://service:port
# - ss -tlnp
# - netstat -an

アプリケーションのクラッシュ

# Copy pod with different entrypoint to inspect
kubectl --context=my-context debug mypod -it \
  --copy-to=mypod-debug \
  --container=app \
  -- sh

# Inside: check filesystem, env vars, config files

プロセスの調査

# Target container's process namespace
kubectl --context=my-context debug mypod -it \
  --image=busybox \
  --target=mycontainer

# Inside: ps aux, /proc inspection

ノードレベルの問題

# Debug node with host access
kubectl --context=my-context debug node/worker-1 -it \
  --image=ubuntu \
  --profile=sysadmin

# Inside:
# - Host filesystem at /host
# - chroot /host for full access
# - journalctl, systemctl, dmesg

非破壊的なデバッグ

# Create copy, keeping original running
kubectl --context=my-context debug mypod -it \
  --copy-to=mypod-debug \
  --same-node \
  --share-processes \
  --image=busybox

# Original pod continues serving traffic
# Debug copy shares storage if on same node

主なオプション

オプション	説明
-it	対話型 TTY（シェルアクセスに必要）
--image	デバッグコンテナーのイメージ
--container	デバッグコンテナーの名前
--target	このコンテナーとプロセス名前空間を共有します
--copy-to	エフェメラルコンテナーの代わりにコピーを作成します
--same-node	同じノードにコピーをスケジュールします（--copy-to と併用）
--set-image	コピー内のコンテナーイメージを変更します
--profile	セキュリティプロファイル（legacy、netadmin、sysadmin など）
--share-processes	プロセス名前空間の共有を有効にします（--copy-to を指定した場合のデフォルト：true）
--replace	コピーの作成時に元の Pod を削除します

ベストプラクティス

1. 適切なプロファイルを使用する - 機能をデバッグのニーズに合わせます
2. エフェメラルコンテナーを優先する - Pod のコピーより影響が少なくなります
3. 影響の大きいデバッグには --copy-to を使用する - 元の Pod を保持します
4. デバッグ用 Pod をクリーンアップする - デバッグ後にコピーを削除します
5. --same-node を使用する - 共有ストレージやネットワーク条件にアクセスする場合に使用します

クリーンアップ

# List debug pod copies
kubectl --context=my-context get pods | grep -E "debug|copy"

# Delete debug pods
kubectl --context=my-context delete pod mypod-debug

要件

• エフェメラルコンテナーには Kubernetes 1.23 以降（安定版）が必要です
• デバッグプロファイルには Kubernetes 1.25 以降が必要です
• pods/ephemeralcontainers の RBAC 権限が必要です

オプションの詳細なリファレンス、例、トラブルシューティングのパターンについては、REFERENCE.md を参照してください。