kubectl debugとエフェメラルコンテナを活用したKubernetesトラブルシューティング

Linux・CLI・DevOpsカテゴリを表すパンダのイラスト Linux・CLI・DevOps
2025.12.25

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

kubectl debugとエフェメラルコンテナを活用したKubernetesトラブルシューティング

DevOpsエンジニアとして、Kubernetesクラスター上で稼働するアプリケーションのトラブルシューティングは日常業務です。特に、本番環境で問題が発生した場合、アプリケーションコンテナに余計なツールをインストールせずに、非侵襲的にデバッグを行う必要があります。ここで強力なツールとなるのが、kubectl debugコマンドとそれに伴って利用される「エフェメラルコンテナ」です。本記事では、このデバッグ手法を具体的な実装例を交えて解説します。

1. 要件と前提

1.1 kubectl debugとエフェメラルコンテナの概要

kubectl debugコマンドは、既存のPodに対して一時的なデバッグ用コンテナ（エフェメラルコンテナ）を起動し、そのコンテナに接続するために使用されます。これにより、デバッグツールが不足している本番コンテナの調査や、ホストのPID名前空間を共有してプロセスを検査するなどの高度な診断が可能になります。

エフェメラルコンテナは、Podの通常のコンテナとは異なり、Podの仕様には含まれず、動的に追加されます。主にデバッグや診断を目的としており、Kubernetes 1.25で安定版となりました。

1.2 Kubernetesバージョン要件

kubectl debugコマンドとエフェメラルコンテナは、Kubernetesバージョン1.25以降で安定版として利用可能です。それ以前のバージョンでは、機能が利用できないか、機能ゲートを有効にする必要がある場合があります。本記事では1.25以降の環境を前提とします。

1.3 必要な権限（RBAC）

kubectl debugを利用するには、以下のRBAC権限が必要です。

  • pods/ephemeralcontainersリソースに対するcreate権限

  • podsリソースに対するget、list、watch権限

通常、editロールを持つユーザーはこれらの権限を持ちますが、最小権限の原則に基づき、専用のロールを作成することが推奨されます。

1.4 セキュリティ上の注意点

エフェメラルコンテナは、既存のPodのコンテナと同じPID名前空間、ネットワーク名前空間、またはIPC名前空間を共有できるため、デバッグ対象のプロセスやネットワークトラフィックに直接アクセスできます。また、--privilegedオプションを併用することで、ホストレベルへの影響も与えかねません。

  • root権限の扱い: デバッグイメージをrootユーザーで実行する場合、コンテナ内でホストファイルシステムへのアクセスや設定変更が可能になるリスクがあります。最小限の権限を持つデバッグイメージを使用し、必要な場合のみ特定のケイパビリティを付与するなどの対策が必要です。

  • 権限分離: kubectl debugを実行するユーザー、デバッグコンテナが利用するサービスアカウント、そしてデバッグコンテナ自体が持つ権限を厳密に分離し、意図しない操作が行われないように管理することが重要です。

1.5 デバッグのフロー

一般的なデバッグのフローは以下のようになります。

graph TD
    A["監視システムで問題検知"] --> B{"問題Podの特定"};
    B --> C["kubectl describe/logsで初期調査"];
    C -- 解決不可 --> D["kubectl debugでエフェメラルコンテナ起動"];
    D --> E["エフェメラルコンテナ内で診断ツール実行"];
    E -- 原因特定 --> F["デバッグセッション終了"];
    F --> G["問題解決策の適用"];
    F --> H["報告/ナレッジ共有"];

2. 実装

2.1 環境準備

デバッグ対象のPodとしてNginxをデプロイします。

# deployment.yaml

cat <<EOF > nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: debug-nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:

      - name: nginx
        image: nginx:1.23.1-alpine
        ports:

        - containerPort: 80
        command: ["sh", "-c", "apk add --no-cache curl && while true; do sleep 3600; done"]
EOF

kubectl apply -f nginx-deployment.yaml

# PodがRunningになるまで待機

kubectl wait --for=condition=Ready pod -l app=nginx --timeout=120s

2.2 基本的なデバッグセッション

デバッグ対象のPod名を確認します。

POD_NAME=$(kubectl get pods -l app=nginx -o jsonpath='{.items[0].metadata.name}')
echo "ターゲットPod: $POD_NAME"

# エフェメラルコンテナを起動し、対象のnginxコンテナのPID名前空間を共有


# --image にはデバッグに必要なツールを含むイメージを指定


# --target にはデバッグ対象のPod内のコンテナ名を指定

