706-technologies-containers-docker

Docker を使用した Java コンテナーイメージのベストプラクティス

Spring Boot、Quarkus、Micronaut に依存しないガイダンスを提供し、チームが Java アプリケーション向けの安全で再現可能、かつ保守しやすい Docker コンテナーイメージを構築できるよう支援します。

このスキルで扱う内容

• Java アプリケーション向け Dockerfile の構成：マルチステージビルド、Maven 依存関係のキャッシュ、決定的なアーティファクトのコピー、カスタムランタイムの jlink、.dockerignore
• 実行時イメージの選択：Alpaquita などのマイクロディストリビューション、最小限の JRE イメージ、適切な場合のバージョンまたはダイジェストの固定、イメージラベル、明示的なエントリーポイント
• JVM のコンテナー対応：メモリ割合のフラグ、起動時の動作、正常なシャットダウンシグナル、タイムゾーン、予測可能な実行時オプション
• セキュリティのデフォルト設定：非 root ユーザー、最小権限、レイヤーへのシークレットの埋め込み禁止、パッケージマネージャーの削減、脆弱性スキャン、SBOM の考慮、特権コンテナーの回避
• 運用準備：適切な場合のヘルスチェック、stdout/stderr ロギング、ポート宣言、イメージサイズの管理、ビルドの再現性、CI による検証

対象範囲： Java プロジェクトにおける、フレームワークに依存しない Docker とコンテナーイメージの品質です。フレームワークの実行時設定については、対応する Spring Boot、Quarkus、または Micronaut のスキルを参照してください。Testcontainers ベースのテストについては、該当するテストスキルを参照してください。

制約事項

ユーザーからフレームワーク固有の設定を明示的に求められない限り、推奨事項は Dockerfile、イメージのビルド、実行時コンテナーのレイヤーに限定してください。このリポジトリの XML ソースを編集した後は、スキルを再生成してビルドを検証してください。

• 必須：同じ変更セットで Java または Maven の変更を提案する前に、./mvnw compile または mvn compile を実行してください
• シークレット：認証情報、トークン、秘密鍵、シークレットを含む Maven 設定、環境固有のシークレットを、イメージレイヤー、ラベル、引数、ログに決して埋め込まないでください
• セキュリティ：特権を持たない実行、最小権限のファイルシステム権限、マイクロランタイムイメージ、明示的なコンテナー機能を優先し、デフォルトで特権を付与する設定は避けてください
• JLINK：モジュールグラフが既知で、実行時に検証され、アプリケーションの依存関係と互換性がある場合は、本番イメージに jlink カスタムランタイムを優先してください
• 再現性：ベースイメージのバージョンを意図的に固定し、ダイジェストを使用する場合のトレードオフを記載し、ビルド入力を明示し、ネットワークに依存する起動時の処理を避けてください
• JVM：本番環境で使用可能と判断する前に、JVM フラグ、正常なシャットダウン動作、観測可能な起動失敗を通じて、コンテナーのメモリ制限と CPU 制限に対応してください
• 境界：Spring Boot の実行時の動作については @301-frameworks-spring-boot-core、Quarkus の実行時の動作については @401-frameworks-quarkus-core、Micronaut の実行時の動作については @501-frameworks-micronaut-core、Testcontainers のセットアップについては該当するテストスキルを参照してください
• 検証：変更を採用する前に、./mvnw clean verify または mvn clean verify を実行してください
• エッジケース：対象の Java バージョン、ビルドツール、デプロイプラットフォーム、ベースイメージのポリシー、レジストリのポリシー、またはセキュリティスキャナーが不明で、推奨事項に影響する場合は、コンテナー関連の成果物を編集する前に確認してください
• エッジケース：依頼された変更がセキュリティポリシー、イメージの来歴、エアギャップビルド、または実行時のプラットフォーム制約と競合する場合は、トレードオフを説明し、確認を求めてください

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

• Java の Dockerfile をレビューする
• Docker イメージのセキュリティを改善する
• Java コンテナーに jlink ランタイムを追加する
• Java プロジェクトにコンテナー化を追加する
• Java コンテナーイメージのサイズを最適化する
• Docker ビルドの再現性をレビューする

ワークフロー

1. リファレンスを読み、コンテナのコンテキストを評価する

変更を提案する前に、references/706-technologies-containers-docker.md を読み、現在の Dockerfile、.dockerignore、Maven のビルド入力、イメージのビルドスクリプト、CI ジョブ、レジストリのポリシー、デプロイ上の制約を確認します。

2. ランタイムとサプライチェーンの制約を特定する

Java のバージョン、ビルドツール、jlink のモジュール要件、軽量ディストリビューションとの互換性、対象プラットフォーム、ベースイメージのポリシー、レジストリの要件、脆弱性スキャナー、SBOM の要件、メモリ制限、公開ポート、運用上の準備要件を確認します。

3. コンテナに適した変更を適用する

リファレンスのパターンとプロジェクトの規約に沿って、Docker およびコンテナのビルド成果物を実装またはリファクタリングします。明示的に依頼されていない限り、フレームワーク固有のランタイム動作は対象外とします。

4. 検証を実行し、結果を報告する

適切なビルド、イメージのビルド、スキャン、スモークテスト、ジェネレーターのチェックを実行し、変更内容、検証内容、残るコンテナ関連のリスクをまとめます。

リファレンス

詳細なガイダンス、例、制約については、references/706-technologies-containers-docker.md を参照してください。