kubectl debug を用いた Kubernetes Pod トラブルシューティング

Tech

本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。

kubectl debug を用いた Kubernetes Pod トラブルシューティング

1. 要件と前提

Kubernetes環境におけるPodのトラブルシューティングは、アプリケーションの安定稼働に不可欠です。kubectl debugコマンドは、実行中のPodに一時的なコンテナ（Ephemeral Container）をアタッチすることで、Pod内部へのアクセスと診断ツール実行を可能にする強力なツールです。本記事では、DevOpsエンジニアがこの機能を効果的に活用し、複雑なPod問題を解決するための実践的な手法を解説します。

1.1. 前提条件

  • Kubernetes クラスター: バージョン1.25以降を推奨します。kubectl debugはKubernetes 1.25でGA（General Availability）になりました。

  • kubectl: クラスターと同等またはそれ以降のバージョンがインストールされていること。

  • 権限: debug pods、create ephemeralcontainersなどの権限が付与されたkubeconfig設定が利用できること。

  • CLIツール: jq (JSON処理)、curl (HTTPクライアント) がインストールされていること。

  • Linux知識: systemdの基本的な操作知識。

1.2. 安全なBashスクリプトの原則

本記事で提示するスクリプト例では、以下の安全なBashスクリプトの原則を適用します。

  • set -euo pipefail:

    • -e: コマンドが失敗した場合に即座に終了します。

    • -u: 未定義の変数を使用した場合にエラーとします。

    • -o pipefail: パイプライン中のどのコマンドが失敗しても、パイプライン全体が失敗したものとします。

  • trap: スクリプト終了時に一時ファイルを確実にクリーンアップするために使用します。

  • mktemp -d: 一時ディレクトリを安全に作成し、競合やセキュリティリスクを低減します。

2. 実装

2.1. 環境準備と基本的なデバッグ

まず、トラブルシューティングの対象となるPodを準備し、kubectl debugの基本的な使い方を確認します。

2.1.1. サンプルPodのデプロイ

# debug-target-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: debug-target-nginx
  labels:
    app: nginx
spec:
  containers:

  - name: nginx
    image: nginx:1.21.6
    ports:

    - containerPort: 80

#!/bin/bash

set -euo pipefail

echo "INFO: サンプルPodをデプロイします..."
kubectl apply -f debug-target-pod.yaml

echo "INFO: PodがRunning状態になるまで待機します..."
kubectl wait --for=condition=Ready pod/debug-target-nginx --timeout=120s

echo "INFO: Podデプロイ完了。"

2.1.2. kubectl debug を用いたシェルアタッチ

最も一般的なデバッグシナリオは、実行中のPodにデバッグ用コンテナをアタッチし、シェルアクセスを得ることです。

#!/bin/bash

set -euo pipefail

TARGET_POD="debug-target-nginx"
DEBUG_IMAGE="ubuntu:latest" # 診断ツールが豊富なイメージを選択

echo "INFO: Pod ${TARGET_POD} に ephemeral container をアタッチし、シェル接続します。"
echo "INFO: デバッグセッション終了後、'exit' コマンドでシェルを終了してください。"

# `--target`で既存のコンテナのPID名前空間を共有し、内部プロセスを調査可能にする

kubectl debug -it "${TARGET_POD}" --image="${DEBUG_IMAGE}" --target=nginx -- /bin/bash

echo "INFO: デバッグセッションが終了しました。"

# デバッグ終了後、不要になったPodを削除する例 (オプション)


# echo "INFO: サンプルPodをクリーンアップします。"


# kubectl delete -f debug-target-pod.yaml

root権限の扱いと注意点: kubectl debugでアタッチされるEphemeral Containerは、多くの場合、デフォルトでrootユーザーとして実行されます。これにより、Pod内部のファイルシステムやプロセスに対する広範な操作が可能になりますが、以下の点に注意が必要です。

  • セキュリティリスク: 悪意のあるユーザーがデバッグコンテナを悪用すると、Pod内部だけでなく、ホストノードへの影響も及ぼす可能性があります。適切なRBAC設定でkubectl debugの利用を制限することが重要です。

  • 意図しない変更: root権限での操作は、誤ってアプリケーションファイルや設定を変更してしまうリスクがあります。変更を加える際は細心の注意を払い、可能な限り読み取り専用のデバッグツールを使用することを検討してください。

  • 権限分離: 可能な場合は、特定のタスクに特化した非rootユーザーで動作するデバッグイメージを用意し、securityContext等で権限を最小化することを検討します。