kubectl debug -it "$POD_NAME" \
  --image=busybox:stable \
  --target=nginx \
  --share-processes=true \
  --container=debugger-$(date +%s)

このコマンドを実行すると、busyboxイメージをベースとしたエフェメラルコンテナが起動し、そのシェルに接続されます。 コンテナ内で以下のコマンドを試してください。

# エフェメラルコンテナ内で実行

ps aux              # nginxプロセスの確認
netstat -tulnp      # nginxのポート80がListenしているか確認
ls -l /proc/1/exe   # PID 1がnginxであることを確認（PID名前空間共有のため）
exit                # セッションを終了するとエフェメラルコンテナは終了します

2.3 スクリプトによる自動化と安全性

Podのヘルスチェックを行い、問題があれば情報を収集するスクリプトの例です。

#!/bin/bash

set -euo pipefail

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

TMP_DIR=$(mktemp -d)
trap 'echo "Cleaning up temporary directory: $TMP_DIR"; rm -rf "$TMP_DIR"' EXIT

KUBECTL_CONTEXT=${KUBECTL_CONTEXT:-$(kubectl config current-context)}
NAMESPACE=${NAMESPACE:-default}
APP_LABEL=${APP_LABEL:-app=nginx}
TARGET_CONTAINER_NAME=${TARGET_CONTAINER_NAME:-nginx}
DEBUG_IMAGE=${DEBUG_IMAGE:-alpine/git:latest} # git, curl, openssh などが含まれるイメージ

echo "--- $(date '+%Y-%m-%d %H:%M:%S JST') ---"
echo "Kubernetes Context: $KUBECTL_CONTEXT"
echo "Namespace: $NAMESPACE"

# Pod名の取得

POD_NAME=$(kubectl get pods -n "$NAMESPACE" -l "$APP_LABEL" -o jsonpath='{.items[0].metadata.name}' 2>/dev/null)

if [ -z "$POD_NAME" ]; then
  echo "Error: No pod found with label '$APP_LABEL' in namespace '$NAMESPACE'." >&2
  exit 1
fi

echo "Target Pod: $POD_NAME"

# Podの状態をチェック (jqを用いたJSON処理の例)

POD_STATUS_JSON=$(kubectl get pod "$POD_NAME" -n "$NAMESPACE" -o json)
POD_PHASE=$(echo "$POD_STATUS_JSON" | jq -r '.status.phase')
CONTAINER_READY=$(echo "$POD_STATUS_JSON" | jq -r --arg TARGET_CONTAINER "$TARGET_CONTAINER_NAME" \
  '.status.containerStatuses[] | select(.name == $TARGET_CONTAINER) | .ready')

echo "Pod Phase: $POD_PHASE"
echo "Container '$TARGET_CONTAINER_NAME' Ready: $CONTAINER_READY"

if [[ "$POD_PHASE" != "Running" || "$CONTAINER_READY" != "true" ]]; then
  echo "Warning: Pod '$POD_NAME' is not in 'Running' phase or container '$TARGET_CONTAINER_NAME' is not ready."
  echo "Initiating diagnostic data collection..."

  # curlを用いた外部サービスのヘルスチェックと再試行/バックオフの例


  # ここではデモとして、Kubernetes APIサーバの健全性をチェック


  # 実際のシナリオでは、アプリケーションが依存する外部サービスなど

  echo "Checking Kubernetes API Server health..."
  API_HEALTH_CHECK=$(curl -s --fail --retry 5 --retry-delay 5 --retry-max-time 60 \
    --cacert "$KUBECTL_CONTEXT_CA_CERT" \
    --header "Authorization: Bearer $KUBECTL_CONTEXT_TOKEN" \
    "$(kubectl config view --minify --output 'jsonpath={.clusters[0].cluster.server}')/healthz")

  if [ "$?" -eq 0 ]; then
    echo "API Server Health: $API_HEALTH_CHECK"
  else
    echo "Error: Failed to reach Kubernetes API Server after retries." >&2
  fi

  # kubectl debug を用いて診断情報を収集 (ここではデモのためps auxを実行)

  echo "Starting ephemeral container for diagnostics on $POD_NAME..."
  DEBUG_LOG="$TMP_DIR/${POD_NAME}_debug_output.log"

  # エフェメラルコンテナ内でコマンドを実行し、その出力をファイルに保存


  # kubectl debug は非対話モードでも実行可能（-- /bin/sh -c "<command>"）

  if kubectl debug "$POD_NAME" \
    --image="$DEBUG_IMAGE" \
    --target="$TARGET_CONTAINER_NAME" \
    --share-processes=true \
    --container="diagnoser-$(date +%s)" \
    -- /bin/sh -c "ps aux; echo '--- Netstat ---'; netstat -tulnp; echo '--- Container Logs ---'; tail -n 50 /var/log/nginx/access.log 2>/dev/null || echo 'Nginx log not found or empty';" > "$DEBUG_LOG"; then
    echo "Diagnostic output saved to $DEBUG_LOG"
    cat "$DEBUG_LOG"
  else
    echo "Error: Failed to start or execute command in ephemeral container." >&2
  fi

