container-development

コンテナ開発

セキュリティ最優先、軽量なコンテナイメージ、12 ファクターアプリの方法論を重視した、コンテナ化とオーケストレーションに関する専門知識です。

このスキルを使用するタイミング

次の場合はこのスキルを使用します…	次の場合は言語固有の関連スキル（go-containers、nodejs-containers、python-containers）を使用します…
言語に依存しない Dockerfile を作成または最適化する	Go の静的バイナリ、Node.js の Alpine ビルド、または Python の slim イメージを最適化する
マルチステージビルドのパターンや 12 ファクター構成を作成する	イメージサイズの目標が、言語ランタイムの選択（scratch、distroless、musl/glibc）によって大きく左右される
コンテナを強化する（非 root、最小限のベース、シークレット）	Skaffold 同期（skaffold-filesync）または OrbStack ネットワーキング（skaffold-orbstack）を実行する
Docker Compose でサービスを構成する	作業が Skaffold のデプロイ前テスト（skaffold-testing）のみである

セキュリティ方針（譲れない要件）

非 root は必須です：本番環境のすべてのコンテナは、必ず非 root ユーザーで実行しなければなりません。これは任意ではありません。

最小限のベースイメージ：Node.js／Go／Rust には Alpine（約 5MB）を使用します。Python には slim（約 50MB）を使用します（Alpine では musl 互換性の問題があるため）。

マルチステージビルドが必須です：ビルド環境と実行環境を分離します。ビルドツールを本番イメージに含めてはいけません。

主な専門分野

コンテナイメージの構築

• Dockerfile／Containerfile の作成：明確で効率的、かつ保守しやすいコンテナビルド手順
• マルチステージビルド：最小限で本番環境に対応したイメージの作成
• イメージの最適化：イメージサイズの縮小、レイヤー数の最小化、ビルドキャッシュの最適化
• セキュリティ強化：非 root ユーザー、最小限のベースイメージ、脆弱性スキャン

コンテナオーケストレーション

• サービスアーキテクチャ：適切なサービスディスカバリーを備えたマイクロサービス
• リソース管理：CPU／メモリー制限、自動スケーリングポリシー、リソースクォータ
• ヘルスチェックとモニタリング：ヘルスチェック、レディネスプローブ、可観測性のパターン
• 構成管理：環境変数、シークレット、構成管理

主な機能

• 12 ファクターへの準拠：特に構成とステートレス性について、コンテナ化されたアプリケーションが 12 ファクターの原則に従うようにします
• ヘルスと信頼性：適切なヘルスチェック、レディネスプローブ、再起動ポリシーを実装します
• Skaffold ワークフロー：効率的な開発サイクルを実現できるよう、コンテナ化されたアプリケーションを構成します
• オーケストレーションパターン：サービスメッシュ、ロードバランシング、コンテナ間通信を設計します
• パフォーマンスチューニング：コンテナのリソース使用量、起動時間、実行時のパフォーマンスを最適化します

イメージ作成のプロセス

1. 分析：アプリケーションの依存関係とビルドプロセスを把握します
2. 構成：ビルド時と実行時の要件を分離したマルチステージ Dockerfile を設計します
3. 除外：包括的な .dockerignore ファイルを作成します
4. ビルドとスキャン：イメージをビルドし、脆弱性をスキャンします
5. 改善：レイヤーキャッシュを最適化し、サイズを縮小し、セキュリティ上の問題に対処するために反復します
6. 検証：イメージが正しく実行され、12 ファクターの原則に準拠していることを確認します

ベストプラクティス

最適化の基本原則

1. マルチステージビルド（必須）：

• ビルド時の依存関係を実行時の依存関係から分離します
• ビルドツールを本番イメージに含めないようにします
• 一般的な削減率：最終イメージを 60～90％縮小

2. 最小限のベースイメージ：

• 要件を満たす最小のベースから始めます
• ほとんどの言語では Alpine を優先します（Python を除く）
• 最大限のセキュリティを求める場合は distroless を検討します

3. 非 root ユーザー（必須）：

• 必ず非 root ユーザーを作成して使用します
• UID／GID を明示的に設定します（例：1001）
• セキュリティコンプライアンス要件です

4. .dockerignore（必須）：

• .git、node_modules、__pycache__ を除外します
• シークレットや開発用ファイルがイメージに入らないようにします
• ビルドコンテキストを 90～98％削減します

5. レイヤーの最適化：

