導入: なぜコンテナのリモートデバッグが必要なのか
開発現場で「ローカル環境では正常に動くのに、コンテナ環境だと特定の条件下でバグが発生する」という経験はありませんか。コンテナ内へのログイン（docker exec）によるログ出力や、一時的なコード修正によるデバッグには限界があります。本稿では、コンテナを再起動することなく、ホスト側のIDEから直接コンテナ内のプロセスにアタッチし、ブレークポイントを張って変数の状態を確認する手法を解説します。これにより、環境差異による不具合調査の効率が飛躍的に向上します。
基礎知識: リモートデバッグの仕組み
リモートデバッグとは、実行中のプロセスに対し、デバッガがネットワーク経由で通信を行い、実行を中断（停止）させたり、メモリ状態を読み取ったりする技術です。通常、言語ランタイム（JavaのJDWP、Pythonのdebugpy、Node.jsのInspectorなど）が専用のデバッグポートを公開し、IDEがそこに接続することで実現します。コンテナ環境では、コンテナ内部のポートをホスト側にマッピング（-pオプション）しておく必要があります。
実装/解決策: IDE連携の準備とアタッチ手順
手順は以下の3ステップです。
1. Dockerfileまたはdocker-compose.ymlで、デバッグ用ポートを公開する。
2. アプリケーションをデバッグモードで起動し、外部からの接続を許可する。
3. IDE側の「Remote Debug」設定を作成し、コンテナのIPとポートを指定してアタッチする。
サンプルプログラム: Python (debugpy) を用いたコンテナデバッグ例
以下の例は、Pythonのdebugpyを利用してコンテナ内のプロセスにリモート接続するための設定です。
Dockerfile:
デバッグ用ポート（5678）を公開
EXPOSE 5678
docker-compose.yml:
services:
app:
build: .
ports:
- “5678:5678” # ホスト側ポート:コンテナ側ポート
app.py:
import debugpy
0.0.0.0を指定することで、コンテナ外部（ホスト）からの接続を許可
debugpy.listen((“0.0.0.0”, 5678))
print(“デバッガの接続を待機しています…”)
IDEで準備が整うまで待機する（必要に応じて）
debugpy.wait_for_client()
def calculate_sum(a, b):
# ここにブレークポイントを張る
result = a + b
return result
print(calculate_sum(10, 20))
応用・注意点: 現場で役立つTIPSと罠
1. 本番環境での使用厳禁
デバッグポートを開放したまま本番環境にデプロイすると、外部から任意コードを実行される重大なセキュリティリスクとなります。必ず開発環境（Development）のみで有効化するようにしてください。
2. コンテナのライフサイクル管理
プロセスが終了するとデバッグ接続も切断されます。長時間起動し続ける常駐プロセスであれば問題ありませんが、ジョブ系コンテナの場合は、プロセスが終了しないようにダミーの待機処理を入れるなどの工夫が必要です。
3. ファイルパスの差異
IDE上のソースコードパスと、コンテナ内の絶対パスが一致しない場合、ブレークポイントが正しく機能しません。VS Codeのlaunch.jsonなどで「pathMappings」を設定し、ホストとコンテナのディレクトリを正しくマッピングすることが重要です。この設定を怠ると、「ソースが見つかりません」というエラーに直面することが多いので注意してください。
コメント