else
  echo "Pod '$POD_NAME' is healthy. No action needed."
fi

解説:

  • set -euo pipefail: スクリプトの安全性を確保します。

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

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

    • -o pipefail: パイプライン中の任意のコマンドが失敗した場合、パイプライン全体が失敗します。

  • TMP_DIR=$(mktemp -d)とtrap '...' EXIT: 一時ディレクトリを作成し、スクリプト終了時に必ずクリーンアップします。

  • jq: kubectl get pod -o jsonの出力からstatus.phaseやcontainerStatusesを安全かつプログラム的に抽出します。

  • curlの再試行ロジック: --retry, --retry-delay, --retry-max-timeオプションを使用して、ネットワークが不安定な状況でも確実に情報を取得しようとします。--cacertやAuthorizationヘッダーは、Kubernetes APIなどTLSで保護されたAPIにアクセスする際の具体的な例です。

  • kubectl debug ... -- /bin/sh -c "<command>": 非対話モードでエフェメラルコンテナ内でコマンドを実行し、その出力をキャプチャします。

2.4 systemdによる定期診断

上記のスクリプトを定期的に実行するためのsystemdユニットとタイマーの例です。 ファイルは/etc/systemd/system/に配置します。

まず、スクリプトを/usr/local/bin/kubernetes-diagnose.shとして保存し、実行権限を与えます。

sudo install -m 755 /dev/stdin /usr/local/bin/kubernetes-diagnose.sh <<'EOF'
#!/bin/bash

set -euo pipefail
TMP_DIR=$(mktemp -d)
trap 'echo "Cleaning up temporary directory: $TMP_DIR"; rm -rf "$TMP_DIR"' EXIT
KUBECTL_CONTEXT=${KUBECTL_CONTEXT:-$(kubectl config current-context)}
NAMESPACE=${NAMESPACE:-default}
APP_LABEL=${APP_LABEL:-app=nginx}
TARGET_CONTAINER_NAME=${TARGET_CONTAINER_NAME:-nginx}
DEBUG_IMAGE=${DEBUG_IMAGE:-alpine/git:latest}

# KUBECTL_CONTEXT_CA_CERTとKUBECTL_CONTEXT_TOKENは、


# systemdで実行される際にKubeconfigが存在しない場合のために設定が必要。


# 例: Service Account Tokenをファイルとしてマウントし、そのパスを指定する


# または、systemdユニットの実行ユーザーのkubeconfigが適切に設定されていることを前提とする。


# デモのため、ここではダミー値を設定（実際の運用では環境に合わせて調整）

KUBECTL_CONTEXT_CA_CERT=${KUBECTL_CONTEXT_CA_CERT:-/etc/ssl/certs/ca-certificates.crt}
KUBECTL_CONTEXT_TOKEN=${KUBECTL_CONTEXT_TOKEN:-dummy-token}

echo "--- $(date '+%Y-%m-%d %H:%M:%S JST') ---"
echo "Kubernetes Context: $KUBECTL_CONTEXT"
echo "Namespace: $NAMESPACE"

POD_NAME=$(kubectl get pods -n "$NAMESPACE" -l "$APP_LABEL" -o jsonpath='{.items[0].metadata.name}' 2>/dev/null)

if [ -z "$POD_NAME" ]; then
  echo "Error: No pod found with label '$APP_LABEL' in namespace '$NAMESPACE'." >&2
  exit 1
fi

echo "Target Pod: $POD_NAME"

POD_STATUS_JSON=$(kubectl get pod "$POD_NAME" -n "$NAMESPACE" -o json)
POD_PHASE=$(echo "$POD_STATUS_JSON" | jq -r '.status.phase')
CONTAINER_READY=$(echo "$POD_STATUS_JSON" | jq -r --arg TARGET_CONTAINER "$TARGET_CONTAINER_NAME" \
  '.status.containerStatuses[] | select(.name == $TARGET_CONTAINER) | .ready')

echo "Pod Phase: $POD_PHASE"
echo "Container '$TARGET_CONTAINER_NAME' Ready: $CONTAINER_READY"

