Goアプリケーション Dockerコンテナ構築標準仕様書

1. はじめに：標準化の目的と基本原則

クラウドネイティブ時代において、コンテナは単なる実行単位ではなく、セキュリティとデリバリ速度を担保する境界線です。本仕様書は、DevSecOpsの観点から、プロダクション環境において最高レベルの信頼性を発揮するGoアプリケーションの構築基準を定義します。

本標準が掲げる「軽量・高速・最小権限」の3原則は、単なる効率化の追求ではなく、システムの堅牢性を高めるための戦略的要件です。

3つの柱（基本原則）

• 軽量（Lightweight）
  • 攻撃対象領域（Attack Surface）の削減: 不要なバイナリ、シェル、ビルドツールを徹底的に排除し、脆弱性が混入する余地を最小化します。
  • リソース最適化: イメージサイズを削減し、コンテナレジストリのストレージコストとデプロイ時の転送負荷を軽減します。
• 高速（Fast）
  • ビルド時間の短縮: Dockerレイヤーキャッシュを高度に活用し、CI/CDパイプラインの回転率を最大化します。
  • スケーラビリティの向上: 軽量なイメージはコールドスタート時の起動速度を早め、急激なトラフィック変動への耐性を強化します。
• 最小権限（Least Privilege）
  • 侵害範囲の局所化: 非rootユーザー実行と権限の剥奪を義務付け、万が一の侵入時もホストシステムや隣接コンテナへの影響を遮断します。
  • 実行時保護: 読み取り専用ファイルシステムにより、動的な不正コードの注入を物理的に防止します。

適用範囲

本仕様書は、新規に開発されるすべてのGoプロジェクト、および既存プロジェクトのモダナイズ実施時に強制適用されます。

--------------------------------------------------------------------------------

2. 技術スタックおよびバージョン管理基準

メンテナンス性とパフォーマンスを最大化するため、Go 1.26以降を標準ランタイムとして採用します。最新バージョンの採用は、コンパイラ最適化による実行速度向上だけでなく、最新のセキュリティ脅威からの保護を意味します。

2.1 Goランタイム基準（Go 1.26）

• 最新機能の活用要件:
  • errors.AsType[T]: ジェネリクスを用いた型安全なエラーハンドリングを必須とし、冗長なエラーunwrap処理を排除します。
  • crypto/rand: セッションID等の生成には、標準ライブラリで簡略化された安全なランダム文字列生成機能を活用します。
  • new(v) 構文: プリミティブ型へのポインタ取得を簡素化し、コードの可読性を高めます。
• 構造化ロギング: log/slog を標準とし、MultiHandler を用いて標準出力と監視サービスへの同時送信を実現します。
• JSON処理: encoding/json/v2 を採用します。特にフロントエンドとの不整合を防ぐため、以下の設定を標準とします。
  • nilスライスの空配列化: デフォルトで nil を [] として出力し、フロントエンドでのヌルポインタ参照を防止。
  • 厳密なマッチング: デコード時の大文字・小文字を厳密に区別し、曖昧なAPI定義を許容しません。

2.2 フレームワークおよびORM選定

• Webフレームワーク:
  • Echo (推奨): net/http 互換性と拡張性のバランスが最も優れているため、標準フレームワークとして推奨します。
  • Fiber: 極限のスループットが求められるマイクロサービスに限定して検討を許可します。ただし、fasthttp ベースによる標準ライブラリとの非互換性を設計に織り込む必要があります。
• ORM選定基準（戦略的選定）:
  • SQLC (I/O優先・標準): Docker環境（特にI/Oレイテンシが発生しやすい仮想環境）において「I/O透過性」が高く、ランタイムオーバーヘッドがほぼゼロであるため、汎用的な標準として推奨します。
  • SQLBoiler (CPU性能優先): スキーマが固定され、かつベアメタル環境に近い低レイテンシ環境で最大のCPUパフォーマンスを求める場合に採用します。
  • Ent: スキーマ駆動開発を重視し、型安全性を最優先する場合に採用します。

2.3 アップデート戦略

• Renovateによる自動追従: go.mod およびDockerfileのベースイメージタグの更新を自動化し、技術的負債の蓄積を防ぎます。
• 更新の分離: 言語バージョンやライブラリの更新は、機能リリースとは別のサイクルで実施し、障害発生時の切り分けを容易にします。

--------------------------------------------------------------------------------

3. プロジェクト構造とクリーンアーキテクチャの準拠

スケーラビリティとテスト容易性を確保するため、依存関係の方向を厳密に制御するレイヤードアーキテクチャを採用します。

