infra(app): Phase 1 Sprint 2 — tasks-webapi コンテナイメージ(GraalVM Native Image、IAM 認証クライアント込み)(S2Infra-1)

[win2cot]

親: #206(Sub-issues 参照)

概要

tasks-webapi のコンテナイメージ作成基盤を実装する(infrastructure-plan §6 S2Infra-1)。手段は ADR-0018 で bootBuildImage(Cloud Native Buildpacks)に確定済み。RDS IAM 認証クライアント設定を含む。

方針(確定済み — ADR-0018 / PR #492)

• 手段 = Spring Boot bootBuildImage。Dockerfile は作成しない
• builder / run image = Spring Boot 4 既定(builder-noble-java-tiny / ubuntu-noble-run-tiny)、差し替えなし
• リンク方式 = mostly-static(glibc)
• Native 化を阻む重大な課題(hints で解決不能な依存の Native 非対応等)が見つかった場合は本 Issue 内で代替構成に走らず、ADR-0008 / ADR-0018 再検討 Issue を起票して判断する
• 実装主体 = ローカル Claude Code + win2cot 検証(claude-automation 不適用)

やること

• webapi/build.gradle に org.graalvm.buildtools.native プラグイン追加 + bootBuildImage 最小設定
• builder / run image のバージョン pin(digest 固定 or latest 追従)の要否を判断し、結論と理由を PR に記録
• native build を通す。必要な reflection hints は @RegisterReflectionForBinding / META-INF/native-image/ に集約(AWS JDBC ドライバ / IAM 認証周りを重点確認)
• コンテナイメージは全環境共通・環境別ファイル非同梱(確定前提)、環境差は env vars 注入
• JST 統一(docs: JST 全層統一(設計規約 §2.4 / コーディング規約 §12.1 反転 + infrastructure-plan に JVM/ECS TZ 明文化) #265 / ADR-0009)を native 実行で担保。JAVA_TOOL_OPTIONS は native バイナリに無効のため TZ env で実現し、docs: JST 全層統一(設計規約 §2.4 / コーディング規約 §12.1 反転 + infrastructure-plan に JVM/ECS TZ 明文化) #265 の「Native Image 後の挙動要再検証」をここで解消
• :webapi:nativeCompile が単体実行可能なことを確認(infra(ci-cd): Phase 1 Sprint 2 — tasks-webapi nativeBuild CI job(PR トリガー、changes ゲート)(S2Infra-8) #490 の PR トリガー CI job が直接呼ぶ前提。workflow 自体は infra(ci-cd): Phase 1 Sprint 2 — tasks-webapi nativeBuild CI job(PR トリガー、changes ゲート)(S2Infra-8) #490 スコープ)
• ローカルでの build / 起動確認手順を docs/specs/local-setup.md に追記(Native build をローカル開発の必須にしない、ADR-0008「ローカル開発戦略」)
• infrastructure-plan §6 S2Infra-1 行(「webapi/Dockerfile を作成」)の doc 同期

受入基準

• ./gradlew :webapi:bootBuildImage 成功 + ローカル起動で /actuator/health 応答(native 実行)
• イメージに環境固有値が焼き込まれていない(env vars 注入で設定が変わることを確認)
• API JSON の日時が +09:00 で出力される(native 実行で確認)
• PR 本文に検証ログを記録(起動時間・イメージサイズ実測、追加 hints 一覧と理由、pin 判断、持ち越し事項)

関連

• ADR-0018(手段確定、PR docs(adr): ADR-0018 採用 — コンテナイメージ作成手段に bootBuildImage(Cloud Native Buildpacks)を確定 #492)/ ADR-0008 / infrastructure-plan §6 / [Phase 1 Infra] Setup 0-2 + Sprint 0-5 Infra ストリーム横断 tracker #206 / Parameter Store 方針(設計規約 §5.4)/ docs: JST 全層統一(設計規約 §2.4 / コーディング規約 §12.1 反転 + infrastructure-plan に JVM/ECS TZ 明文化) #265(JST 統一)/ infra(ci-cd): Phase 1 Sprint 2 — tasks-webapi nativeBuild CI job(PR トリガー、changes ゲート)(S2Infra-8) #490(nativeBuild CI、blocked by 本 Issue)

[win2cot]

Claude Code 実装プロンプト(#478)

ローカル Claude Code で実装する際のキックオフプロンプト。Cowork 駆動 / claude-automation 不適用。

Issue #478(S2Infra-1)を実装してください: tasks-webapi のコンテナイメージ作成基盤(GraalVM Native Image)。

前提(必読)

• 作業開始前に main を pull すること(ADR-0018 が merge 済み)。ブランチ名は feat/478-container-image-bootbuildimage とする
• 正本: docs/adr/0018-container-image-build-with-boot-build-image.md(手段の決定と理由)、docs/adr/0008-graalvm-native-image.md(背景)、本 Issue 本文(受入基準)
• 決定済み事項(再検討しない): 手段 = bootBuildImage(Cloud Native Buildpacks)、Dockerfile は作らない、builder/run image は Spring Boot 4 既定(builder-noble-java-tiny / ubuntu-noble-run-tiny)、リンク方式 = mostly-static(glibc)
• 着手前に docker info で Docker daemon が使えることを確認(bootBuildImage に必須)

やること

1. webapi/build.gradle に org.graalvm.buildtools.native プラグインを追加(バージョンは Spring Boot 4.0.6 のプラグイン整合で選定)。これだけで bootBuildImage が native モードになる
2. bootBuildImage の設定は最小限(imageName 程度)。builder/run image のバージョン pin(digest 固定 or latest 追従)の要否を判断し、結論と理由を PR 本文に記録
3. ./gradlew :webapi:bootBuildImage を実行し、落ちた箇所に reflection hints を追加して通るまで反復。hints は Spring Boot AOT の自動解析を優先し、手動分は @RegisterReflectionForBinding または META-INF/native-image/ に集約(ADR-0008 §6 / コーディング規約 §20.1)。AWS JDBC ドライバ(aws-advanced-jdbc-wrapper)/ IAM 認証周りで hints が必要になる可能性が高い
4. ローカル起動確認: 既存のローカル開発手順(docs/specs/local-setup.md を確認、MySQL コンテナ起動はそれに倣う)で native イメージを起動し検証
   • /actuator/health が応答する
   • TZ=Asia/Tokyo env で API JSON の日時が +09:00 で出力される(注意: JAVA_TOOL_OPTIONS は native バイナリに無効。TZ env で行う。docs: JST 全層統一(設計規約 §2.4 / コーディング規約 §12.1 反転 + infrastructure-plan に JVM/ECS TZ 明文化) #265 の「Native Image 後の挙動要再検証」の解消を兼ねる)
   • イメージに環境固有値が焼き込まれていない(env vars 注入で設定が変わる)
   • TLS(ビルド時 cacerts 同梱)の検証はローカルで可能な範囲でよい。RDS/Keycloak への実接続検証は dev 環境構築後(S2Infra-2 以降)に持ち越し可。持ち越す場合は PR 本文に明記
5. ローカルでの build / 起動確認手順を docs/specs/local-setup.md に追記(Native build をローカル開発の必須にしない、という ADR-0008 の方針を崩さない書き方)
6. docs/architecture/infrastructure-plan.md §6 の S2Infra-1 行(「webapi/Dockerfile を作成」)を本実装の成果に合わせて doc 同期
7. :webapi:nativeCompile task が単体で実行可能なことを確認(後続 infra(ci-cd): Phase 1 Sprint 2 — tasks-webapi nativeBuild CI job(PR トリガー、changes ゲート)(S2Infra-8) #490 の PR トリガー CI job がこの task を直接呼ぶ。CI workflow 自体は infra(ci-cd): Phase 1 Sprint 2 — tasks-webapi nativeBuild CI job(PR トリガー、changes ゲート)(S2Infra-8) #490 スコープなので作らない)

守ること

• CLAUDE.md / docs/specs/コーディング規約.md / docs/specs/設計規約.md に従う(Spotless、NullAway、ADR 運用等)
• commit 前に ./gradlew :webapi:spotlessApply と ./gradlew :webapi:check を通す
• PR は Closes #478 で作成。本文に: 実施内容 / pin 判断の結論と理由 / 追加した hints の一覧と理由 / 検証結果(上記 4 の各項目、起動時間・イメージサイズ実測含む)/ 持ち越し事項
• 通常 CI(JVM build + test)は native build を検証しない。PR 本文の検証結果セクションがその代わりになるため、検証ログを必ず残す

停止して win2cot に相談する条件

• 依存ライブラリの Native 非対応など、hints 追加で解決できない重大な障害(ADR-0018 の方針: 勝手に代替構成へ走らず、ADR-0008/0018 再検討 Issue の起票を提案して止まる)
• ビルドは通るが受入基準のいずれかがどうしても満たせない
• スコープ外の変更(既存コードの広範な改修、新規 ADR が必要な判断)が必要に見えた場合