if [[ "$POD_PHASE" != "Running" || "$CONTAINER_READY" != "true" ]]; then
  echo "Warning: Pod '$POD_NAME' is not in 'Running' phase or container '$TARGET_CONTAINER_NAME' is not ready."
  echo "Initiating diagnostic data collection..."

  echo "Checking Kubernetes API Server health..."
  API_SERVER_URL=$(kubectl config view --minify --output 'jsonpath={.clusters[0].cluster.server}')
  if [ -z "$API_SERVER_URL" ]; then
    echo "Error: Could not determine API Server URL from kubeconfig." >&2
    exit 1
  fi

  if API_HEALTH_CHECK=$(curl -s --fail --retry 5 --retry-delay 5 --retry-max-time 60 \
    --cacert "$KUBECTL_CONTEXT_CA_CERT" \
    --header "Authorization: Bearer $KUBECTL_CONTEXT_TOKEN" \
    "$API_SERVER_URL/healthz" 2>/dev/null); then
    echo "API Server Health: $API_HEALTH_CHECK"
  else
    echo "Error: Failed to reach Kubernetes API Server after retries." >&2
  fi

  DEBUG_LOG="$TMP_DIR/${POD_NAME}_debug_output.log"

  if kubectl debug "$POD_NAME" \
    --image="$DEBUG_IMAGE" \
    --target="$TARGET_CONTAINER_NAME" \
    --share-processes=true \
    --container="diagnoser-$(date +%s)" \
    -- /bin/sh -c "ps aux; echo '--- Netstat ---'; netstat -tulnp; echo '--- Container Logs ---'; tail -n 50 /var/log/nginx/access.log 2>/dev/null || echo 'Nginx log not found or empty';" > "$DEBUG_LOG"; then
    echo "Diagnostic output saved to $DEBUG_LOG"
    cat "$DEBUG_LOG"
  else
    echo "Error: Failed to start or execute command in ephemeral container." >&2
  fi

else
  echo "Pod '$POD_NAME' is healthy. No action needed."
fi
EOF

systemd Unit File (/etc/systemd/system/kubernetes-diagnose.service)

[Unit]
Description=Kubernetes Pod Diagnostics Service using kubectl debug
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/kubernetes-diagnose.sh

# Kubeconfigのパスは、実行ユーザーの環境変数KUBECONFIGで指定するか、


# ここで直接指定することも可能。


# Environment=KUBECONFIG=/root/.kube/config


# Kubeconfigを特定のユーザーで管理している場合、User/Groupを指定


# User=devops


# Group=devops


# ログ出力先

StandardOutput=journal
StandardError=journal

# root権限の扱いと権限分離の注意点:


# このサービスはデフォルトではrootで実行されます。


# kubectlが参照するkubeconfigファイルがroot以外に所有されている場合、


# User=devops のように適切なユーザーを指定する必要があります。


# また、エフェメラルコンテナ内の操作はPodのセキュリティに直結するため、


# スクリプト内で実行されるコマンドは最小限にし、デバッグイメージも信頼できるものを選定します。

[Install]
WantedBy=multi-user.target

systemd Timer File (/etc/systemd/system/kubernetes-diagnose.timer)

[Unit]
Description=Run Kubernetes Pod Diagnostics Service every 5 minutes

[Timer]
OnUnitActiveSec=5min # 5分ごとにサービスを実行
AccuracySec=1min     # サービス起動の精度（最大1分のずれを許容）

[Install]
WantedBy=timers.target

3. 検証

systemdサービスとタイマーを有効化し、動作を確認します。

# systemd設定をリロード

sudo systemctl daemon-reload

# タイマーを有効化して開始

sudo systemctl enable kubernetes-diagnose.timer
sudo systemctl start kubernetes-diagnose.timer

# タイマーが動作していることを確認

systemctl list-timers | grep kubernetes-diagnose

# サービスが実行されたことを確認（数分待機するか、手動でサービスを実行）


# sudo systemctl start kubernetes-diagnose.service # 即時実行する場合

journalctl -u kubernetes-diagnose.service --since "1 hour ago"

# デプロイしたNginx Podを一時的にダウンさせて、診断スクリプトが反応するか確認


# kubectl scale deployment debug-nginx-deployment --replicas=0


# kubectl scale deployment debug-nginx-deployment --replicas=1 # 元に戻す

ログには、診断スクリプトの出力と、エフェメラルコンテナから収集された情報が表示されるはずです。

4. 運用

