DockerのENV・ARG・env_fileを正しく使う設計｜ビルド時と実行時の値の渡し方とsecrets

この記事のポイント

・ENVは実行時の変数、ARGはビルド時限定でイメージに残らない
・ARGにシークレットを渡すとdocker historyで漏洩する危険がある
・env_fileで.envを外部化し必ず.gitignoreに追加する
・BuildKit --mount=type=secretならレイヤーにシークレットが残らない

# Dockerfile
FROM node:20-slim

# 実行時も使われる変数
ENV PORT=3000
ENV NODE_ENV=production
ENV LOG_LEVEL=info

WORKDIR /app
COPY . .
RUN npm ci --omit=dev
CMD ["node", "server.js"]

# 実行時にLOG_LEVELをdebugに上書き
$ docker run -e LOG_LEVEL=debug myapp:latest

# 動作確認（コンテナ内の環境変数を確認）
$ docker exec  printenv LOG_LEVEL
debug

# Dockerfile
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-slim

ARG APP_VERSION=1.0.0
LABEL version=${APP_VERSION}

WORKDIR /app
COPY . .
RUN npm ci --omit=dev
CMD ["node", "server.js"]

# ビルド時にARGを渡す
$ docker build --build-arg NODE_VERSION=22 --build-arg APP_VERSION=2.1.0 -t myapp:2.1.0 .

# シークレット以外の値に限り有効なパターン
ARG APP_ENV=production
ENV NODE_ENV=${APP_ENV}

# .env（シークレットは書かない）
DB_HOST=db.internal
DB_PORT=5432
APP_TIMEZONE=Asia/Tokyo

# .gitignore
.env
.env.*
!.env.example

$ docker run --env-file .env myapp:latest

# 実際の出力例（環境変数が渡っていることを確認）
$ docker run --rm --env-file .env myapp:latest printenv DB_HOST
db.internal

# 危険な例（ARGでAPIキーを渡すと漏洩する）
ARG API_KEY
RUN curl -H "Authorization: Bearer ${API_KEY}" https://api.example.com/data

$ docker build --build-arg API_KEY=sk-xxxx -t myapp .

# historyでAPIキーが見えてしまう
$ docker history --no-trunc myapp | grep API_KEY
sha256:abc123...  /bin/sh -c #(nop)  ARG API_KEY=sk-xxxx

# Dockerfile（BuildKit secrets使用）
# syntax=docker/dockerfile:1
FROM ubuntu:24.04

RUN --mount=type=secret,id=api_key     API_KEY=$(cat /run/secrets/api_key) &&     curl -H "Authorization: Bearer ${API_KEY}" https://api.example.com/data -o /app/data.json

# ファイルからシークレットを渡す
$ echo "sk-xxxx" > api_key.txt
$ docker build --secret id=api_key,src=api_key.txt -t myapp .

# 環境変数から渡す（CI環境で便利）
$ docker build --secret id=api_key,env=API_KEY -t myapp .

# docker historyでシークレットは出てこない（漏洩しない）
$ docker history --no-trunc myapp | grep api_key
（出力なし）

# compose.yml
services:
  app:
    image: myapp:latest
    secrets:
      - db_password
    environment:
      DB_HOST: db.internal

secrets:
  db_password:
    file: ./secrets/db_password.txt

# compose.yml
services:
  app:
    image: myapp:latest
    environment:
      # 固定値や非秘密の設定
      NODE_ENV: production
      PORT: 3000
    env_file:
      # 環境依存の変数を外部ファイルで管理
      - .env

# .env.dev（開発環境用）
DB_HOST=localhost
LOG_LEVEL=debug

# .env.prod（本番環境用・CI/CDの秘密変数から生成）
DB_HOST=prod-db.internal
LOG_LEVEL=warn

# 開発環境で起動
$ docker compose --env-file .env.dev up

# 本番環境で起動
$ docker compose --env-file .env.prod up

# .gitignoreに追加（これ以降のコミットで無視される）
echo ".env" >> .gitignore

# git履歴から.envを削除（破壊的操作。チーム全員への周知が必要）
git filter-branch --force --index-filter   "git rm --cached --ignore-unmatch .env" HEAD

# シークレットを必ずローテーションすること（これが最重要）

# NG（=の前後にスペースがあるとパースエラー）
DB_HOST = localhost

# OK（スペースなし）
DB_HOST=localhost

# NG（クォートが不要）
DB_PASSWORD="mypassword"

# OK（クォートなし）
DB_PASSWORD=mypassword