2.2. 高度なトラブルシューティング技術

2.2.1. jq を用いた Pod 情報の効率的な解析

kubectlのJSON出力をjqで処理することで、Podの状態やイベントを素早く抽出・分析できます。

#!/bin/bash

set -euo pipefail

TARGET_POD="debug-target-nginx"

echo "INFO: Pod ${TARGET_POD} の詳細情報を jq で解析します。"

# Podのコンテナイメージと状態を抽出

echo "--- コンテナのイメージと状態 ---"
kubectl get pod "${TARGET_POD}" -o json | \
  jq '.spec.containers[] | {name: .name, image: .image, state: .status.state}'

# Podのイベント情報を抽出 (最新5件)

echo "--- 最新のPodイベント ---"
kubectl get events --field-selector involvedObject.name="${TARGET_POD}" -o json | \
  jq '.items | sort_by(.lastTimestamp) | .[-5:] | .[] | {time: .lastTimestamp, reason: .reason, message: .message}'

# 計算量: `kubectl get` の出力サイズに比例。O(N) (NはJSONドキュメントのサイズ)。


# メモリ: `kubectl get` の出力全体をメモリにロードする。大規模クラスターの場合、`stream`処理を検討。

2.2.2. curl によるネットワーク診断（TLS/再試行/バックオフ）

Pod内からの外部サービスへの接続性やTLSハンドシェイクの問題は、curlを使って診断できます。特に、信頼性の低いネットワーク環境では再試行やバックオフが重要です。

#!/bin/bash

set -euo pipefail

TARGET_POD="debug-target-nginx"
EXTERNAL_URL="https://example.com" # 診断対象の外部URL

echo "INFO: Pod ${TARGET_POD} 内で ${EXTERNAL_URL} への接続性を curl で診断します。"

# kubectl debug で一時コンテナを起動し、その中で curl を実行


# -- /bin/sh -c "..." で複数のコマンドを連結

kubectl debug -it "${TARGET_POD}" --image=curlimages/curl:latest --target=nginx -- \
  /bin/sh -c "
    echo '--- curl による接続テスト ---';
    curl --retry 5 \
         --retry-delay 3 \
         --retry-max-time 30 \
         --fail \
         --show-error \
         --location \
         --connect-timeout 5 \
         --cacert /etc/ssl/certs/ca-certificates.crt \
         '${EXTERNAL_URL}';

    if [ \$? -eq 0 ]; then
      echo 'SUCCESS: 外部サービスへの接続に成功しました。';
    else
      echo 'ERROR: 外部サービスへの接続に失敗しました。';
      echo 'INFO: TLS証明書の問題の可能性も考慮し、--insecure オプションでの再試行を検討してください (本番環境では非推奨)。';

      # curl --retry 3 --retry-delay 2 --insecure '${EXTERNAL_URL}' # 例: TLSエラーを無視する場合

    fi
  "

echo "INFO: ネットワーク診断が終了しました。"

# 計算量: curlのHTTPリクエスト回数に比例。


# メモリ: curlプロセスとその応答を処理する一時的なバッファ。

2.3. systemd との連携によるログ収集

特定のPodやノードから定期的に診断情報を収集し、永続化する必要がある場合、systemd unitとtimerを組み合わせることが有効です。ここでは、kubectl logsを定期的に収集する例を示します。

2.3.1. systemd unit ファイルの作成 (/etc/systemd/system/k8s-pod-log-collector.service)

# k8s-pod-log-collector.service

[Unit]
Description=Kubernetes Pod Log Collector
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/collect-k8s-pod-logs.sh
User=root # kubectl実行に必要な権限を持つユーザー、またはrootで実行
Group=root
WorkingDirectory=/var/log/kubernetes-pod-logs
StandardOutput=journal
StandardError=journal

2.3.2. ログ収集スクリプトの作成 (/usr/local/bin/collect-k8s-pod-logs.sh)