3.1 ディレクトリレイアウト

• /cmd: バイナリのエントリーポイント。DI（依存注入）と初期化のみを実施。
• /internal: プロジェクト外からのインポートを禁止。ビジネスロジックの核心を配置。
• /pkg: 外部再利用可能なユーティリティ。
• /api: OpenAPI / gRPC定義ファイル。

3.2 階層構造と境界定義

「依存関係は常に内側に向かう」というルールのもと、以下の4層で構成します。

1. Domain層 (Domain Layer): エンティティとビジネスルール。
   • domain/entity: データ構造とバリデーションロジック。
   • domain/repository: データアクセスのための 「インターフェース」 を定義。外部技術（SQL）を隠蔽。
2. Usecase層 (Usecase Layer): アプリケーション固有のビジネスロジック（業務フロー）の実装。インターフェースを介してドメイン操作を実行。
3. Interface層 (Interface Adapter Layer):
   • interface/handler: HTTPリクエストの変換とユースケースの呼び出し。
   • interface/repository: Domain層のインターフェースに対する 「具体的な実装」（SQL発行等）。
4. Infrastructure層 (Infrastructure Layer): DB接続、サーバー設定、フレームワークの初期設定。

--------------------------------------------------------------------------------

4. マルチステージビルドによるイメージ最適化

ビルド用と実行用のイメージを完全に分離し、配布効率と安全性を最大化します。

4.1 ベースイメージ選定

• ビルドステージ (Builder): golang:1.26-alpine を使用。ビルドツール一式を含むフルイメージ（約800MB）ですが、最終イメージには残りません。
• 実行ステージ (Runtime): alpine:3.19 を使用。バイナリ実行に必要な最小パッケージ（約30MB）のみで構成します。

4.2 ビルド最適化要件

• .dockerignore の適用: .git, node_modules, 開発ドキュメントを除外し、ビルドコンテキストを最小化。
• キャッシュ効率化: COPY . . の前に COPY go.mod go.sum と RUN go mod download を実行し、ライブラリ層をキャッシュ。
• 静的リンクバイナリ: CGO_ENABLED=0 を明示し、Alpine環境でも安定動作するポータブルなバイナリを作成。
• バイナリサイズ削減: ldflags="-s -w" を付与し、シンボル情報を除去してサイズを約20%削減。

# ビルド例
FROM golang:1.26-alpine AS builder
RUN apk add --no-cache git
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /main .

--------------------------------------------------------------------------------

5. 実行時セキュリティと最小権限の原則

コンテナ侵害のリスクを前提とし、攻撃者が実行可能な操作をインフラレベルで封じ込めます。

5.1 非rootユーザーの実行

UID 10001の専用ユーザー（appuser）を定義し、コンテナ内での特権昇格を防止します。

RUN addgroup -g 10001 appuser && adduser -D -u 10001 -G appuser appuser
USER 10001

5.2 読み取り専用ファイルシステム

実行時は --read-only を前提とした設計とします。

• 書き込みが必要な領域（一時ファイル等）のみ、ボリュームを明示的にマウントして分離します。

5.3 Linuxケーパビリティと特権制御

• --cap-drop ALL: デフォルトで付与される全特権を剥奪。
• no-new-privileges:true: プロセスが setuid 等によって新しい特権を取得することをカーネルレベルで阻止します。
• 例外: 開発環境でのDelveデバッグ時に限り、SYS_PTRACE の一時的な付与を認めます。

--------------------------------------------------------------------------------

6. ビルド・デプロイ・運用管理基準

CI/CDパイプラインにおいて継続的に安全性を検証し、品質の一貫性を担保します。

6.1 推奨運用コマンド

本番環境での docker run は、以下のセキュリティフラグを標準セットとします。

docker run -d \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --user 10001:10001 \
  my-go-app:1.0.0

6.2 脆弱性スキャンとモニタリング

• Trivyによるスキャン: CIパイプラインでベースイメージと依存ライブラリを常時スキャンし、High以上の脆弱性が検出された場合はビルドを停止。
• 自動再ビルド: ベースイメージのセキュリティアップデートを検知した際、Renovateを通じて自動的に最新イメージへ更新されるフローを構築します。

まとめ

本仕様書の遵守により、Goアプリケーションは「外部攻撃に強く、パフォーマンス効率に優れ、運用の透明性が高い」次世代の標準を達成します。各エンジニアは、コードの書き味だけでなく、実行環境を含めたトータルなアーキテクチャの品質に責任を持つことを強く求めます。