• 依存関係マニフェストをソースコードとは別にコピーします
• 変更頻度の高いレイヤーを最後に配置します
• 関連する RUN コマンドを && でまとめます

バージョンの確認

重要：ベースイメージを使用する前に、最新バージョンを確認してください。

• Node.js Alpine：最新の LTS を Docker Hub node で確認してください
• Python slim：最新バージョンを Docker Hub python で確認してください
• Go Alpine：最新バージョンを Docker Hub golang で確認してください
• nginx Alpine：Docker Hub nginx で確認してください
• Distroless：最新バージョンを Google distroless で確認してください

WebSearch または WebFetch を使用して、現在のバージョンを確認してください。

言語別の最適化

言語別の詳しい最適化パターンについては、専用のスキルを参照してください。

言語	スキル	主な最適化	一般的な削減効果
Go	go-containers	静的バイナリ、scratch/distroless	846MB → 2.5MB（99.7%）
Node.js	nodejs-containers	Alpine、マルチステージ、npm/yarn/pnpm	900MB → 100MB（89%）
Python	python-containers	Slim（Alpine ではないもの）、uv、venv	1GB → 100MB（90%）

ベースイメージのクイックガイド

適切なベースイメージを選択してください：

• Go：scratch または distroless/static（2-5MB）
• Node.js：node:XX-alpine（50-150MB）
• Python：python:XX-slim（80-120MB）- Python では Alpine を使用しないでください！
• Nginx：nginx:XX-alpine（20-40MB）
• 静的ファイル：scratch または nginx:alpine（最小限）

マルチステージビルドのテンプレート

# Build stage - includes all build tools
FROM <language>:<version> AS builder
WORKDIR /app

# Copy dependency manifests first (better caching)
COPY package.json package-lock.json ./  # or go.mod, requirements.txt, etc.

# Install dependencies
RUN <install-command>

# Copy source code
COPY . .

# Build application
RUN <build-command>

# Runtime stage - minimal
FROM <minimal-base>
WORKDIR /app

# Create non-root user
RUN addgroup --gid 1001 appgroup && \
    adduser --uid 1001 --gid 1001 --disabled-password appuser

# Copy only what's needed from builder
COPY --from=builder --chown=appuser:appuser /app/dist ./dist

USER appuser
EXPOSE <port>

HEALTHCHECK --interval=30s CMD <health-check-command>

CMD [<start-command>]

セキュリティ要件（必須）

• 非 root ユーザー：必須。本番環境では root として実行しないでください
• 最小限のベースイメージ：実用可能な中で最小のベースイメージを選択してください
  • 一般的な CVE の削減：50-100%（完全なベース：50-70 CVE → 最小限：0-12 CVE）
  • シェルがなければ、シェルインジェクション攻撃は発生しません
  • パッケージマネージャーがなければ、サプライチェーン攻撃は発生しません
• マルチステージビルド：必須。ビルドツールを実行時環境に含めないでください
• HEALTHCHECK：Kubernetes のライブネス／レディネスプローブに必須です
• 脆弱性スキャン：CI で Trivy、Grype、または Docker Scout を使用してください
• バージョンの固定：必ず具体的なタグ（例：node:20.10-alpine）を使用し、latest は使用しないでください
• .dockerignore：必須。シークレット、.env、.git がイメージに含まれるのを防ぎます

最適化全体による一般的な効果：

• イメージサイズ：85-99% 削減
• セキュリティ：CVE が 70-100% 減少
• プル時間：80-98% 短縮
• ビルド時間：40-60% 短縮（適切なキャッシュを使用した場合）
• メモリ使用量：60-80% 削減
• ストレージコスト：90-99% 削減

12-Factor App の原則

• 環境変数による設定
• ステートレスなプロセス
• 明示的な依存関係
• サービスのポートバインディング
• グレースフルなシャットダウン処理

コンテナラベル（OCI アノテーション）

コンテナラベルは、イメージの検索、リンク、ドキュメント用のメタデータを提供します。GitHub Container Registry（GHCR）は OCI アノテーションに対応しており、イメージをリポジトリにリンクして説明を表示できます。

GHCR で必須のラベル

ラベル	目的	例
org.opencontainers.image.source	イメージをリポジトリにリンクします（GHCR の機能を有効にします）	https://github.com/owner/repo
org.opencontainers.image.description	パッケージの説明（最大 512 文字）	Production API server
org.opencontainers.image.licenses	SPDX ライセンス識別子（最大 256 文字）	MIT、Apache-2.0

推奨ラベル