#!/bin/bash

set -euo pipefail

# 一時ディレクトリの作成とクリーンアップ


# メモリ: 基本的にディスクI/Oベース。一時ファイルはディスク容量を消費。


# 計算量: kubectlコマンドの実行回数に比例。ログサイズが大きいほど処理時間が増加。

TMP_DIR=$(mktemp -d -t k8s-logs-XXXXXXXXXX)
trap "rm -rf '${TMP_DIR}'" EXIT

LOG_DIR="/var/log/kubernetes-pod-logs"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)

mkdir -p "${LOG_DIR}"

echo "INFO: [${TIMESTAMP}] Kubernetes Podログの収集を開始します..."

# 全てのRunning Podのログを収集


# NOTE: 大規模クラスターでは、特定のNamespaceやLabelでフィルタリング推奨

while IFS= read -r pod_name; do
  echo "INFO: Pod ${pod_name} のログを収集中..."
  kubectl logs "${pod_name}" > "${LOG_DIR}/${pod_name}-${TIMESTAMP}.log" || echo "WARNING: Pod ${pod_name} のログ収集に失敗しました。"
done < <(kubectl get pods --field-selector=status.phase=Running -o custom-columns=NAME:.metadata.name --no-headers)

echo "INFO: [${TIMESTAMP}] Kubernetes Podログの収集が完了しました。ログは ${LOG_DIR} に保存されました。"

2.3.3. systemd timer ファイルの作成 (/etc/systemd/system/k8s-pod-log-collector.timer)

# k8s-pod-log-collector.timer

[Unit]
Description=Run Kubernetes Pod Log Collector every 15 minutes

[Timer]
OnCalendar=*:0/15
Persistent=true # タイマー起動時にmissした実行を補完
Unit=k8s-pod-log-collector.service

[Install]
WantedBy=timers.target

2.3.4. systemd サービスとタイマーの有効化・開始

#!/bin/bash

set -euo pipefail

echo "INFO: systemd service/timer ファイルをリロードします。"
sudo systemctl daemon-reload

echo "INFO: k8s-pod-log-collector timer を有効化して開始します。"
sudo systemctl enable --now k8s-pod-log-collector.timer

echo "INFO: timer のステータスを確認します。"
sudo systemctl status k8s-pod-log-collector.timer

echo "INFO: 最新の実行ログを確認するには、'journalctl -u k8s-pod-log-collector.service' を実行してください。"
echo "INFO: ログファイルは /var/log/kubernetes-pod-logs/ に保存されます。"

3. 検証

3.1. kubectl debug の動作検証

デバッグセッションが正常に開始され、Pod内部でコマンドが実行できることを確認します。

#!/bin/bash

set -euo pipefail

TARGET_POD="debug-target-nginx"

echo "INFO: Pod ${TARGET_POD} に ephemeral container をアタッチし、簡単なコマンドを実行します。"
kubectl debug "${TARGET_POD}" --image=busybox --target=nginx -- ls -la /usr/share/nginx/html/

echo "INFO: コマンドが正常に実行されたことを確認してください。"
echo "INFO: ephemeral container が自動的に終了したことを確認してください。"

3.2. systemd タイマーの動作検証

systemdタイマーが設定通りに動作し、ログが収集されていることを確認します。

  1. タイマーの実行確認: sudo systemctl status k8s-pod-log-collector.timer 出力にNext: ...と次回の実行時刻が表示されていることを確認します。

  2. サービスログの確認: sudo journalctl -u k8s-pod-log-collector.service ログ収集スクリプトの出力（INFOメッセージ）が表示されていることを確認します。

  3. ログファイルの確認: ls -la /var/log/kubernetes-pod-logs/ debug-target-nginx-YYYYMMDD-HHMMSS.logのようなファイルが生成されていることを確認し、その内容を閲覧します。