4.1 権限管理とRBACのベストプラクティス

  • kubectl debugコマンドを使用するユーザーや自動化スクリプトには、必要最小限のRBAC権限のみを付与します。

  • pods/ephemeralcontainersリソースへのcreate権限は、デバッグ作業を行うDevOpsチームやCI/CDパイプラインに限定すべきです。

  • --privilegedオプションやhostPID共有を伴うデバッグセッションは、厳格な監査と承認プロセスを設けるべきです。

4.2 使用するデバッグイメージの選定と管理

  • busyboxやalpine/gitのような軽量で必要最低限のツールが揃ったイメージをベースに、必要なデバッグツール（strace, tcpdump, gdbなど）を追加したカスタムイメージを作成・管理することが推奨されます。

  • デバッグイメージは定期的に更新し、脆弱性がないかスキャンします。

4.3 ログ収集と監査

kubectl debugコマンドの実行は、Kubernetesの監査ログに記録されます。これをSIEMや集中ログ管理システムに連携し、不正な利用がないか監視します。エフェメラルコンテナ内で行われた操作も、可能であればコンテナの標準出力/エラー出力を収集し、後から追跡できるようにします。

4.4 環境変数やシークレットの扱い

エフェメラルコンテナ内で環境変数やシークレットを利用する必要がある場合、通常のPodと同様にKubernetesの仕組み（envFrom, volumeMount）を利用して安全に渡すことを検討します。ただし、デバッグコンテナは通常、本番コンテナの環境を模倣するため、機密情報へのアクセスは厳重に管理する必要があります。

5. トラブルシュート

5.1 エフェメラルコンテナが起動しない場合

  • Kubernetesバージョン: クラスターがKubernetes 1.25以降であることを確認します。

  • RBAC権限: kubectl debugを実行するユーザーまたはサービスアカウントにpods/ephemeralcontainersリソースに対するcreate権限があるか確認します。

  • Podの状態: デバッグ対象のPodがRunning状態であるかを確認します。

  • リソース不足: ノードのリソース（CPU, メモリ）が枯渇していないか確認します。

  • イメージのPullエラー: 指定したデバッグイメージが存在しない、またはPullできない（レジストリ認証失敗など）場合があります。kubectl describe pod <pod-name>でイベントログを確認します。

5.2 デバッグセッションが接続できない場合

  • ネットワークポリシー: クラスターに適用されているネットワークポリシーが、エフェメラルコンテナから必要な通信をブロックしていないか確認します。

  • ファイアウォール: ノードのファイアウォール設定が通信を妨げていないか確認します。

  • --share-processes=true: PID名前空間を共有しない場合、既存のコンテナのプロセスが見えないことがあります。

5.3 リソース枯渇やパフォーマンスへの影響

エフェメラルコンテナは一時的ですが、その実行中はノードのリソース（CPU, メモリ）を消費します。大量のエフェメラルコンテナを同時に起動したり、リソースを多く消費するデバッグツールを使用したりすると、ノードや既存のワークロードのパフォーマンスに影響を与える可能性があります。必要なときのみ起動し、使用後は速やかに終了するようにします。

5.4 kubectl debugコマンドのエラーメッセージ

kubectl debugコマンドは、内部でAPIコールを実行します。エラーが発生した場合は、出力されるメッセージを注意深く読み、Kubernetes APIサーバーのログ(kubectl logs -n kube-system <api-server-pod>)やKubeletのログ(journalctl -u kubelet)も参照して原因を特定します。

6. まとめ

kubectl debugとエフェメラルコンテナは、Kubernetes環境におけるアプリケーションのトラブルシューティングを効率的かつ非侵襲的に行うための強力なツールです。本記事で紹介した安全なBashスクリプト、jqやcurlを活用したデータ処理、そしてsystemdによる自動化は、DevOpsエンジニアが日々の運用で直面する課題解決に役立つでしょう。

これらのツールを適切に利用することで、本番環境の安定性を保ちつつ、迅速な問題特定と解決が可能になります。しかし、その強力さゆえに、権限管理、イメージの選定、監査といったセキュリティ面の配慮が不可欠であることを常に意識しておくべきです。

文書情報

記事タイトル
kubectl debugとエフェメラルコンテナを活用したKubernetesトラブルシューティング
作成日
更新日
Source URL
https://papanda925.com/?p=4764

ライセンス: 本記事のうち、当サイトが権利を有する本文・自作図表は、特記なき限り CC BY 4.0 で利用できます。生成AIを活用して作成・編集した内容を含みます。コードについて、別途ライセンス表示またはリンク先GitHubリポジトリのライセンスがある場合は、その条件を優先します。引用・第三者資料・画像・商標等は本ライセンスの対象外です。 利用ポリシー

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