ラベル	目的	例
org.opencontainers.image.version	セマンティックバージョン	1.2.3
org.opencontainers.image.revision	Git コミット SHA	abc1234
org.opencontainers.image.created	ビルドのタイムスタンプ（RFC 3339）	2025-01-19T12:00:00Z
org.opencontainers.image.title	人が読める名前	My Application
org.opencontainers.image.vendor	組織名	Forum Virium Helsinki
org.opencontainers.image.url	プロジェクトのホームページ	https://example.com
org.opencontainers.image.documentation	ドキュメントの URL	https://docs.example.com

Dockerfile でのラベルの追加

# Static labels (set at build time)
LABEL org.opencontainers.image.source="https://github.com/owner/repo" \
      org.opencontainers.image.description="Production API server" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.vendor="Forum Virium Helsinki"

# Dynamic labels (via build args)
ARG VERSION=dev
ARG BUILD_DATE
ARG VCS_REF

LABEL org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.created="${BUILD_DATE}" \
      org.opencontainers.image.revision="${VCS_REF}"

ビルド時のラベルの追加

docker build \
  --label "org.opencontainers.image.source=https://github.com/owner/repo" \
  --label "org.opencontainers.image.description=My container image" \
  --label "org.opencontainers.image.licenses=MIT" \
  --build-arg VERSION=1.2.3 \
  --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --build-arg VCS_REF=$(git rev-parse --short HEAD) \
  -t myapp:1.2.3 .

docker/metadata-action を使った GitHub Actions

docker/metadata-action は、リポジトリのメタデータから OCI ラベルを自動生成します。

- id: meta
  uses: docker/metadata-action@v5
  with:
    images: ghcr.io/${{ github.repository }}
    labels: |
      org.opencontainers.image.title=My Application
      org.opencontainers.image.description=Production API server
      org.opencontainers.image.vendor=Forum Virium Helsinki

- uses: docker/build-push-action@v6
  with:
    labels: ${{ steps.meta.outputs.labels }}

metadata-action が自動生成するラベル：

• org.opencontainers.image.source（リポジトリ URL から取得）
• org.opencontainers.image.revision（コミット SHA から取得）
• org.opencontainers.image.created（ビルドのタイムスタンプ）
• org.opencontainers.image.version（タグ／参照から取得）

Skaffold の推奨事項

• ローカル開発では Docker Compose より Skaffold を優先します
• ホットリロードを使った継続的な開発ループ
• 本番環境に近いローカル環境

エージェント向けの最適化

コンテナのビルドとテストを行う際は、フィードバックを速めるために次の最適化を使用してください。

コンテキスト	コマンド	目的
クイックビルド	DOCKER_BUILDKIT=1 docker build --progress=plain -t app .	BuildKit をプレーンな出力で使用
キャッシュを使ったビルド	docker build --cache-from app:latest -t app:new .	前回のビルドのレイヤーを再利用
セキュリティスキャン	docker scout cves app:latest | head -50	脆弱性をすばやくチェック
サイズ分析	docker images app --format "{{.Size}}"	イメージサイズを確認
レイヤーの検査	docker history app:latest --human --no-trunc	レイヤーサイズを分析
キャッシュなしでビルド	docker build --no-cache --progress=plain -t app .	クリーンビルドを強制
コンテナのテスト	docker run --rm -it app:latest /bin/sh	対話形式でテスト
クイックヘルスチェック	docker run --rm app:latest timeout 5 /health	起動を確認

ビルド最適化フラグ：

• --target=<stage>：特定のステージのみをビルドします（反復を高速化）
• --build-arg BUILDKIT_INLINE_CACHE=1：インラインキャッシュを有効にします
• --secret id=key,src=file：シークレットをイメージに含めずにマウントします

Dockerfile の最適化手法、オーケストレーションパターン、セキュリティ強化、Skaffold の設定について詳しくは、REFERENCE.md を参照してください。

関連スキル

言語固有のコンテナ最適化：

• go-containers - Go の静的バイナリ、scratch／distroless（846MB → 2.5MB）
• nodejs-containers - Node.js の Alpine パターン、npm／yarn／pnpm（900MB → 100MB）
• python-containers - Python slim（Alpine は使用しない）、uv／poetry（1GB → 100MB）

関連コマンド

• /configure:container - コンテナインフラストラクチャの包括的な検証
• /configure:dockerfile - Dockerfile 固有の設定
• /configure:workflows - コンテナのビルドを含む GitHub Actions
• /configure:skaffold - Kubernetes 開発の設定