4. 運用

  • デバッグイメージの管理: 頻繁に利用するデバッグツールを含むカスタムイメージを作成し、信頼できるレジストリで管理することで、セキュリティと効率性を向上させます。

  • RBACによるアクセス制御: kubectl debugコマンドは強力なため、必要なユーザーやグループにのみ最小限の権限（例: 特定のNamespace内のみ）を与えるようにRBACポリシーを設定します。

  • クリーンアップの徹底: 一時的に作成されたデバッグコンテナは自動的に削除されますが、--copy-toで作成されたPodは手動で削除が必要です。また、systemdで収集したログファイルも定期的にアーカイブまたは削除する運用が必要です。

  • デバッグコンテナの監視: デバッグセッションが予期せず長時間継続していないか、リソースを過剰に消費していないかなど、監視体制を整えることも重要です。

5. トラブルシュート

5.1. EphemeralContainers 機能が無効化されている

症状: error: ephemeral containers are disabled by feature gate EphemeralContainers 原因: KubernetesクラスターでEphemeralContainersのFeature Gateが有効になっていない場合。 解決策: Kubernetes 1.25以降ではデフォルトでGAですが、それ以前のバージョンやカスタム設定では明示的に有効化が必要です。kube-apiserverの起動オプションに--feature-gates=EphemeralContainers=trueを追加します。

5.2. デバッグイメージの取得失敗

症状: ImagePullBackOffやErrImagePull 原因: 指定したデバッグイメージが存在しない、レジストリへのアクセスに問題がある、またはイメージのプルに時間がかかっている。 解決策:

  • イメージ名が正しいか確認します（例: ubuntu:latest）。

  • プライベートレジストリの場合、imagePullSecretsがPodに正しく設定されているか確認します。

  • ノードのインターネット接続を確認します。

5.3. 権限不足エラー

症状: Error from server (Forbidden): ephemeralcontainers "nginx" is forbidden: User "..." cannot create ephemeralcontainers in the namespace "..." 原因: kubectl debugを実行しているユーザーのServiceAccount/Userに、Ephemeral Containerの作成やPodへのアクセス権限がない。 解決策:

  • kubectl auth can-i debug podsで権限を確認します。

  • 必要なRBAC権限を付与するRoleBindingを作成します。

5.4. PodがRunning状態でない場合のデバッグ

kubectl debugは通常、Running状態のPodに対して使用します。しかし、CrashLoopBackOffなど、PodがRunning状態に至らない場合もデバッグしたいことがあります。

解決策: --copy-toオプションを使用して、問題のPodのコピーを作成し、そのコピーに対してデバッグイメージやコマンドを調整してデバッグを行います。 例: kubectl debug --copy-to=debug-crashloop-nginx -f debug-target-pod.yaml --image=busybox -- /bin/sh

6. まとめ

kubectl debugコマンドとEphemeral Containerは、Kubernetes Podのトラブルシューティングにおいて不可欠なツールです。本記事では、その基本的な使い方から、jqやcurlといったCLIツールとの連携、さらにsystemdを利用したログ収集の自動化まで、実践的なアプローチを紹介しました。

graph TD
    A["Pod障害発生/異常検知"] --> |`kubectl get events` `kubectl logs`| B("初期調査");
    B --> |問題切り分け: Pod内部か外部か?| C{"Pod内部の問題"};
    C --> |`kubectl debug -it  --image= --target=`| D("Ephemeral Container起動");
    D --> |シェル接続| E["内部環境の確認: `ps`, `ls`, `df`"];
    D --> |ツール実行| F["診断ツールの利用: `netstat`, `dig`, `curl`, `strace`"];
    E --> G{"問題特定"};
    F --> G;
    G --> |設定変更/修正| H("問題解決");
    H --> |デバッグコンテナ終了| I["サービス復旧"];
    C --> |Pod起動時エラー (CrashLoopBackOff等)| J["`kubectl debug --copy-to= ...`"];
    J --> |複製Podでイメージ/コマンド変更| K["起動プロセスデバッグ"];
    K --> G;

これらの技術を組み合わせることで、DevOpsエンジニアはKubernetesクラスター内の複雑な問題を迅速かつ効率的に解決し、サービスの可用性維持に貢献できます。常にセキュリティと権限管理を意識し、安全な運用を心がけましょう。

ライセンス：本記事のテキスト/コードは特記なき限り CC BY 4.0 です。引用の際は出典URL（本ページ）を明記してください。
利用ポリシー もご参照ください。

コメント

タイトルとURLをコピーしました