モノレポのCI/CDは、単一リポジトリだから楽になる一方で、リリース設計を誤ると一気に難しくなります。

• 1つの変更で全サービスを再デプロイしてしまう
• 並列ジョブが増えてキュー渋滞する
• どのコミットがどのサービスへ反映されたか追跡できない
• 一部失敗時のロールバックが曖昧

本記事では、GitHub Actionsでモノレポを運用しているチーム向けに、実務で耐えるリリース自動化の構成を具体的に説明します。

1. モノレポCI/CDで先に決める設計原則

最初に次の原則を明文化します。

1. 変更のないサービスはデプロイしない
2. リリース対象は機械的に決定する
3. 本番反映は段階的（canary/割合配布）
4. 失敗時の復旧手順を自動化する
5. 監査ログ（誰が何をいつ）を残す

この5つがないと、運用が属人化し、障害時対応が遅れます。

2. 変更検知をワークフローの入口に置く

モノレポでは「どのディレクトリが変わったか」を最初に判定し、対象サービスだけを処理します。

2.1 changed-filesの例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: changed
        uses: tj-actions/changed-files@v45
        with:
          files_yaml: |
            api:
              - services/api/**
            web:
              - services/web/**
            worker:
              - services/worker/**
      - id: set-matrix
        run: |
          python .github/scripts/build_matrix.py '${{ toJson(steps.changed.outputs) }}'

ここでmatrixを作り、後続ジョブを fromJson で動的展開します。

3. reusable workflowで共通化する

各サービスごとにworkflowを複製すると、保守コストが急上昇します。workflow_call で共通化します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# .github/workflows/release-service.yml
on:
  workflow_call:
    inputs:
      service:
        required: true
        type: string
      environment:
        required: true
        type: string

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/release.sh ${{ inputs.service }} ${{ inputs.environment }}

呼び出し側はサービス名だけ渡せばよくなり、ガバナンスが効きます。

4. 同時実行制御（concurrency）で事故防止

同一サービスへの並列デプロイは事故のもとです。concurrency を必ず設定します。

1
2
3

concurrency:
  group: release-${{ github.ref }}-${{ matrix.service }}
  cancel-in-progress: false

cancel-in-progress は本番では通常 false が安全です。途中キャンセルで半端状態を作らないためです。

5. 環境ごとの保護ルールを使う

GitHub Environmentsを使えば、本番前レビューやシークレット分離を標準機能で実装できます。

• staging: 自動デプロイ
• production: 承認必須
• 緊急時のみ管理者がoverride

加えて、OIDCでクラウド認証し、長期鍵（固定アクセスキー）を排除します。

6. 段階リリース（Canary）を組み込む

本番へ一気に100%展開は避け、段階配布をワークフローに組み込みます。

例:

1. 10%トラフィックへ5分
2. エラーレート確認
3. 問題なければ50%
4. 最終的に100%

疑似コード例:

1
2
3
4
5
6
7
8
9

deploy --service api --traffic 10
sleep 300
check_slo api || rollback api

deploy --service api --traffic 50
sleep 300
check_slo api || rollback api

deploy --service api --traffic 100

check_slo はp95レイテンシ・5xx率・ビジネスKPIを含めるのが理想です。

7. 失敗復旧を「手順」ではなく「機能」にする

運用で強いチームは、ロールバックを手作業Runbookではなくワークフロー化しています。

7.1 rollback workflow例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

on:
  workflow_dispatch:
    inputs:
      service:
        required: true
      target_sha:
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/rollback.sh ${{ github.event.inputs.service }} ${{ github.event.inputs.target_sha }}

「事故時はこのボタンを押す」で復旧できる状態を目指してください。

8. リリース証跡の自動生成

監査対応やトラブル解析で必須になるのが証跡です。

最低限、以下をアーティファクト化します。

• 対象サービス一覧
• 対象コミットSHA
• 実行者
• 実行時刻
• 結果（成功/失敗）
• ロールバック有無

さらにSlack/Discord通知で、サービス単位の反映結果を即時共有すると現場が安定します。

9. コスト最適化も同時に行う

モノレポCIは規模が大きくなるほどコストが効いてきます。

• キャッシュ（依存/ビルド成果物）を徹底
• 変更のないサービスはskip
• 夜間バッチと競合しない時間帯に重いjobを寄せる
• 自己ホストランナーはautoscaling前提で運用

「全サービス毎回build」は最初は簡単ですが、半年後に必ず負債化します。

10. 導入チェックリスト

• 変更検知のmatrix生成がある
• reusable workflowに統一されている
• concurrency制御がサービス単位で設定済み
• production環境に承認ルールあり
• canary + 自動SLO判定がある
• rollback workflowが存在する
• リリース証跡を保存している
• 通知連携（Slack/Discord）が整備されている

まとめ

GitHub Actionsでのモノレポ自動リリースは、単にworkflowを書く作業ではありません。変更検知・段階配布・復旧自動化・監査 を含む運用設計です。

• デプロイ対象を最小化する
• 本番反映は必ず段階化する
• 失敗時の復旧を自動化する
• 証跡を残して再現性を確保する

この設計を最初に固めると、サービス数が増えても運用は破綻しません。まずは「変更検知 + reusable workflow + rollback workflow」の3点から着手するのが実装コストと効果のバランスが良いです。

付録: 失敗しにくい運用設計テンプレート

最後に、運用へ落とし込むときに有効なテンプレートを示します。実際にはこの3点をチーム標準にするだけで、リリース事故率が下がります。

• PRテンプレートに「影響サービス」欄を必須化
  • service-a, service-b のように宣言させ、変更検知結果と突合する
• デプロイ承認時の確認項目を固定化
  • 監視グラフURL、ロールバック手順URL、オンコール担当を毎回入力
• 失敗後レビューのフォーマット統一
  • 失敗原因、検知時刻、復旧時刻、再発防止策を必ず残す

特にモノレポでは「誰がどこに責任を持つか」が曖昧になりやすいです。workflowの技術実装だけでなく、承認と振り返りの運用ルールをセットにして初めて、自動リリースは安定運用に乗ります。

FastAPIの初期実装は非常に快適です。しかし運用フェーズに入ると、次のような症状が出てきます。

• 一覧APIのレスポンスが急に遅くなる
• 同時接続が増えるとp95が跳ねる
• CPUは余っているのにタイムアウトが増える
• DB接続数が上限に張り付く

こうした問題の多くは「Pythonが遅い」のではなく、SQLAlchemyの使い方とDBアクセス設計 に起因します。

本記事では、FastAPI + SQLAlchemy + PostgreSQL構成を前提に、実際の改善手順を計測ベースで整理します。

1. 最初に測るべき指標

最適化は、体感ではなく数値で進めます。最低限、以下を可視化します。

• APIのp50/p95/p99レイテンシ
• エンドポイント別SQL発行回数
• 1リクエストあたりのDB滞在時間
• connection pool待ち時間
• slow query件数（200ms以上など）

OpenTelemetryやNew Relicを使っているなら、アプリspanとDB spanを必ず紐付けてください。これだけでボトルネック特定速度が上がります。

2. N+1問題を最優先で潰す

最も頻出するのがN+1です。例えばユーザー一覧でプロフィールを参照すると、ユーザー数分の追加クエリが発行されます。

2.1 悪い例

1
2
3
4
5
6
7
8

users = session.query(User).limit(100).all()
result = []
for u in users:
    result.append({
        "id": u.id,
        "name": u.name,
        "profile": u.profile.bio,
    })

2.2 改善例（joinedload/selectinload）

1
2
3
4
5
6
7
8

from sqlalchemy.orm import selectinload

users = (
    session.query(User)
    .options(selectinload(User.profile))
    .limit(100)
    .all()
)

joinedload と selectinload はデータ量で使い分けます。

• 1対1/少量: joinedload
• 1対多/件数多め: selectinload

闇雲に joinedload を増やすと行爆発が起きるため、EXPLAINで確認しながら適用します。

3. SQLAlchemy 2.xスタイルへ揃える

旧query APIと新APIが混在すると可読性と最適化精度が落ちます。2.xスタイルへ統一しましょう。

1
2
3
4
5
6
7
8
9

from sqlalchemy import select

stmt = (
    select(Order)
    .where(Order.status == "paid")
    .order_by(Order.created_at.desc())
    .limit(50)
)
orders = session.execute(stmt).scalars().all()

この形式は、EXPLAIN の追跡や再利用がしやすく、レビュー品質も上がります。

4. 必要な列だけ取る（過剰フェッチの削減）

ORMは便利ですが、何も考えずモデル全体を取ると不要データまで転送されます。特にJSONカラムやTEXTが重い場合、ここが効きます。

1
2

stmt = select(User.id, User.name, User.email).where(User.active.is_(True))
rows = session.execute(stmt).all()

一覧APIはDTO用の軽量SELECTを使い、詳細APIでのみ重いカラムを取得する設計が安定します。

5. 接続プール設定を環境に合わせる

pool_size を適当に増やすだけでは逆効果です。PostgreSQL側上限とアプリ台数を合わせて設計します。

1
2
3
4
5
6
7
8

engine = create_engine(
    DB_URL,
    pool_size=20,
    max_overflow=10,
    pool_timeout=10,
    pool_recycle=1800,
    pool_pre_ping=True,
)

設計の目安:

• DB max_connections = 300
• API Pod = 6
• 1 Podあたりpool_size 20

この時点で理論最大120接続。バッチや管理接続も見込み、余白を残すのが安全です。

6. トランザクション境界を短くする

長いトランザクションはロック競合とスループット低下を招きます。

悪い例:

1. DB更新
2. 外部API呼び出し
3. メール送信
4. commit

この順は危険です。外部I/Oをトランザクション外へ逃がします。

改善例:

1. DB更新 + commit
2. 外部通知は非同期ジョブで実行

これだけで同時処理性能が目に見えて改善します。

7. インデックス設計をAPI単位で見直す

「インデックスはある」だけでは不足です。実際のWHERE + ORDER BYに合っているかが重要です。

例: 注文履歴API

1
2
3
4
5

SELECT id, total_amount, created_at
FROM orders
WHERE user_id = $1 AND status = 'paid'
ORDER BY created_at DESC
LIMIT 50;

この場合、次の複合indexが有効です。

1
2

CREATE INDEX CONCURRENTLY idx_orders_user_status_created_at_desc
ON orders (user_id, status, created_at DESC);

単独indexを乱立させるより、アクセスパターンに合わせた複合indexを厳選した方が効きます。

8. キャッシュ導入は「遅い理由の解決後」に行う

キャッシュは万能ではありません。N+1やスロークエリを放置したまま載せると、整合性事故の温床になります。

導入順序:

1. SQL最適化
2. 接続プール調整
3. 必要なエンドポイントに限定してRedis cache

キャッシュキーは resource:id:version 形式にし、更新時の無効化戦略を先に定義してください。

9. 負荷試験シナリオ（k6例）

最適化の成果は負荷試験で確認します。最低3シナリオが必要です。

• steady: 通常トラフィック
• burst: 短時間ピーク
• soak: 長時間連続実行（リーク検知）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '2m', target: 50 },
    { duration: '5m', target: 50 },
    { duration: '1m', target: 200 },
    { duration: '2m', target: 0 },
  ],
};

export default function () {
  const res = http.get('https://api.example.com/orders?limit=50');
  check(res, { 'status 200': (r) => r.status === 200 });
  sleep(1);
}

改善前後で p95, SQL回数, DB CPU を比較し、定量で判断します。

10. 本番での改善手順テンプレート

1. ボトルネックendpointの特定
2. SQLログとEXPLAIN ANALYZE取得
3. N+1解消
4. 必要列取得へ変更
5. インデックス追加（CONCURRENTLY）
6. pool設定調整
7. 負荷試験再実施
8. 段階リリース（10%→50%→100%）

この手順を運用チーム全体でテンプレ化すると、パフォーマンス問題への対応速度が上がります。

まとめ

FastAPI + SQLAlchemyの性能改善は、派手なテクニックより 計測→原因分離→小さく改善 の積み重ねが効きます。

• N+1解消
• 過剰フェッチ削減
• 接続プール最適化
• インデックスの再設計
• 負荷試験で再検証

この5点を回せば、遅いAPIは高確率で改善できます。まずは「1リクエストあたりのSQL発行数」を可視化するところから始めるのが最短です。

付録: 改善施策の優先順位（最短で効く順）

時間が限られる現場では、まず「SQL発行回数削減 → インデックス最適化 → connection pool調整」の順で着手すると効果が出やすいです。特に、N+1解消だけでp95が半減するケースは珍しくありません。改善後は必ず同一負荷条件で再計測し、数字で効果を残しておくと、次の改善投資判断が通りやすくなります。

Terraformのライセンス変更以降、OpenTofuへ移行したいという相談は確実に増えています。とはいえ現場の本音は「理屈は分かるが、stateが壊れたら終わる」「本番を止めずに移行できるのか不安」です。

結論から言うと、移行は十分可能です。ただし「CLIを置き換えるだけ」で済むケースは限定的で、実際は providerバージョン整合・state lock・CI/CD・運用Runbook までまとめて整える必要があります。

本記事では、既にTerraformを本番運用しているチーム向けに、OpenTofuへ段階移行する実践手順をまとめます。

1. 移行方針を先に決める

最初に決めるべきは「一気に切り替えるか」「ワークスペース単位で段階移行するか」です。実務では次の方針が安全です。

1. 低リスク環境（dev/sandbox）から先行
2. 本番は最終フェーズで移行
3. 旧TerraformとOpenTofuを一定期間並行運用
4. ロールバック手順を文書化してから実施

この順序を守るだけで、移行事故の大半を避けられます。

2. 互換性の棚卸し（最重要）

まずは現状のIaC資産を棚卸しします。

• Terraformバージョン（例: 1.5.x / 1.6.x）
• 使用provider（AWS/Azure/GCP/Kubernetes等）
• backend（S3 + DynamoDB lock、Terraform Cloud、GCSなど）
• moduleの参照方式（registry / git / local）
• CI実行環境（GitHub Actions, GitLab CI, Jenkins）

2.1 依存を固定化してから移行する

.terraform.lock.hcl を必ずコミットし、providerを固定します。移行時にproviderまで同時更新すると、差分原因の切り分けが困難になります。

1
2
3
4
5
6
7
8
9

terraform {
  required_version = ">= 1.6.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.40"
    }
  }
}

移行フェーズでは「ツール差分」と「provider差分」を分離してください。

3. ローカル検証の基本手順

OpenTofuを導入したら、既存プロジェクトで次を実行します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 現状確認
terraform version

# OpenTofu側確認
tofu version

# 初期化（既存backendを利用）
tofu init -upgrade=false

# 差分確認
 tofu plan -out=tfplan

plan が完全一致しない場合、いきなり適用してはいけません。主な原因は以下です。

• providerの暗黙更新
• data sourceの評価タイミング差
• 標準関数・型変換の微差
• module内部のversion制約

差分は「構文差分」より「実行時評価差分」で出ることが多い点に注意してください。

4. Stateを守る設計（壊したら復旧が重い）

IaC移行の本質的リスクはstateです。ここを守るために、以下を移行前チェックリストに組み込みます。

• state backendのバックアップ取得
• lock機構が有効か確認（DynamoDB等）
• apply 権限を移行担当者に限定
• 並列実行ジョブを停止（同時apply禁止）

4.1 S3 backendの例

1
2
3
4
5
6
7
8
9

terraform {
  backend "s3" {
    bucket         = "prod-iac-state"
    key            = "network/prod.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

OpenTofuでもこのbackend構成は継続利用できます。重要なのは「誰がいつlockするか」を運用で統制することです。

5. CI/CDをOpenTofu対応に置換

CLI切替はローカルだけでは不十分です。実運用ではCIがapply主体です。

5.1 GitHub Actions移行例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

name: iac-plan
on:
  pull_request:
    paths:
      - "infra/**"

jobs:
  plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.8.5
      - run: tofu init -input=false
      - run: tofu validate
      - run: tofu plan -input=false -no-color

ポイントは、tofu_version を固定し、突然のツール更新を防ぐことです。

5.2 Planの品質ゲート

• tofu fmt -check
• tofu validate
• tflint
• checkov や tfsec によるセキュリティ検査

この4点をPRゲート化すると、移行直後の品質低下を防げます。

6. 段階移行の実践フロー

本番で安全に移行するなら、次の順番が現実的です。

1. dev workspaceをOpenTofuに切替
2. 1週間運用し、差分・事故を記録
3. stg workspaceを切替
4. 本番はメンテウィンドウで切替
5. 切替後48時間は変更凍結（緊急以外apply禁止）

移行で一番危険なのは「切替当日に通常の機能変更を混ぜる」ことです。必ず分離してください。

7. よくある障害と対策

7.1 plan 差分が毎回揺れる

原因:

• data sourceに非決定的値（timestamp等）が混在
• providerバージョン不統一

対策:

• 変動値をlocalsに隔離
• provider lockを全環境で統一

7.2 import済み資源が再作成扱いになる

原因:

• module path変更
• resource address変更（count→for_each）

対策:

• moved ブロックを使い論理移動を明示
• 必要時のみ state mv を計画的に実施

7.3 lock解放漏れでapplyが詰まる

原因:

• CI異常終了
• 手動中断

対策:

• lock timeoutを定義
• 強制unlock手順をRunbook化
• Slack通知でlock継続を可視化

8. 運用Runbookに必ず入れる項目

• OpenTofuバージョン更新手順
• backend障害時の復旧手順
• lock競合時の対応フロー
• 監査ログ（誰がいつapplyしたか）
• ロールバック条件（差分件数・重大リスク判定）

「ツール移行成功」は、CLIが動くことではなく、運用が回ることです。

9. 具体的な移行チェックリスト

• .terraform.lock.hcl を全リポジトリで固定
• OpenTofu版CIテンプレート作成
• dev/stg/prodの順に移行計画作成
• stateバックアップの自動化
• lock競合監視の通知導入
• apply実行権限を限定
• 切替後の変更凍結ルールを明文化

まとめ

TerraformからOpenTofuへの移行は、単純なCLI置換ではなく IaC運用基盤の再整備 です。

• 差分原因を分離して検証する
• state保護を最優先に設計する
• CIとRunbookをセットで更新する
• 段階移行でリスクを局所化する

この4点を守れば、既存システムを止めずに移行できます。まずはdev環境で「同一plan再現性」を検証し、そこから本番へ広げるのが最短かつ安全です。

付録: 切替当日の実行チェック（時系列）

移行当日は、作業手順よりも「順番管理」が事故防止に効きます。以下は実務で使える時系列テンプレートです。

• T-30分: 変更凍結を全チームへ告知、未マージPRを棚卸し
• T-20分: tofu version と lockfile整合性確認、CI変数最終確認
• T-10分: backend到達確認、stateバックアップ取得
• T+0分: dev→stg→prodの順で tofu plan 実行（差分をレビュー）
• T+15分: 許容差分のみ tofu apply 実行、結果を監査ログへ転記
• T+30分: 主要監視（APIエラー率、レイテンシ、コスト）を15分監視

さらに、切替時に最も有効なのは「中止判断ライン」を先に決めることです。例えば、plan差分件数が想定の2倍以上 や apply失敗が2連続 の場合は即時中断し、旧フローへ戻す、といった基準を明文化しておくと現場判断がぶれません。

Kubernetes運用で一番つらい事故は、クラスタが壊れるよりも「本来防げたはずのミスがそのまま本番へ入る」ことです。たとえば、latest タグのイメージが本番に入り再現不能になる、resources 未設定でノードが詰まる、privileged コンテナが混入する。これらは人の注意力だけに依存すると必ず再発します。

そこで有効なのが Admission Policy（入場制御）です。本記事では Kyverno を使って、現場で本当に運用できるポリシー群を段階導入する手順をまとめます。単なる「denyの例」ではなく、監査→警告→強制の移行、例外管理、CI連携まで含めて解説します。

1. なぜKyvernoなのか

OPA Gatekeeper も強力ですが、Kyvernoは以下の特徴があり、初期導入が比較的スムーズです。

• YAML中心で書ける（Rego学習コストを後回しにしやすい）
• validate / mutate / generate / verifyImages を一貫して扱える
• PolicyReportにより違反可視化がしやすい
• Pod SecurityやSupply Chain対策との相性が良い

「まずルールを回し始める」目的なら、Kyvernoは現実的な選択肢です。

2. 先に決めるべき設計原則

導入前に、以下だけは先に決めておきます。

1. 導入フェーズ: Audit → Enforce を基本にする
2. 責任分界: プラットフォームチームが共通ポリシー、各チームがアプリ固有例外
3. 例外の期限: 永久例外は禁止。期限付きで必ず棚卸し
4. 観測性: 違反数・対象Namespace・上位違反ルールをダッシュボード化

この原則なしにルールだけ増やすと、運用が破綻します。

3. 最小導入手順（30〜60分）

3.1 Kyvernoのインストール

1
2
3
4
5
6
7
8
9

helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update

helm upgrade --install kyverno kyverno/kyverno \
  -n kyverno --create-namespace \
  --set admissionController.replicas=2 \
  --set backgroundController.replicas=2 \
  --set cleanupController.replicas=1 \
  --set reportsController.replicas=1

本番では可用性のため、admission/backgroundは最低2レプリカ推奨です。

3.2 まずはAuditモードで3ルール

最初に効くルールは、次の3つです。

• イメージタグに latest を禁止
• CPU/Memory requests/limits必須
• privileged: true を禁止

例: latest タグ禁止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-latest-tag
spec:
  validationFailureAction: Audit
  background: true
  rules:
    - name: validate-image-tag
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "latestタグは禁止です。固定タグまたはdigestを使用してください。"
        foreach:
          - list: "request.object.spec.containers"
            deny:
              conditions:
                any:
                  - key: "{{ element.image }}"
                    operator: Matches
                    value: ".*:latest$"

3.3 レポートで現状把握

1
2
3

kubectl get policyreport -A
kubectl get clusterpolicy
kubectl describe clusterpolicy disallow-latest-tag

導入直後は違反が大量に出るのが普通です。ここで「Kyvernoが厳しすぎる」と判断しないでください。違反は“見えていなかった負債”です。

4. 実務で効くルールセット（具体例）

4.1 リソース未設定防止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-resources
spec:
  validationFailureAction: Audit
  rules:
    - name: check-resources
      match:
        any:
          - resources:
              kinds: ["Pod"]
      validate:
        message: "全コンテナにrequests/limitsを設定してください。"
        pattern:
          spec:
            containers:
              - resources:
                  requests:
                    cpu: "?*"
                    memory: "?*"
                  limits:
                    cpu: "?*"
                    memory: "?*"

4.2 特権設定防止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-privileged
spec:
  validationFailureAction: Enforce
  rules:
    - name: no-privileged
      match:
        any:
          - resources:
              kinds: ["Pod"]
      validate:
        message: "privilegedコンテナは禁止です。"
        pattern:
          spec:
            containers:
              - securityContext:
                  =(privileged): "false"

4.3 Digest固定の推奨（Supply Chain）

本来は digest 固定が理想です。移行期は Audit で始め、違反率が下がってから Enforce に切り替えます。

5. AuditからEnforceへ移行する基準

「何となく」で切り替えると炎上します。次の客観指標を使うと安全です。

• 直近14日で対象ポリシー違反率が5%未満
• 主要Namespace（prod/stg/shared）で違反ゼロ
• 例外申請フロー（Issue/PRテンプレート）が整備済み
• 当番がトラブル時に切り戻し手順を理解している

validationFailureAction を一括で上げるのではなく、ルール単位・Namespace単位で段階化するのがポイントです。

6. 例外運用のテンプレート

ポリシー導入で最も壊れるのは「例外管理」です。おすすめは以下。

• 例外は PolicyException で明示
• 期限（例: 14日）を必須にする
• チケット番号をannotationで必須化
• 期限切れを毎日バッチで通知

例外YAMLに expires と owner を必須化すると、放置率が一気に下がります。

7. CIに組み込んで“本番前に落とす”

クラスタ投入時に拒否されるより、PR段階で検知される方が開発体験は良いです。kyverno-cli をCIで実行します。

1

kyverno apply policies/ -r manifests/ --audit-warn

GitHub Actions例:

1
2
3
4

- name: Validate manifests with Kyverno
  run: |
    kyverno version
    kyverno apply ./policies -r ./k8s --audit-warn

これで「マージ後に初めて失敗する」パターンを減らせます。

8. よくある障害と対処

症状1: 正常なPodまで拒否される

• match条件が広すぎる可能性
• exclude で kube-system や監視系を一時除外
• まずAuditで影響範囲を確認してからEnforceへ

症状2: Admission timeoutでデプロイ遅延

• Kyvernoコンポーネントのリソース不足を確認
• policy数が多い場合、ルール統合とmatch最適化
• API Serverとのネットワーク遅延確認

症状3: レポートは出るが改善が進まない

• 違反上位3ルールに絞ってKPI化
• チーム別に違反件数を見える化
• 例外を期限付きに強制

9. 運用を続けるためのダッシュボード指標

最低限、以下を可視化してください。

• ルール別違反件数（7日移動平均）
• Namespace別違反件数
• Audit と Enforce の比率
• 期限切れ例外の件数
• deploy失敗要因のうちpolicy起因の割合

これを見ないと、ポリシーは「導入しただけ」で止まります。

10. 実践ロードマップ（最初の4週間）

• Week 1: Kyverno導入、3ルールをAuditで開始
• Week 2: 違反上位を改善、例外テンプレート導入
• Week 3: 一部NamespaceでEnforce化
• Week 4: CI連携完了、SLOに違反率を組み込み

4週間で「人頼みのレビュー文化」から「仕組みで防ぐ文化」へ移行できます。

まとめ

Kyverno導入の本質は、Kubernetesを縛ることではなく、再発するミスを設計で減らすことです。

• 最初はAuditで可視化
• 指標を持って段階的にEnforce
• 例外は期限付きで管理
• CIに前倒し検知を組み込む

この4点を守れば、ポリシーは“開発を止める壁”ではなく“事故を減らすガードレール”になります。まずは latest 禁止とリソース必須の2ルールから始めて、違反データを見ながら育てていきましょう。

FastAPIでAPIを作ると、重い処理はすぐに非同期ジョブへ逃がしたくなります。画像変換、レポート生成、外部API連携、メール配信など、Celeryは非常に便利です。ですが、本番で問題になるのは「動くかどうか」ではなく、失敗したときに壊れないか です。

• 同じジョブが二重実行される
• 一時障害で永遠にリトライしてキューが詰まる
• ワーカー再起動で中途半端な状態が残る
• 完了通知が先に飛んで実データがない

本記事では FastAPI + Celery + Redis 構成を前提に、再実行安全性（idempotency）と運用信頼性を上げる実装手順をまとめます。

1. まず守るべき設計原則

非同期基盤の事故は、ほぼ次の4原則で防げます。

1. At-least-once前提（同一タスク再実行は必ず起こる）
2. 副作用は冪等化（何回実行されても結果が壊れない）
3. 状態遷移を明示（PENDING/RUNNING/SUCCEEDED/FAILED）
4. 失敗を可観測化（リトライ回数・死活・滞留時間を計測）

この原則を外すと、障害時に「何が完了して何が未完了か」が追えなくなります。

2. 参照アーキテクチャ

• API: FastAPI
• Queue Broker: Redis
• Worker: Celery
• Result Store: PostgreSQL（業務状態）
• Monitoring: Flower + Prometheus + Sentry

ポイントは、業務上重要な状態はRedis結果バックエンドに依存しない ことです。Redisは一時的に使い、真実の状態はRDBに持たせます。

3. 実装の土台: タスク受付API

3.1 受け付け時に idempotency_key を必須化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from sqlalchemy import select

app = FastAPI()

class JobRequest(BaseModel):
    idempotency_key: str
    report_type: str
    user_id: str

@app.post("/reports")
def create_report(req: JobRequest):
    existing = find_job_by_key(req.idempotency_key)
    if existing:
        return {"job_id": existing.id, "status": existing.status}

    job = create_job_record(
        idempotency_key=req.idempotency_key,
        status="PENDING",
        report_type=req.report_type,
        user_id=req.user_id,
    )
    generate_report.delay(job.id)
    return {"job_id": job.id, "status": "PENDING"}

これでクライアント再送が来てもジョブ多重作成を防げます。

3.2 DB制約で最終防衛線を張る

idempotency_key に UNIQUE 制約を入れ、アプリバグ時も二重作成を防ぎます。

1

ALTER TABLE async_jobs ADD CONSTRAINT uq_async_jobs_idempotency UNIQUE (idempotency_key);

4. Celeryタスクの実践設定

4.1 推奨設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

from celery import Celery

celery_app = Celery(
    "worker",
    broker="redis://redis:6379/0",
    backend="redis://redis:6379/1",
)

celery_app.conf.update(
    task_acks_late=True,
    task_reject_on_worker_lost=True,
    worker_prefetch_multiplier=1,
    task_time_limit=900,
    task_soft_time_limit=840,
    task_default_retry_delay=30,
    task_routes={"tasks.generate_report": {"queue": "reports"}},
)

• acks_late=True: 実行完了後にACK。途中クラッシュ時は再配信
• prefetch_multiplier=1: 取り込み過多を防ぎ、偏りを減らす
• time limit: ハング抑止

4.2 リトライは指数バックオフ + 上限

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@celery_app.task(
    bind=True,
    autoretry_for=(TemporaryExternalError,),
    retry_backoff=True,
    retry_backoff_max=300,
    retry_jitter=True,
    max_retries=7,
)
def generate_report(self, job_id: str):
    ...

無制限リトライは障害増幅装置です。必ず上限を設定します。

5. 冪等タスクの実装パターン

5.1 状態遷移をトランザクションで管理

1
2
3
4
5
6
7
8

def start_job(job_id: str):
    with session.begin():
        job = session.get(Job, job_id, with_for_update=True)
        if job.status in ("RUNNING", "SUCCEEDED"):
            return False
        job.status = "RUNNING"
        job.started_at = utcnow()
    return True

FOR UPDATE を使い、同時実行で状態が競合しないようにします。

5.2 副作用前に“実行済みチェック”

外部API呼び出しやファイル生成前に、既に成果物が存在するか確認します。

• 既に同名レポートが生成済みならスキップ
• 外部通知は送信履歴テーブルで重複防止
• 決済や課金は必ず業務ID単位で一意化

5.3 完了処理はCompare-and-Setで確定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

def complete_job(job_id: str, result_url: str):
    updated = session.execute(
        """
        UPDATE async_jobs
        SET status='SUCCEEDED', result_url=:url, finished_at=now()
        WHERE id=:id AND status='RUNNING'
        """,
        {"id": job_id, "url": result_url},
    )
    return updated.rowcount == 1

これで二重完了更新を防げます。

6. 失敗時の設計（DLQ相当の運用）

Celeryに“標準DLQ”はありませんが、実運用では次の形で代替できます。

• リトライ上限超過時に FAILED_PERMANENT へ遷移
• 失敗理由とスタックトレースをDB保存
• 再実行API（手動リカバリ）を提供
• 重大失敗はSentry + Pagerで通知

この構成で「黙って死ぬジョブ」をなくせます。

7. 監視設計（最低限）

メトリクス

• キュー滞留数（queue length）
• oldest message age
• タスク成功率 / 失敗率
• p95 実行時間
• リトライ回数分布

アラート例

• 滞留数が通常の3倍を10分継続
• 失敗率 > 5% が15分継続
• oldest message age > 20分
• worker heartbeat消失

「CPU高い」より「キューが古い」がユーザー影響に直結します。

8. デプロイ時の落とし穴

8.1 ローリング更新での重複実行

• acks_late + graceful shutdown を設定
• TERM 後にタスク完了待ち時間を確保
• 長時間ジョブは分割し、中断耐性を持たせる

8.2 スキーマ変更の順序

非同期基盤では、ワーカーとAPIが異なるバージョンで同居します。

安全な順序:

1. 先に後方互換なDB変更を適用
2. ワーカーを先に更新
3. APIを更新
4. 非互換削除は次リリースで

これを守らないと、古いタスクが新スキーマで失敗します。

9. ローカル・ステージングでの検証手順

1. 正常系: ジョブ作成→完了→結果取得
2. 再送系: 同一 idempotency_key で2回POST
3. 障害系: 外部APIタイムアウトを強制しリトライ確認
4. クラッシュ系: 実行中にworker再起動し再配信確認
5. 負荷系: 1000ジョブ投入で滞留時間と失敗率確認

この5ケースを自動テストに入れるだけで、運用品質は大幅に上がります。

10. 本番チェックリスト

• idempotency_key のUNIQUE制約あり
• 冪等な状態遷移実装（RUNNING/SUCCEEDED）
• リトライ上限 + バックオフ設定済み
• 手動再実行導線あり
• 失敗通知（Sentry/Pager）有効
• 滞留監視とアラート運用あり
• デプロイ手順に互換性ルール明記

まとめ

FastAPI + Celeryの本質は、非同期化そのものではなく 失敗しても壊れない設計 にあります。

• At-least-once を前提に設計する
• 冪等性をDB制約と状態遷移で担保する
• リトライと監視を“運用可能”な形で実装する
• デプロイ時のバージョン混在を想定する

ここまで作り込むと、ジョブ基盤は「たまに落ちるブラックボックス」から「予測可能に運用できるインフラ」へ変わります。まずは idempotency_key と状態遷移の明確化から始めるのがおすすめです。

PostgreSQL運用で最も危険なのは「バックアップがある」という安心感です。実際の障害では、バックアップ自体より 復旧手順の不整合 で時間を失います。たとえば、WAL保管期間が足りず目標時刻に戻せない、暗号鍵が見つからず復号できない、復旧後の整合性確認が曖昧で再開判断ができない、といった問題です。

本記事では、PostgreSQLの Point-in-Time Recovery（PITR）を、机上ではなく本番レベルで回すための実装手順を解説します。pgBackRest を例にしていますが、考え方は他ツールでも共通です。

1. PITRの前提: 3つ揃わないと復旧できない

PITRは次の3要素で成立します。

1. ベースバックアップ（フルまたは差分）
2. WALアーカイブ（継続的）
3. 目標時刻情報（いつまで戻すか）

どれか1つでも欠けると成立しません。特に本番で多いのは「WALが途中で消えていた」ケースです。S3保存していても、ライフサイクル設定や権限変更で欠落することがあります。

2. まず決めるべきRTO/RPO

技術論の前に、業務要件を決めます。

• RTO（復旧に許容される時間）: 例 60分
• RPO（失ってよいデータ時間）: 例 5分

この2つで設計が変わります。

• RPO 5分以内ならWALアーカイブ遅延監視が必須
• RTO 60分以内なら復旧訓練を定期実施し、手順を自動化する必要あり

要件不明のまま「毎日バックアップ」だけ実施しても、障害時に役立たないことが多いです。

3. 推奨アーキテクチャ（単一リージョンの最小構成）

• DBサーバ: PostgreSQL 15/16
• バックアップツール: pgBackRest
• 保存先: S3互換ストレージ（バージョニングON）
• 監視: Prometheus + Alertmanager
• 復旧先: 別ホスト（本番と同一ネットワーク）

重要なのは、本番DBと別ホストで実際に復旧できること を定期検証する点です。

4. 実装手順（pgBackRest）

4.1 PostgreSQL設定

postgresql.conf 例:

wal_level = replica
archive_mode = on
archive_command = 'pgbackrest --stanza=main archive-push %p'
max_wal_senders = 10
wal_compression = on

archive_command は失敗時に非0を返す必要があります。ここが曖昧だとWAL欠落に気づけません。

4.2 pgBackRest設定

/etc/pgbackrest/pgbackrest.conf 例:

[global]
repo1-type=s3
repo1-path=/pgbackrest
repo1-s3-bucket=prod-db-backup
repo1-s3-endpoint=s3.ap-northeast-1.amazonaws.com
repo1-s3-region=ap-northeast-1
repo1-retention-full=14
start-fast=y
process-max=4
compress-type=zst

[main]
pg1-path=/var/lib/postgresql/16/main

初期化:

1
2

pgbackrest --stanza=main stanza-create
pgbackrest --stanza=main --type=full backup

4.3 WAL到達の監視

• pg_stat_archiver の failed_count
• 最終成功時刻と現在時刻の差分
• repoの最新WALタイムスタンプ

例: 10分以上WALが更新されない場合にCriticalアラート。

5. 復旧訓練（Drill）を標準化する

運用で差が出るのはここです。訓練の目的は「復旧できること」ではなく、予測可能な時間で安全に復旧できること です。

5.1 月次ドリル手順（テンプレート）

1. 目標時刻を決める（例: 当日 08:35:00 JST）
2. 復旧専用ホストを初期化
3. バックアップ + WALからリストア
4. DB起動後、整合性チェックを実行
5. アプリのスモークテストを実行
6. RTO実測値と課題を記録

5.2 実コマンド例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 復旧先でデータディレクトリを準備
systemctl stop postgresql
rm -rf /var/lib/postgresql/16/main/*

# 指定時刻までリストア
pgbackrest --stanza=main \
  --type=time \
  --target="2026-03-06 08:35:00+09" \
  --delta \
  restore

# 起動
systemctl start postgresql

PostgreSQL 12+では recovery.conf ではなく postgresql.auto.conf + standby.signal 形式に変わっている点に注意してください。

6. 復旧後の整合性チェック項目

「起動したからOK」は危険です。最低限、次を確認します。

• 主要テーブル件数（基準値との差分）
• 直近トランザクション時刻
• 重要集計値（売上、注文、在庫など）
• アプリの read/write スモークテスト
• レプリカ再構築可否

SQL例:

1
2
3

SELECT now();
SELECT max(created_at) FROM orders;
SELECT count(*) FROM users;

件数だけでなく「業務上重要な指標」を入れるのが実務的です。

7. 失敗しがちなポイントと対策

7.1 WAL保持期間が短すぎる

• 対策: RPO/RTOに基づき、最低でも7〜14日保持
• 削除はバックアップ整合性確認後に実行

7.2 暗号鍵・認証情報の保管ミス

• 対策: KMS/Secret Managerに分離保管
• 緊急時アクセス手順をRunbook化

7.3 手順が個人依存

• 対策: RunbookをGit管理
• ドリル時に“当番以外”が実行して再現性を検証

7.4 復旧はできるが遅すぎる

• 対策: 差分バックアップ頻度見直し
• 復旧先マシンスペックの最低保証
• リストア並列度（process-max）調整

8. 自動化の実装例（CIでドリルを回す）

本番同等データを使えない場合は、匿名化済みスナップショットで定期検証します。

• 毎週日曜 03:00 に復旧ジョブ起動
• 復旧後にSQLチェック + APIスモーク
• 結果をSlack/Discordへ通知
• 失敗時は翌営業日のSRE定例でレビュー

この「半自動ドリル」を導入すると、障害時の初動が劇的に安定します。

9. 監査対応のための証跡

監査や顧客説明で必要になるのは、次の証跡です。

• バックアップ成功ログ（日次）
• WAL連続性の証跡
• 復旧ドリルの実行記録（日時、担当、RTO実測）
• 改善アクション履歴

「やっています」ではなく「この月にこの結果でした」と示せる状態を作っておきましょう。

10. 現場向けチェックリスト

• フルバックアップ成功率 99%以上
• WAL遅延アラートが有効
• 目標時刻指定の復旧手順がRunbook化
• 月次ドリル実施済み
• 復旧後整合性チェックSQLが整備済み
• KMS/鍵管理手順が文書化済み

このチェックリストを満たして初めて「PITR対応」と言えます。

まとめ

PITRは設定項目の話ではなく、復旧可能性を継続的に検証する運用 です。

• RTO/RPOを先に決める
• バックアップ + WAL + 監視をセットで設計する
• 月次ドリルで実測し、Runbookを改善する
• 復旧後整合性チェックまで標準化する

バックアップがあることはゴールではありません。障害時に「何分で、どこまで戻せるか」を言える状態こそが、プロダクション品質です。

付録: 実運用で使えるPITRドリル手順（90分版）

以下は、現場でそのまま回せる最小ドリル手順です。月次で固定化すると、障害対応の心理的負荷を下げられます。

1. 開始宣言（5分）
   • 担当者、開始時刻、目標RTO/RPOをチケットに記録
2. 復旧環境準備（15分）
   • 復旧先PostgreSQLを起動
   • バックアップ世代と目標復旧時刻（例: 10:32:00 JST）を確定
3. リストア実行（25分）
   • pg_restore もしくはベースバックアップ展開
   • WAL適用完了ログを保存
4. 整合性検証（20分）
   • 件数チェックSQL、外部キー整合性、直近注文IDの連続性を確認
   • APIスモーク（ログイン/一覧/作成）を実施
5. 振り返り（25分）
   • 実測RTO/RPOを記録
   • 失敗ポイントをRunbookに即反映

重要なのは「成功したか」だけではなく、どこで何分消費したかを毎回残すことです。これを3回続けるだけで、復旧手順のボトルネックがかなり明確になります。

「カラムを追加するだけだから大丈夫」──この油断が、本番障害の入口になります。Kubernetes のように複数バージョンの Pod が同時に存在する環境では、DB スキーマ変更はアプリ変更よりも慎重に扱う必要があります。

本記事では、Expand-Contract パターンを中心に、ゼロダウンタイムを目指すための具体手順を解説します。実際の運用では、DDLの速さより「互換性のある期間をどう作るか」が勝負です。

1. なぜKubernetesでDB移行が難しいのか

Kubernetesでは、ローリングアップデート中に新旧Podが混在します。つまり次の状態が同時に発生します。

• 新アプリは新スキーマを期待
• 旧アプリは旧スキーマしか知らない
• DBは1つしかない

このとき破綻するのが「破壊的変更を先に適用する」ケースです。たとえば旧カラムを即削除すると、旧Podがエラーを連発します。

2. 基本戦略：Expand → Migrate → Contract

ゼロダウンタイム移行の原則はこの3段階です。

1. Expand: 互換性を壊さない変更を先に入れる（新カラム追加など）
2. Migrate: アプリを段階的に切替え、データを移行する
3. Contract: 旧仕様を最終削除する（十分な監視後）

この順序なら、どの時点でも旧新どちらのアプリも動作可能にできます。

3. 具体例：users.full_name を first_name / last_name へ分割

3.1 Expand フェーズ

まず破壊的でないDDLを適用します。

1
2

ALTER TABLE users ADD COLUMN first_name text;
ALTER TABLE users ADD COLUMN last_name text;

この時点で旧アプリは full_name を使い続けられます。新アプリは新カラムに対応した実装を持っていても、まだ必須にしません。

3.2 アプリを「両対応」にする

書き込み時は両方へ保存（dual write）し、読み込み時は新カラム優先 + 旧カラムフォールバックにします。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

def save_user_name(user_id: str, full_name: str):
    first, last = split_name(full_name)
    db.execute(
        """
        UPDATE users
        SET full_name = %s,
            first_name = %s,
            last_name = %s
        WHERE id = %s
        """,
        (full_name, first, last, user_id),
    )


def read_user_display_name(row):
    if row.first_name and row.last_name:
        return f"{row.first_name} {row.last_name}"
    return row.full_name

この両対応期間を作るのが、ゼロダウンタイムの本質です。

3.3 バックフィル（既存データ移行）

大規模テーブルでは一括更新を避け、チャンク更新します。

1
2
3
4
5
6
7

-- 疑似コードイメージ
UPDATE users
SET first_name = split_part(full_name, ' ', 1),
    last_name = split_part(full_name, ' ', 2)
WHERE id > :last_id
  AND id <= :last_id + 10000
  AND (first_name IS NULL OR last_name IS NULL);

ジョブ実装時のポイント:

• 1チャンクごとに commit
• 再開可能なチェックポイント（last_id）を保存
• 実行時間帯を制御（ピーク時間回避）

3.4 Contract フェーズ

全Podが新実装になり、フォールバックが不要と判断できたら旧カラム削除へ進みます。

1

ALTER TABLE users DROP COLUMN full_name;

削除は必ず最後です。ここを急ぐとロールバック不能になります。

4. マイグレーション実行方式の選び方

Kubernetesでは主に3パターンがあります。

A. CI/CDで先行実行（推奨）

デプロイ前に migration Job を走らせ、成功後にアプリを更新。

• メリット: 実行順序を固定しやすい
• デメリット: 長時間 migration の扱いが難しい

B. initContainer 実行

Pod起動時に migration を走らせる方式。

• メリット: 実装が単純
• デメリット: 複数Pod同時起動で競合しやすい

C. 専用 Migration Controller / Job

Argo Workflows などで明示的に管理。

• メリット: 大規模運用で監査しやすい
• デメリット: 初期構築コストが高い

中規模までなら A が最も事故が少ないです。

5. Alembic/Flyway運用の実務ポイント

5.1 1 migration = 1責務

「追加 + データ移行 + 削除」を1ファイルに詰め込むと失敗時に戻しづらくなります。Expand/Migrate/Contract を別 migration に分けて、各段階を検証可能にしてください。

5.2 lock timeout を設定する

DDL はロック待ちでアプリを止めることがあります。PostgreSQL なら lock_timeout を設定して、危険な待機を避けます。

1
2

SET lock_timeout = '5s';
ALTER TABLE ...;

失敗時は即中断し、メンテナンス時間帯に再実行する判断が可能です。

5.3 破壊的変更前に計測窓を設ける

旧カラム参照がゼロになったことを、メトリクスやログで一定期間確認してから削除します。目安として 7〜14日程度の観測期間を取ると安全です。

6. ロールバック戦略

ゼロダウンタイム設計では、ロールバック可能性を最初に決めます。

• Expand段階: ほぼ即ロールバック可能
• Migrate段階: dual write を維持していればロールバック可能
• Contract段階: 削除後は復元コスト高（バックアップ依存）

したがって、Contract 実施前に以下を満たす必要があります。

• 直近スナップショット取得済み
• 復元手順を演習済み
• 影響範囲（API・バッチ・BI）を棚卸し済み

7. 監視項目と成功判定

移行中は「成功したか」より「安全に進んでいるか」を見ます。

• APIエラー率（4xx/5xx）
• DBロック待ち時間
• スロークエリ件数
• migration ジョブ進捗（処理済み件数、残件数）
• 旧カラム参照回数

成功判定の例:

1. 新旧Pod混在中のエラー率に有意な悪化なし
2. バックフィル完了率100%
3. 旧カラム参照0が連続7日
4. Contract後24時間で異常なし

8. よくある失敗と回避策

失敗1: 非NULL制約を早く付けすぎる

バックフィル完了前に NOT NULL を付けると、旧データで失敗します。まずは nullable で追加し、データ移行後に制約追加が正解です。

失敗2: インデックス作成で書き込み停止

大きいテーブルで通常インデックス作成を行うとロックが重くなります。PostgreSQL では CREATE INDEX CONCURRENTLY を使って影響を下げます。

失敗3: migration の実行主体が複数

同時に2つのJobが走ると競合します。Kubernetes Job は排他制御（Lease/Lock）を持たせるか、CI側で単一実行を保証してください。

9. 実運用テンプレート：Migration Job と段階リリース

最後に、現場でそのまま使える最小テンプレートを示します。ポイントは「DDLを一気にやらない」「アプリ側フラグで読取切替を制御する」の2点です。

9.1 Migration Job（Expand専用）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

apiVersion: batch/v1
kind: Job
metadata:
  name: users-expand-20260305
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: ghcr.io/example/api:1.42.0
          command: ["bash", "-lc", "alembic upgrade 20260305_expand_users_name"]
          envFrom:
            - secretRef:
                name: api-db-secret

Expand 用 Job を分離しておけば、失敗時にアプリデプロイを止める判断が明確になります。backoffLimit: 0 にして「失敗を隠さない」運用にするのも実務で有効です。

9.2 段階リリース手順（例）

1. Expand Job 実行（DDLのみ）
2. アプリ v1（dual write + fallback read）を10%配信
3. エラー率・ロック待ちを30分監視
4. 50% → 100%へ段階拡大
5. バックフィル Job 実行
6. 旧参照ゼロ確認後に Contract 実施

Kubernetes では kubectl rollout status deployment/api -n prod を必ず監視に組み込み、配信完了判定を人間が明示的に確認する運用が安全です。

まとめ

KubernetesでのDBマイグレーションは、DDLテクニックだけでは成功しません。重要なのは、

• 互換性期間を意図的に作る
• 段階を分けて進める
• ロールバック可能性を先に設計する
• 監視で「削除してよい」根拠を取る

この4点です。Expand-Contract を守るだけで、移行の失敗率は目に見えて下がります。スキーマ変更は怖い作業ですが、手順化すれば再現可能な運用にできます。次回の変更から、ぜひこの流れで試してみてください。

本番障害でよくあるのが、too many clients already や remaining connection slots are reserved です。アプリ側から見ると「急にDBに繋がらない」、ユーザー側から見ると「全機能が遅い・失敗する」という最悪の体験になります。

厄介なのは、接続枯渇が「DBサーバー性能不足」だけで起こるわけではない点です。リーク、タイムアウト設定、長時間トランザクション、プールサイズ不整合など、複数要因が重なって起きます。

この記事では、接続枯渇に対して 発生時の初動 → 根本原因の特定 → 恒久対策 の順で、手順を実務レベルでまとめます。

1. まず初動：サービス継続を優先する

障害対応では、完璧な原因究明より「止血」が先です。以下を順番に実施します。

1. 直近リリース有無を確認（機能フラグ含む）
2. アプリの接続数・待機数・エラー率を確認
3. DB側で pg_stat_activity を取得
4. 長時間実行クエリを必要に応じて停止
5. 一時的にアプリ Pod 数を制限して雪だるま増幅を止める

pg_stat_activity の基本クエリ:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

SELECT
  pid,
  usename,
  application_name,
  client_addr,
  state,
  wait_event_type,
  wait_event,
  now() - query_start AS query_duration,
  now() - xact_start  AS xact_duration,
  left(query, 120) AS query_head
FROM pg_stat_activity
WHERE datname = current_database()
ORDER BY xact_start NULLS LAST, query_start NULLS LAST;

ここで見るべきは、state='idle in transaction' と異常に長い xact_duration です。これがあるとコネクションを握ったまま解放されず、枯渇の引き金になります。

2. 典型原因を4パターンで切り分ける

パターンA: アプリ接続プールサイズが過大

よくあるのが、以下のような構成です。

• Pod 20個
• 各Podのプール max 20
• 理論最大接続 400
• PostgreSQL max_connections=300

この時点で設計破綻です。さらに管理接続やメンテ接続を引くと余裕ゼロになります。

対策:

• プールサイズ設計は「全インスタンス合計」で管理
• max_connections の70〜80%以内に通常運用を収める
• ピーク時はワーカ数/Pod数で制御

パターンB: コネクションリーク

finally で close していない、ORMセッションの寿命が長い、例外時に返却されない、といった実装ミスです。

Python（SQLAlchemy）の悪い例:

1
2
3
4

session = SessionLocal()
user = session.query(User).filter(User.id == user_id).first()
# 例外時にcloseされない可能性
return user

改善例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from contextlib import contextmanager

@contextmanager
def get_session():
    session = SessionLocal()
    try:
        yield session
        session.commit()
    except Exception:
        session.rollback()
        raise
    finally:
        session.close()

FastAPI なら dependency でセッションスコープを統一し、endpointごとに確実に返却させるのが安全です。

パターンC: 長時間トランザクション

バッチ処理で 1トランザクションに大量更新を詰め込むと、ロック競合と接続占有が同時発生します。

対策:

• バッチをチャンク分割（例: 500件単位）
• statement_timeout、idle_in_transaction_session_timeout を設定
• 長時間処理はキュー化して非同期実行

パターンD: プールとDBのタイムアウト不一致

アプリの接続再利用時間が長すぎると、DB側で切断済み接続を使って失敗し、リトライで更に接続圧を上げます。

対策:

• プールの maxLifetime を DB/NLB timeout より短く
• 接続取得待ち時間（acquire timeout）を短くし、早めに失敗させる
• 失敗時リトライは指数バックオフ + ジッター

3. 具体的な設定例（PgBouncer + PostgreSQL）

高トラフィック環境では、アプリ直結より PgBouncer を挟むのが安定します。

pgbouncer.ini の例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
pool_mode = transaction
max_client_conn = 5000
default_pool_size = 80
reserve_pool_size = 20
server_reset_query = DISCARD ALL
server_idle_timeout = 30

PostgreSQL 側の最小設定例:

max_connections = 300
shared_buffers = 4GB
idle_in_transaction_session_timeout = 60000
statement_timeout = 30000
log_min_duration_statement = 1000

pool_mode=transaction は接続効率が高い一方、セッション依存機能（一時テーブルや session variable）の扱いに注意が必要です。導入前に該当クエリを洗い出してください。

4. Kubernetes運用での落とし穴

Kubernetes では、HPA がスケールアウトすると同時に接続数が急増しやすいです。

4.1 設計式を最初に決める

最大接続見積もり = maxPods × perPodPoolMax + 管理余白

例:

• maxPods=30
• perPodPoolMax=8
• 管理余白=30
• 合計 270 → max_connections=320 なら許容

この計算を IaC へコメントで残しておくと、後任が壊しにくくなります。

4.2 readiness に DB接続必須チェックを入れすぎない

Pod起動時に全Podが同時にDBへ接続テストすると、再起動時にスパイクが起きます。readiness は軽量化し、重い初期化はバックグラウンドへ逃がすのが無難です。

5. 監視項目：再発防止の最低ライン

以下を可視化し、閾値アラートを設定します。

• numbackends / max_connections
• 接続待ち時間（アプリメトリクス）
• idle in transaction セッション数
• 95/99パーセンタイルのクエリ時間
• DBエラー率（connection refused, timeout）

推奨アラート例:

• numbackends > 85% が 5分継続で Warning
• numbackends > 92% が 2分継続で Critical
• idle in transaction > 10 が 3分継続で調査開始

6. 障害後レビュー（ポストモーテム）で必ず決めること

「接続が足りませんでした」で終えると再発します。次の観点を明文化します。

1. なぜ早期検知できなかったか
2. どの設定が設計値と乖離していたか
3. コード修正・設定修正・監視修正の担当と期限
4. 次回同様インシデント時の runbook 更新点

運用改善は「学びをコード化する」ことです。ドキュメントだけでなく、Terraform や Helm values に反映して初めて再発率が下がります。

7. 実務向けチェックリスト

最後に、現場で使いやすいチェックリストを置いておきます。

• max_connections と総プール上限の関係を計算済み
• 接続リーク防止（close/return保証）が実装されている
• 長時間トランザクションに timeout が設定済み
• PgBouncer の pool_mode が要件に適合している
• numbackends と接続待ち時間のアラートがある
• 障害時 runbook に SQL コマンドと判断基準が書かれている

まとめ

PostgreSQL 接続枯渇は、単なるパラメータ不足ではなく、アプリ実装・スケーリング設計・監視不足が重なって起こる複合障害です。だからこそ、

• 初動で止血する
• パターン別に切り分ける
• 設定と実装を同時に直す
• 監視と runbook に落とし込む

この流れを徹底するだけで、同じ障害の再発率は大きく下げられます。次に障害が起きたとき、慌てず順番に潰せる状態を今日作っておくのが最善です。

CI/CD の事故は、ビルドが失敗することより「漏えいしても気づけない鍵」が残り続けることのほうが深刻です。特に AWS_ACCESS_KEY_ID のような長期シークレットを GitHub Secrets に保存し続ける運用は、便利ですがリスクが高いです。

本記事では、GitHub Actions の OIDC（OpenID Connect）連携を使って、長期鍵を使わずに AWS へデプロイする実践手順をまとめます。単なる設定紹介ではなく、最小権限・ブランチ制限・監査ログ設計まで含めて、明日から本番投入できる形で説明します。

1. まず何が危険なのか：長期シークレット運用の限界

従来構成では、次のような問題が起きます。

• Secret が漏れても検知が遅い（CIログ、誤コミット、権限の広いメンバー）
• ローテーションが後回しになる
• 1つの鍵で複数環境へアクセスできてしまう
• 「誰のどの workflow 実行が何をしたか」が追いにくい

OIDC 連携では、GitHub が発行する短命トークンを信頼し、AWS 側で一時認証情報を払い出します。つまり、保管する鍵そのものを減らすのが最大の価値です。

2. 全体アーキテクチャ

基本フローは以下です。

1. GitHub Actions ジョブが OIDC トークンを取得
2. AWS IAM の OIDC プロバイダとロール信頼ポリシーで検証
3. 条件に一致したジョブだけ AssumeRoleWithWebIdentity
4. 一時クレデンシャルで S3/CloudFront/ECR/ECS へデプロイ

ポイントは「GitHub 側の workflow 制御」だけでなく、AWS 側で repo・branch・workflow を強制することです。

3. AWS 側の初期設定（OIDC Provider + IAM Role）

3.1 OIDC Provider を作成

CLI 例（すでに存在する場合はスキップ）:

1
2
3
4

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

3.2 信頼ポリシーを厳密化する

以下のように sub と aud を必ず絞ります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:your-org/your-repo:ref:refs/heads/main"
        }
      }
    }
  ]
}

sub を repo:org/repo:* のように広く取りすぎると、意図しない workflow からも引き受ける可能性があり危険です。

3.3 デプロイ権限ポリシーを分離する

「ロール1個に全部盛り」は避けます。

• deploy-web-prod-role: S3同期 + CloudFront invalidation
• deploy-api-prod-role: ECR push + ECS update
• read-only-audit-role: CloudWatch Logs / Describe 系のみ

環境別（dev/stg/prod）にロールを分離すると、誤デプロイ時の被害半径が大きく減ります。

4. GitHub Actions workflow 実装

最小サンプル:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

name: deploy-web
on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/deploy-web-prod-role
          aws-region: ap-northeast-1

      - name: Build
        run: |
          npm ci
          npm run build

      - name: Upload to S3
        run: aws s3 sync ./dist s3://example-prod-web --delete

      - name: Invalidate CloudFront
        run: aws cloudfront create-invalidation --distribution-id E123456 --paths "/*"

重要なのは permissions.id-token: write を明示する点です。これがないと OIDC トークンを取得できません。

5. 事故を防ぐための実務ルール

5.1 branch protection と environment protection を組み合わせる

• main 直push禁止
• 必ず PR + 1 approval
• production environment には Required reviewers を設定
• 夜間デプロイを禁止したい場合は手動承認ステップを入れる

5.2 workflow ファイル改変の監査

.github/workflows/*.yml の変更は CODEOWNERS で必ずレビュアー固定にします。

1

.github/workflows/*  @platform-team

5.3 self-hosted runner の扱い

OIDC を導入しても、runner 自体が侵害されると意味が薄れます。

• runner をプロジェクト共有にしない（専用化）
• ジョブ後にワークディレクトリをクリーン
• egress 制限をかける
• runner グループを環境ごとに分離

6. トラブルシューティング

症状1: Not authorized to perform sts:AssumeRoleWithWebIdentity

確認ポイント:

1. aud が sts.amazonaws.com になっているか
2. sub が実際の実行 ref と一致しているか（タグ実行でハマりやすい）
3. permissions.id-token: write が設定されているか
4. Role ARN の typo がないか

症状2: main 以外で偶発的にデプロイされた

• workflow の on.push.branches 見直し
• IAM 信頼ポリシー sub を main 固定へ
• 環境保護ルール（Required reviewers）追加

症状3: デプロイは通るが操作が一部失敗

これは IAM 権限不足の可能性が高いです。CloudTrail の eventName と errorCode を見て、必要最小限のアクションだけ追加します。闇雲に * を付けないこと。

7. 段階的な移行計画（既存運用からの切替）

実務では一気に切り替えず、以下の順が安全です。

1. OIDC ロールを作成（既存シークレットは残す）
2. staging workflow だけ OIDC に切替
3. 1週間監視（失敗率・デプロイ時間・CloudTrail）
4. production を OIDC 化
5. 最後に長期シークレットを削除

削除前に「どの workflow がどの secret を参照しているか」を grep で確認しておくと事故が減ります。

1

git grep -n "AWS_ACCESS_KEY_ID\|AWS_SECRET_ACCESS_KEY" .github/workflows

8. 監査ログ設計：何を見れば安全性が上がるか

最低限、次をダッシュボード化すると運用しやすいです。

• AssumeRoleWithWebIdentity 実行回数（日次）
• 失敗イベント数（権限エラー/条件不一致）
• production deploy 実行者（workflow + sha + actor）
• 1回のデプロイで変更された主要リソース数

CloudTrail + CloudWatch Logs Insights での簡易クエリ例:

1
2
3
4
5

fields @timestamp, userIdentity.sessionContext.sessionIssuer.userName, eventName, errorCode
| filter eventSource = "sts.amazonaws.com"
| filter eventName = "AssumeRoleWithWebIdentity"
| sort @timestamp desc
| limit 50

まとめ

OIDC は「設定が新しいから導入する」ものではなく、長期鍵を削減して事故確率を下げるための運用設計です。導入時にやるべきことはシンプルで、次の3つに集約できます。

1. IAM 信頼ポリシーを repo/branch 単位で厳密化する
2. workflow 側で id-token 権限と環境保護を設定する
3. CloudTrail で AssumeRole の監査を継続する

ここまで実施すれば、CI/CD のセキュリティは「頑張って守る」状態から、「漏えいしにくい仕組みで守る」状態へ進化します。まずは staging 1本から置き換えるのがおすすめです。

FastAPI は実装が速い反面、認証・認可を最小構成のまま本番に出してしまい、後からセキュリティ事故に発展するケースが少なくありません。特に「JWT を入れたから安全」という誤解は危険です。

本記事では、開発速度を落とさずに本番で耐える認証基盤を作るための設計を、コード例と運用手順込みで解説します。

1. 認証と認可を分離して設計する

最初に押さえるべきは責務分離です。

• 認証（Authentication）: 誰かを確認する
• 認可（Authorization）: 何をしてよいか判定する

この2つを混ぜると、実装も監査も破綻します。FastAPI では dependency を分け、get_current_user と require_permission を独立させるのが基本です。

2. JWT は「短命 + リフレッシュ + 失効管理」で使う

アクセストークンを長寿命にすると、漏えい時の被害が大きくなります。実運用では以下が標準です。

• Access Token: 5〜15分
• Refresh Token: 7〜30日
• Refresh Token は DB 保存し、ローテーション時に旧トークンを失効

sub だけでなく、jti（トークンID）や scope を持たせると管理しやすくなります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from datetime import datetime, timedelta, timezone
import jwt

ALGORITHM = "HS256"


def create_access_token(user_id: str, scopes: list[str], secret: str) -> str:
    now = datetime.now(timezone.utc)
    payload = {
        "sub": user_id,
        "scope": " ".join(scopes),
        "iat": int(now.timestamp()),
        "exp": int((now + timedelta(minutes=10)).timestamp()),
        "jti": "generated-uuid"
    }
    return jwt.encode(payload, secret, algorithm=ALGORITHM)

3. 鍵管理とローテーション

秘密鍵を .env に固定して数年運用するのは典型的な事故パターンです。最低限、次を実施します。

• KMS/Vault など外部シークレット管理を利用
• kid をヘッダに持たせ、複数鍵を並行運用
• 鍵ローテーション手順を runbook 化

ローテーションの要点:

1. 新鍵を追加（検証側は新旧どちらも受理）
2. 発行側を新鍵へ切替
3. 旧鍵の有効期限を過ぎたら削除

この手順にすると、無停止で切替できます。

4. FastAPI Dependencyで認可を明示化

ロジック中で if user.role == "admin" を乱立させると、抜け漏れが起こります。権限チェックは dependency 化し、ルート定義に明示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from fastapi import Depends, HTTPException, status


def require_permission(required: str):
    def checker(user=Depends(get_current_user)):
        if required not in user.permissions:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="insufficient permissions"
            )
        return user
    return checker


@router.delete("/projects/{project_id}")
def delete_project(
    project_id: str,
    user=Depends(require_permission("project:delete"))
):
    ...

ルート単位で要件が見えるため、レビュー効率と監査性が上がります。

5. RBAC/ABAC の使い分け

小規模なら RBAC（role-based）で十分ですが、顧客単位データや組織階層があると ABAC（属性ベース）を併用した方が安全です。

• RBAC: admin, editor, viewer
• ABAC: tenant_id, resource_owner_id, department

実務では「ロールで粗く許可し、属性で絞る」が扱いやすいです。

6. マルチテナントで必須の防御

マルチテナント API では、ID 推測よりもテナント境界漏れが主要リスクです。対策は次の通りです。

• すべての DB クエリに tenant_id 条件を必須化
• 管理者 API でも境界を明示的に超える操作だけ許可
• 監査ログに tenant_id, actor_id, resource_id を残す

SQLAlchemy でも repository 層で共通フィルタを強制すると漏れを減らせます。

7. 監査ログを設計段階で入れる

認証系は障害後に「誰が何をしたか」が必要になります。後付けだと間に合いません。最低限、次を記録します。

• ログイン成功/失敗（IP, user-agent, reason）
• 権限エラー（403）
• 重要操作（削除、権限変更、請求情報更新）
• トークン失効・再発行

フォーマットは JSON 構造化に統一し、SIEM や OpenSearch に流せる形にしておくと分析が速いです。

8. レート制限とブルートフォース対策

パスワード認証がある場合、レート制限なしは危険です。slowapi などを使い、ログイン系エンドポイントに制限を入れます。

1
2
3
4
5
6
7
8
9

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@router.post("/auth/login")
@limiter.limit("5/minute")
def login(...):
    ...

さらに次を組み合わせると強化できます。

• 失敗回数に応じた遅延（progressive delay）
• CAPTCHA（必要時のみ）
• 異常IP/ASN の遮断

9. よくある実装ミス

ミスA: 署名検証はしているが aud/iss 未検証

結果:

• 他システム向けトークンを誤受理

対処:

• issuer/audience を厳格検証
• 想定外クレームは拒否

ミスB: refresh token の使い回しを検知しない

結果:

• 漏えい時に長期間乗っ取られる

対処:

• ローテーション時に旧トークン失効
• 再利用検知時はセッション全失効

ミスC: 認可チェックが一部エンドポイントで抜ける

結果:

• 水平権限昇格

対処:

• dependency ベースで強制
• 重要ルートにセキュリティテスト追加

10. テスト戦略（必須）

認証はユニットテストだけでなく、統合テストで権限境界を確認します。

• 有効トークン/期限切れ/改ざんトークン
• role ごとのアクセス可否
• tenant 越境アクセス拒否
• refresh token 再利用検知

pytest では fixture で role 別トークンを用意し、回帰を防ぎます。

11. 障害時 runbook（最低限）

インシデント時に迷わないよう、次を文書化しておきます。

1. 鍵漏えい疑い時の全トークン失効手順
2. 認証基盤障害時のフェイル動作（許可しすぎを防ぐ）
3. 監査ログの検索手順
4. 関係者通知テンプレート

特に「認証サーバーが落ちたとき、API をどうするか」は事前に決めておく必要があります。

12. 導入チェックリスト

• access token は短寿命（<=15分）
• refresh token は DB 管理 + ローテーション
• 鍵ローテーション手順がある
• ルート単位で認可 dependency が明示されている
• tenant 境界を DB レイヤーで強制している
• 監査ログ（認証/認可/重要操作）を構造化保存
• レート制限と異常検知がある
• 権限境界の統合テストがある

FastAPI の認証・認可は、フレームワーク機能だけでは守り切れません。トークン寿命設計、鍵運用、境界強制、監査、テスト、runbookまで含めて初めて、本番で信頼できるセキュリティ基盤になります。

PostgreSQL を長期運用すると、遅かれ早かれぶつかるのが bloat（テーブル/インデックス肥大化）です。CPU やメモリを増やしても、実体は不要領域の蓄積なので、根本原因を処理しない限り性能は戻りません。

本記事では、サービス停止なしで bloat を抑える運用を目標に、Autovacuum 設計、監視、メンテ手順を実践ベースで解説します。

1. なぜ肥大化が起きるのか

PostgreSQL は MVCC を採用しているため、UPDATE/DELETE で古い行バージョンが即時削除されません。不要バージョンは VACUUM で回収されますが、追いつかないと肥大化します。

肥大化が進むと以下が起こります。

• 同じデータ量でも I/O が増える
• インデックス探索が遅くなる
• キャッシュ効率が落ち、p95 レイテンシが悪化
• 自動メンテの時間がさらに伸びる（悪循環）

重要なのは、「遅くなってから対処」だと回復コストが高いという点です。

2. 最初に見るべき指標

運用でまず可視化するのは次の4つです。

1. n_dead_tup（死んだタプル数）
2. last_autovacuum（最後に vacuum が走った時刻）
3. テーブルサイズ・インデックスサイズ推移
4. age(relfrozenxid)（XID 消費進行）

確認クエリ例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

SELECT
  schemaname,
  relname,
  n_live_tup,
  n_dead_tup,
  last_autovacuum,
  last_vacuum
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC
LIMIT 20;

XID の健全性チェック:

1
2
3
4
5

SELECT
  datname,
  age(datfrozenxid) AS xid_age
FROM pg_database
ORDER BY xid_age DESC;

xid_age が高いのに vacuum が遅れている場合は、緊急度が高いです。

3. Autovacuum の基本パラメータ設計

デフォルト設定は小規模環境向けで、更新量が多い本番には不足しやすいです。まずは「全体設定 + ホットテーブル個別設定」に分けて調整します。

代表的パラメータ:

• autovacuum_max_workers
• autovacuum_naptime
• autovacuum_vacuum_cost_limit
• autovacuum_vacuum_scale_factor
• autovacuum_vacuum_threshold

考え方:

• 更新頻度が高いテーブルは scale_factor を下げる（例: 0.2 → 0.02）
• 小さなテーブルは threshold 主体、大きなテーブルは scale factor 主体
• まず vacuum が「間に合う」状態を作る

個別テーブル例:

1
2
3
4
5
6

ALTER TABLE events
  SET (
    autovacuum_vacuum_scale_factor = 0.01,
    autovacuum_vacuum_threshold = 5000,
    autovacuum_analyze_scale_factor = 0.02
  );

4. インデックス肥大化の見落としに注意

テーブル側だけ見ていて、実際のボトルネックがインデックス側というケースは非常に多いです。特に更新頻度の高い B-Tree インデックスで顕著です。

実務では次を定期確認します。

• 使用頻度が低い巨大インデックス
• 重複インデックス
• インデックスサイズ増加率（週次）

重複候補を探す SQL（簡易）:

1
2
3
4
5
6

SELECT
  indexrelid::regclass AS index_name,
  indrelid::regclass AS table_name,
  pg_get_indexdef(indexrelid)
FROM pg_index
WHERE indisvalid = true;

実際は pg_stat_user_indexes と組み合わせ、idx_scan がほぼゼロのものを優先削減します。

5. REINDEX と pg_repack の使い分け

肥大化したインデックスを戻すには REINDEX が基本ですが、ロック影響を避けたい場合は REINDEX CONCURRENTLY を選びます。

• 影響小で安全重視: REINDEX INDEX CONCURRENTLY
• まとめて再編成: pg_repack（導入・権限管理が必要）

例:

1

REINDEX INDEX CONCURRENTLY idx_orders_created_at;

注意点:

• ディスク空き容量を事前確認（再構築時に追加領域が必要）
• 長時間トランザクションがあると完了しない
• 実行ウィンドウを決め、監視を付ける

6. vacuum が進まない時の切り分け

「Autovacuum が動いているのに改善しない」時は、次の順で確認します。

1. 長時間トランザクションが残っていないか
2. レプリカ遅延や hot_standby_feedback で cleanup が妨げられていないか
3. I/O 飽和で vacuum が極端に遅くなっていないか
4. freeze 対象の backlog が巨大化していないか

長時間トランザクション確認:

1
2
3
4
5

SELECT pid, usename, state, xact_start, now() - xact_start AS tx_age, query
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
ORDER BY xact_start ASC
LIMIT 20;

tx_age が長い接続は、vacuum の前進を阻害する最優先要因です。

7. 実運用で効くスケジュール設計

本番では「毎晩まとめて重い処理」より、小さく高頻度に回す方が安定します。

• 日中: autovacuum でこまめに回収
• 深夜: 重いテーブルの VACUUM (ANALYZE) を計画実行
• 週次: 重要インデックスの肥大化確認
• 月次: 上位肥大化テーブルの再編成計画レビュー

ANALYZE を外すとプランが古くなるため、統計更新を一体運用にします。

8. 典型インシデントと復旧手順

ケースA: API レイテンシ急上昇

兆候:

• CPU は高くないがクエリ時間が増加
• 特定テーブルの n_dead_tup が急増

対処:

1. 長時間トランザクションを特定
2. 対象テーブルに VACUUM (VERBOSE, ANALYZE)
3. 重度ならインデックス再構築を計画

ケースB: ストレージ逼迫

兆候:

• disk 使用率が短期間で増加
• UPDATE 多発テーブルが存在

対処:

1. サイズ上位テーブル・インデックスを抽出
2. 不要インデックス削除
3. REINDEX CONCURRENTLY / pg_repack を段階実行

ケースC: wraparound 警告

兆候:

• autovacuum: preventing wraparound ログ

対処:

1. 緊急度を最優先に切替
2. 長時間 TX を停止
3. freeze 対象テーブルを優先 vacuum

9. 導入時チェックリスト

• 上位更新テーブルに個別 autovacuum パラメータがある
• n_dead_tup と last_autovacuum を監視している
• 長時間トランザクションのアラートがある
• インデックス使用率 (idx_scan) を定期レビューしている
• REINDEX 実行時の空き容量基準を定義している
• wraparound 対応 runbook がある

10. 30日改善プラン（最短で効果を出す）

Week 1

• 現状計測（dead tuple、サイズ、xid age）
• ホットテーブル上位10件を特定

Week 2

• テーブルごとに autovacuum 個別設定
• 長時間 TX 監視アラート導入

Week 3

• 低利用/重複インデックス整理
• 対象インデックスを REINDEX CONCURRENTLY

Week 4

• 実行後の p95 クエリ時間、ストレージ増加率を比較
• 設定の再チューニングと runbook 更新

PostgreSQL の肥大化対策は、一発のメンテで終わる作業ではありません。観測 → 個別設定 → 段階的再編成 → 監視改善を繰り返すことで、停止なしでも安定して性能を維持できます。

GitHub Actions は便利ですが、プロジェクトが成長すると「遅い」「不安定」「原因が分かりにくい」という三重苦になりがちです。特に monorepo や複数ランタイム対応（Node/Python/Go など）では、ワークフローの設計次第で CI 時間が 2〜3 倍変わります。

本記事では、実行時間を短くしながら失敗時の調査コストも下げるために、matrix 設計・キャッシュ設計・障害時の確認順序を具体的に整理します。

1. まず「何を並列化するか」を決める

Actions の高速化は、いきなりキャッシュ最適化から入るより、先にジョブ分解を決める方が効きます。原則は次の通りです。

• 並列化すべき: 独立テスト（OS/バージョン別、サービス別）
• 直列にすべき: デプロイ、DB マイグレーション、本番反映
• 依存を分ける: lint/typecheck/test/build を一つに詰め込まない

悪い例は、1ジョブに全部詰め込み、失敗時に最初から再実行するパターンです。良い設計では「lint は通るが test だけ失敗」のように切り分けできます。

2. matrix を作るときの実践ルール

matrix は便利ですが、組み合わせ爆発で逆に遅くなることがあります。例えば os x runtime x db をすべて直積にすると、不要なジョブが大量発生します。そこで include/exclude を活用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [20, 22]
    include:
      - os: ubuntu-latest
        node: 22
        coverage: true
    exclude:
      - os: macos-latest
        node: 20

ポイントは次です。

1. 基準環境を1つ決める（例: ubuntu + latest）
2. カバレッジ計測や重い E2E は基準環境だけで実施
3. 互換性確認は軽量テスト中心にする

この設計にすると、品質を落とさずに全体時間を短縮できます。

3. キャッシュは「鍵設計」が9割

actions/cache や setup-node / setup-python のキャッシュを入れても、キー設計が甘いとヒット率が低く、逆に復元時間だけ増えます。

Node.js の例:

1
2
3
4
5
6
7

- uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node }}
    cache: 'npm'
    cache-dependency-path: |
      package-lock.json
      packages/*/package-lock.json

Python (pip) の例:

1
2
3
4
5
6
7

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
    cache-dependency-path: |
      requirements.txt
      requirements-dev.txt

実務で効くコツ:

• lockfile をキーに含める（依存変化に追従）
• OS・ランタイムバージョンをキーに含める
• monorepo は対象サブディレクトリ単位でキー分割
• restore-keys を入れすぎない（古いキャッシュ復元で不整合）

4. concurrency で「古い実行を止める」

PR に連続 push されると、古い CI が残り続けてランナー枯渇を起こします。concurrency を入れて、最新コミットだけ走らせる構成にします。

1
2
3

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

これだけで無駄実行を大きく減らせます。特にレビュー中に細かい修正を重ねるチームほど効果が高いです。

5. paths-filter で不要ジョブを起動しない

ドキュメント更新だけなのに全テストが走る、という状態はよくあります。dorny/paths-filter で変更範囲に応じてジョブを分岐します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

- uses: dorny/paths-filter@v3
  id: changes
  with:
    filters: |
      backend:
        - 'backend/**'
      frontend:
        - 'frontend/**'

# 例: backend が変わった時だけ実行
if: steps.changes.outputs.backend == 'true'

これにより、実行時間だけでなくランナーコストも下げられます。

6. 失敗時の調査を速くするログ設計

CI が遅い組織は、だいたい「失敗調査も遅い」です。改善するには、次の3点を標準化します。

• 失敗したジョブで artifact（ログ、スクリーンショット、coverage）を必ず保存
• 重要ステップに ::group:: を付けてログを畳む
• flaky テスト検出用に rerun 情報を残す

artifact 例:

1
2
3
4
5
6
7
8

- name: Upload test reports
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: test-report-${{ matrix.os }}-${{ matrix.node }}
    path: |
      reports/
      coverage/

if: always() を忘れると、失敗時ほど証跡が残らないので注意です。

7. self-hosted runner を使う場合の注意点

高速化目的で self-hosted runner を導入する場合、運用事故が増えやすい領域です。

• 毎回クリーンワークスペース化（残骸で再現不能バグ）
• シークレットを runner に永続化しない
• パッチ適用・再起動の定期メンテをスケジュール化
• runner ラベルを用途別に分離（deploy と test を混在させない）

また、デプロイ権限を持つ runner と、PR 由来コードを実行する runner は分離するのが基本です。

8. 実際の改善ステップ（2週間）

Day 1-2: 現状計測

• 平均実行時間、p95 実行時間、失敗率を取得
• 一番遅いジョブ上位3つを特定

Day 3-5: ジョブ分割と matrix 整理

• lint/typecheck/test/build を分離
• matrix の組み合わせを include/exclude で整理

Day 6-8: キャッシュ最適化

• lockfile ベースキーへ統一
• キャッシュヒット率を可視化

Day 9-10: 無駄実行削減

• concurrency + cancel-in-progress
• paths-filter で対象限定

Day 11-14: 運用ルール化

• 失敗時 artifact を全ジョブ標準化
• flaky テスト記録のテンプレート化

この手順で進めると、速度改善だけでなく再発防止まで一気に整います。

9. よくある失敗パターン

パターンA: キャッシュを入れたのに遅い

原因:

• キーが細かすぎて毎回ミスヒット
• 圧縮/復元コストが大きいディレクトリを丸ごとキャッシュ

対処:

• 依存に限定してキャッシュ
• キーに lockfile ハッシュを利用

パターンB: matrix 失敗がノイズ化

原因:

• fail-fast: true で他環境の情報が取れない
• ログ命名が統一されず比較困難

対処:

• fail-fast: false
• artifact 命名規則を統一

パターンC: PR の待ち時間が長い

原因:

• 古いコミットの CI が走り続ける
• 変更範囲に関係ないジョブが常時起動

対処:

• concurrency で古い実行を停止
• paths-filter 導入

10. 運用チェックリスト

• ジョブは責務別に分離されている
• matrix は必要最小限に絞られている
• 依存キャッシュのキーに lockfile が含まれる
• concurrency で古い実行をキャンセルしている
• 変更範囲に応じたジョブ起動制御がある
• 失敗時 artifact が必ず残る

GitHub Actions は「機能を使う」だけでは速くなりません。実行単位の設計、キャッシュ鍵設計、無駄実行抑制、証跡設計をセットで行うと、初めて安定した CI 基盤になります。

Kubernetes は「自動でスケールするから安心」と思われがちですが、実運用では逆です。HPA、VPA、Cluster Autoscaler（CA）の設定が噛み合わないと、スケールアウトと再スケジューリングが衝突し、レイテンシ悪化やコスト増大を引き起こします。

本記事では、3つのオートスケーリング機構を同時運用する際の設計ポイントを、障害対応目線で整理します。

1. 役割分担を明確にする

まず前提として、各コンポーネントの責務を固定します。

• HPA: Pod 数を短期的に増減
• VPA: Pod あたりの requests/limits を中長期で最適化
• CA: ノード数を増減

この役割分担が曖昧だと、同じ問題を複数レイヤーで同時に解こうとして不安定化します。特に Web/API ワークロードでは、HPA を主軸、VPA は recommendation 中心で始めるのが安全です。

2. requests/limits が崩れていると全て失敗する

HPA の CPU 指標は requests 基準で計算されます。requests が不正確だと、HPA の判断もズレます。最初にやるべきは次です。

1. 過去 2 週間の実使用量を可視化
2. p95 使用量を requests の初期値に設定
3. limits は requests の 1.5〜2 倍で開始

極端に低い requests は「見かけの高負荷」を作り、不要スケールを誘発します。逆に高すぎる requests は CA の過剰増設を招きます。

3. HPA 指標選定の実践

CPU だけで運用すると、I/O 待ちや外部 API 待ちのボトルネックを見逃します。推奨は複合指標です。

• CPU Utilization（基本）
• メモリ使用率（リーク監視）
• RPS あたりレイテンシ（SLO 接続）
• Queue 長（非同期処理）

autoscaling/v2 では複数メトリクスを扱えるため、最初から設計しておくと後で楽です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api
  minReplicas: 3
  maxReplicas: 30
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60
    - type: Pods
      pods:
        metric:
          name: http_requests_per_second
        target:
          type: AverageValue
          averageValue: "80"

4. スケール挙動を安定化する

HPA は設定次第で「増えすぎ・減りすぎ」を起こします。behavior を入れて振動を抑えます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

behavior:
  scaleUp:
    stabilizationWindowSeconds: 0
    policies:
      - type: Percent
        value: 100
        periodSeconds: 60
  scaleDown:
    stabilizationWindowSeconds: 300
    policies:
      - type: Percent
        value: 20
        periodSeconds: 60

スケールアップは素早く、スケールダウンは慎重に、が基本です。障害時の復旧速度と平常時コストのバランスを取りやすくなります。

5. VPA の安全な導入順序

VPA をいきなり Auto で入れると、Pod 再作成が頻発し、ピーク時間帯に影響することがあります。次の順序を推奨します。

1. Off で recommendation だけ収集
2. 2〜4週間データ蓄積
3. 非クリティカルなバッチ系から Auto 開始
4. API 系は Initial または手動反映を継続

この段階導入にすると、VPA が既存 SLO を壊すリスクを抑えられます。

6. HPA と VPA の衝突回避

同一 Deployment で CPU/Memory の両方を HPA と VPA が同時に強く制御すると、調整ループが競合します。現場では次の運用が現実的です。

• HPA: レプリカ数を制御（主）
• VPA: requests 最適化（従）
• クリティカルサービスは VPA recommendation を人間レビューして反映

また、メモリで OOM が起こるサービスは、HPA より先にアプリ側リーク調査を優先します。スケールで隠すと後で必ず再発します。

7. Cluster Autoscaler の盲点

CA は Pending Pod を見てノードを増やしますが、以下の条件で期待通り動きません。

• PDB が厳しすぎて eviction できない
• NodeSelector/taint 制約で配置先がない
• requests が過大で BinPacking 不可能

スケールしない時の確認手順を runbook 化しておくと、夜間障害で迷いません。

1. Pending Pod の events を確認
2. CA logs で scale-up decision を確認
3. node group の上限値と quota を確認
4. Pod 制約（affinity/taint/tolerations）を確認

8. 典型障害シナリオと対処

シナリオA: 突発トラフィックで 5xx 増加

• 兆候: CPU 90%超、pod 起動待ち
• 対処: HPA minReplicas を一時引き上げ、イメージ pull 最適化、readiness 調整
• 恒久策: 予測ピーク前の scheduled scaling を導入

シナリオB: コスト急増

• 兆候: ノード数だけ増えて利用率低い
• 対処: requests 見直し、scaleDown stabilization 調整、CA consolidate 有効化
• 恒久策: ワークロード別の node pool 分離

シナリオC: 断続的なタイムアウト

• 兆候: CPU 余裕あり、レイテンシ悪化
• 対処: 外部依存（DB/Redis/API）をトレースで確認
• 恒久策: HPA 指標に queue 長・レイテンシを追加

9. 実運用のメトリクスセット

運用ダッシュボードには、最低限次を置きます。

• HPA current/desired replicas
• Pod 起動時間（image pull + readiness）
• Pod Pending 数と理由
• Node 利用率（CPU/Memory）
• CA scale up/down イベント数
• 5xx 率と p95 latency

このセットがあると「スケーラが原因か、アプリが原因か」を 5 分以内で切り分けられます。

10. 段階的チューニング手順（4週間）

Week 1: ベースライン計測

• 現行 requests/limits と実使用量を比較
• HPA 閾値を仮設定（CPU 60%）

Week 2: 振動抑制

• behavior 追加
• scaleDown window を 300s 前後で調整

Week 3: 指標追加

• RPS/queue 指標を導入
• アラートを SLO 連動へ変更

Week 4: コスト最適化

• idle 時の minReplicas 見直し
• node pool の統廃合

この 4 週間を回すだけでも、無駄スケールと障害時復旧の両方が改善します。

11. 導入チェックリスト

• requests/limits が実使用量に基づいている
• HPA に behavior を設定済み
• VPA は recommendation 期間を経て適用している
• CA の上限値・quota・制約を定期点検している
• SLO 指標とスケーリング指標を接続している
• 典型障害シナリオの runbook がある

Kubernetes のスケーリングは、機能を有効にするだけでは安定しません。役割分担、指標設計、調整ループの制御、そして runbook をセットで整えることで、初めて「自動化が味方になる」状態を作れます。

「監視は入れているのに障害原因の特定が遅い」。この状態は、たいていデータが足りないのではなく、データが分断されていることが原因です。メトリクスは見える、ログは別画面、トレースは導入途中、という構成だと、オンコールは毎回同じ調査を手作業で繰り返すことになります。

OpenTelemetry（OTel）はこの分断を減らすための共通規格です。ただし、導入に失敗するチームも少なくありません。理由は単純で、「計測の追加」だけやって「運用設計」を後回しにするからです。

本記事では、OpenTelemetry を 90 日で現場定着させるための、実務寄りの導入手順を紹介します。

1. まず決めるべき運用目標

OTel を入れる前に、次の問いに答えます。

• どの障害をどれだけ早く見つけたいか
• どのサービスの MTTR をどれだけ下げたいか
• どのチームがトリアージ責任を持つか

たとえば「API 5xx の原因調査を 60 分 → 15 分に短縮する」と明文化すると、必要な計測が決まります。逆に目標がないと、span を増やす作業が目的化して終わります。

2. 参照アーキテクチャ

本番で扱いやすい最小構成は次です。

1. アプリケーションに OTel SDK を導入
2. エージェント/サイドカー経由で OTel Collector に送信
3. Collector で加工・サンプリング・ルーティング
4. Prometheus / Loki / Tempo（または商用基盤）へ出力

Collector を中継に置く理由は、アプリ側の再デプロイなしでルール変更できるからです。運用現場ではここが非常に効きます。

3. サービス命名規則を最初に固定する

命名規則を後で直すと、ダッシュボードとアラートが壊れます。以下は最低限のルール例です。

• service.name: domain-service-env（例: billing-api-prod）
• deployment.environment: prod|stg|dev
• service.version: Git SHA または semver
• cloud.region: 実リージョン名

この 4 つが揃うと、障害時に「どの環境・どのバージョン」が悪いか一気に絞れます。

4. Pythonサービス計測の実装例

FastAPI を例に、最小導入手順を示します。

1
2
3
4

pip install opentelemetry-distro \
  opentelemetry-exporter-otlp \
  opentelemetry-instrumentation-fastapi \
  opentelemetry-instrumentation-requests

起動時に auto-instrumentation を有効化します。

1
2
3
4
5
6
7

export OTEL_SERVICE_NAME=billing-api-prod
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

opentelemetry-instrument uvicorn app.main:app --host 0.0.0.0 --port 8080

次に、業務的に重要な処理へ custom span を追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def charge_customer(order_id: str, customer_id: str, amount: int):
    with tracer.start_as_current_span("billing.charge") as span:
        span.set_attribute("order.id", order_id)
        span.set_attribute("customer.id", customer_id)
        span.set_attribute("payment.amount", amount)
        # 決済処理

HTTP 自動計測だけでは業務上のボトルネックが見えません。注文IDや課金金額など、調査に必要な属性を入れることが重要です。

5. Collector設定の実践パターン

Collector の典型構成は次です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  batch:
    send_batch_size: 1024
    timeout: 5s
  resource:
    attributes:
      - key: deployment.environment
        value: prod
        action: upsert

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true
  prometheusremotewrite:
    endpoint: http://mimir:9009/api/v1/push

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch, resource]
      exporters: [otlp/tempo]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch, resource]
      exporters: [prometheusremotewrite]

ポイントは memory_limiter と batch を必ず入れることです。高負荷時の Collector 落ちを防げます。

6. サンプリング戦略

全トレースを保存すると費用が跳ねます。まずは次の段階運用が現実的です。

• フェーズ1: 10% head sampling
• フェーズ2: エラーは 100%、正常は 5%
• フェーズ3: 高価値APIのみ 20%、その他 1%

さらに Collector で tail sampling を使うと、異常リクエストを優先的に残せます。導入初期は head sampling だけでも十分ですが、障害解析を重視するなら tail sampling への移行を計画に含めます。

7. ログとの相関を必ず作る

トレースだけ可視化しても、最終的にはログを見ます。ログに trace_id と span_id を埋め込み、画面から相互ジャンプできるようにします。

Python の標準 logging なら、フォーマッタに trace_id を追加するだけで改善します。アプリ基盤に共通 formatter を置いて強制するのが現実的です。

8. SLO/アラート設計の接続

OTel 導入の価値は、可視化だけでなく SLO 運用に繋がる点です。例:

• SLI: http.server.duration の p95
• SLI: http.server.request.count に対する 5xx 率
• エラーバジェット消費率が閾値超過でページ

ここで重要なのは、アラート本文に「関連トレースのリンク」を入れることです。オンコールが即座に原因調査へ入れます。

9. 90日導入ロードマップ

Day 1-14: 土台づくり

• 命名規則決定
• Collector を冗長構成で配置
• 主要 2 サービスへ SDK 導入

Day 15-45: 運用化

• 主要 API の custom span 追加
• ダッシュボード標準化
• エラー系アラートにトレースリンクを追加

Day 46-90: 最適化

• サンプリング改善（費用最適化）
• ノイズアラート削減
• 週次レビューで MTTR 変化を追跡

この 90 日で「導入しただけ」から「使って解決できる」状態に変わります。

10. よくある失敗と対策

失敗1: span を増やしすぎて遅くなる

対策: 重要フローに限定し、属性も最小から始める。

失敗2: PII を属性に入れてしまう

対策: Collector でマスキング、アプリ側で禁止 lint を導入。

失敗3: ダッシュボードがチームごとにバラバラ

対策: プラットフォーム側で共通テンプレートを配布し、必須指標を統一。

11. 導入チェックリスト

• service.name / deployment.environment / service.version が揃っている
• Collector に memory_limiter と batch が入っている
• トレースとログが trace_id で相関できる
• エラー率アラートからトレースへ遷移できる
• サンプリング率と月次コストをレビューしている
• 主要障害のポストモーテムで観測改善が反映される

OpenTelemetry は魔法のツールではありません。しかし、計測規約と運用フローをセットで設計すると、障害対応の速度と質は確実に上がります。まずは 2 サービスで勝ち筋を作り、そこから全体展開するのが最短ルートです。

Terraform を導入していても、運用が進むほど「実環境がいつの間にかコードとズレる」問題にぶつかります。いわゆるドリフトです。最初は小さな差分でも、放置すると本番変更時に予期せぬ差分が混ざり、障害やリリース遅延の原因になります。

本記事では、Terraform ドリフト検知を単なる terraform plan 実行で終わらせず、継続運用できる仕組みとして実装するための具体策をまとめます。対象は AWS を例にしますが、考え方は他クラウドでも共通です。

1. ドリフト検知で最初に決めるべきこと

多くのチームが失敗するのは、実装前に運用設計を決めないことです。まず以下を決めます。

1. どの環境をいつ検知するか（prod は毎日、stg は平日など）
2. 検知結果をどこに通知するか（Slack/Discord/Issue）
3. 誰がいつまでに対応するか（当番制、SLA）
4. 「意図した手動変更」をどう扱うか（例外ラベル、期限付き）

ここを決めずに CI だけ作ると、通知がノイズ化して無視されます。ドリフト検知は技術課題より運用課題です。

2. リポジトリ構成と state 分離

最小限、次のような構成を推奨します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

infra/
  modules/
    vpc/
    ecs/
    rds/
  envs/
    prod/
      main.tf
      backend.hcl
      variables.tf
    stg/
      main.tf
      backend.hcl
.github/
  workflows/
    terraform-drift.yml

環境ごとに backend と state を分けることが重要です。ドリフト検知ジョブが state を誤って参照すると、存在しない差分が出ます。S3 backend + DynamoDB lock を使う場合は、bucket/key/region/table の整合性を必ず固定化します。

3. CI での検知フロー（GitHub Actions）

以下は、毎朝実行してドリフトを検知する最小構成です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

name: terraform-drift

on:
  schedule:
    - cron: "0 22 * * *" # JST 07:00
  workflow_dispatch:

jobs:
  drift-prod:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra/envs/prod
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.9.8

      - name: Configure AWS credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-terraform-readonly
          aws-region: ap-northeast-1

      - name: Init
        run: terraform init -backend-config=backend.hcl

      - name: Drift check
        run: terraform plan -detailed-exitcode -out=tfplan

-detailed-exitcode は実務で必須です。終了コードの意味は以下です。

• 0: 差分なし
• 1: エラー
• 2: 差分あり（ドリフト含む）

これを使えば、差分ありと失敗を明確に分けられます。

4. 終了コードを正しく扱う

Actions で単純に terraform plan を実行すると、終了コード 2 が failure 扱いになるため、実際には「検知成功」なのに赤く見えます。以下のように分岐して扱います。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

set +e
terraform plan -detailed-exitcode -out=tfplan
code=$?
set -e

if [ "$code" -eq 0 ]; then
  echo "DRIFT=false" >> $GITHUB_ENV
elif [ "$code" -eq 2 ]; then
  echo "DRIFT=true" >> $GITHUB_ENV
else
  echo "Terraform plan failed"
  exit 1
fi

この実装にすると、ジョブ自体は成功させたまま「ドリフト有無」を後段に渡せます。

5. 通知設計：差分サマリを人間が読める形にする

ドリフト検知で最も大事なのは、通知が読みやすいことです。plan 全文を貼ると誰も読みません。次の 3 つだけ通知します。

1. どの環境で
2. 何が（resource type + name）
3. どう変わるか（create/update/delete）

例: terraform show -json tfplan を jq で要約

1
2
3
4
5

terraform show -json tfplan > plan.json
jq -r '
  .resource_changes[] |
  "- \(.type).\(.name): \(.change.actions | join(","))"
' plan.json | head -n 50 > summary.txt

通知文は長すぎると切れるため、冒頭 50 件だけに制限し、全文は artifacts に添付する運用が実践的です。

6. 誤検知を減らす具体策

ドリフト検知の信頼性を下げる典型例は次です。

• timestamp 的な値を管理対象にしている
• provider バージョン差で毎回微差分が出る
• autoscaling 系設定が外部コントローラで更新される

対策として、lifecycle { ignore_changes = [...] } を乱用せず、変化が許容される属性だけを限定的に無視します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

resource "aws_ecs_service" "app" {
  name            = "app"
  cluster         = aws_ecs_cluster.main.id
  task_definition = aws_ecs_task_definition.app.arn

  lifecycle {
    ignore_changes = [
      desired_count
    ]
  }
}

ignore_changes は便利ですが、広げすぎると本当に危険なドリフトを見逃します。四半期ごとに見直しを入れてください。

7. 復旧フロー：検知後に迷わない手順

ドリフトを検知したら、毎回議論しないように Runbook 化します。

ステップA: 変更の意図確認

• 直近の障害対応や緊急作業がなかったか
• コンソール手動変更のチケットがあるか

ステップB: 差分分類

• 許容（意図あり）
• 要コード反映（意図あり、IaC未反映）
• 要即時修正（意図なし）

ステップC: 実行方針

• IaC 正とする場合: コード更新 → PR → apply
• 実環境正としない場合: 手動変更を戻す、または Terraform apply で整合

このフローを当番が 30 分以内に回せるようにすると、検知の価値が跳ね上がります。

8. IAM 最小権限の実例

ドリフト検知専用ロールは read-only を原則にします。plan だけなら多くのサービスで読み取り権限で足ります。apply 権限を同じロールに入れると、漏えい時のリスクが大きくなります。

• github-terraform-readonly: drift check 用
• github-terraform-apply: manual approval 後に限定実行

この分離は監査対応でも説明しやすく、セキュリティレビューで通りやすいです。

9. 週次レポートで改善を回す

検知を入れたら終わりではありません。週次で次を見ます。

• ドリフト検知件数
• うち誤検知件数
• MTTR（検知から解消まで）
• 原因カテゴリ（手動運用、自動スケール、設定ミス）

誤検知率が 30% を超えるなら通知設計か ignore ポリシーが過剰です。逆に検知ゼロが長すぎる場合は、ジョブ自体が死んでいる可能性もあります。

10. 導入チェックリスト

最後に、導入時のチェックリストを置いておきます。

• env ごとに backend/state 分離済み
• terraform plan -detailed-exitcode を採用
• 終了コード 2 を正常系として処理
• 通知は summary + artifacts の二段構成
• read-only ロールで drift check を実行
• 復旧 Runbook を 1 ページ化
• 週次で誤検知率と MTTR をレビュー

Terraform ドリフト検知は、単なる監視ではなく「IaC の信頼性を維持する運用基盤」です。最初から完璧を狙うより、通知品質と対応フローを小さく回して改善する方が、結果的に強い運用になります。

11. すぐ使える運用コマンド（当番向け）

最後に、当番が迷わず実行できる最小コマンドをまとめます。どれも「まず状況把握」を優先する順序です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 1) 直近のドリフトジョブ確認（GitHub CLI）
gh run list --workflow terraform-drift.yml --limit 5

# 2) 失敗/差分あり実行のログ確認
gh run view <run-id> --log

# 3) 対象環境で再現確認（ローカル）
cd infra/envs/prod
terraform init -backend-config=backend.hcl
terraform plan -detailed-exitcode

# 4) 差分要約を作成
terraform plan -out=tfplan
terraform show -json tfplan | jq -r '.resource_changes[] | "- \(.type).\(.name): \(.change.actions | join(","))"'

この 4 ステップを運用手順書の先頭に置くだけで、一次対応の速度と品質が安定します。特に「誰が見ても同じ順序で確認できる」状態を作ることが、夜間障害時の認知負荷を大きく下げます。

Redis を使っていても、ピークトラフィック時に DB が突然落ちることがあります。原因の多くはキャッシュスタンピードです。人気キーの TTL が同時に切れると、大量リクエストが一斉に DB へ流れ、接続プールが飽和します。

「Redis を入れたのに遅い」「ピーク時だけ 500 が増える」という現象は、このパターンで説明できることが非常に多いです。

本記事では、キャッシュスタンピードを実運用で防ぐために、設計原則・実装パターン・監視方法を順に解説します。

1. キャッシュスタンピードとは何か

典型シナリオ:

1. 商品ランキング API が ranking:daily を Redis に 300 秒で保存
2. 300 秒後、人気時間帯にキー期限切れ
3. 同時に 1000 リクエストが miss
4. 1000 回 DB 集計が走ってレイテンシ急増

このとき Redis 自体は正常でも、背後の DB が壊れます。つまり、問題はキャッシュ障害ではなく「再生成の同時実行制御」です。

2. 防御の基本は三層構え

スタンピード対策は単一施策では不十分です。次の三層を組み合わせると安定します。

1. 同時再生成の抑制（singleflight / 分散ロック）
2. 期限切れの分散（TTL ジッター）
3. 期限切れ後の挙動制御（stale-while-revalidate）

3. パターン1: singleflight で同時再生成を止める

同一キーの miss が同時発生しても、1 リクエストだけ再生成し、他は待つ設計です。

TypeScript 例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

const inflight = new Map<string, Promise<string>>();

async function getOrCompute(key: string, ttlSec: number, compute: () => Promise<string>) {
  const cached = await redis.get(key);
  if (cached) return cached;

  if (!inflight.has(key)) {
    const p = (async () => {
      try {
        const value = await compute();
        await redis.set(key, value, { EX: ttlSec });
        return value;
      } finally {
        inflight.delete(key);
      }
    })();
    inflight.set(key, p);
  }

  return await inflight.get(key)!;
}

単一プロセスではこれで十分ですが、複数インスタンス構成では分散ロックも必要です。

4. パターン2: 分散ロック（SET NX EX）

複数 Pod で同時 miss が起きる場合、Redis ロックで再生成担当を 1 つに制限します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const lockKey = `lock:${key}`;
const lock = await redis.set(lockKey, instanceId, { NX: true, EX: 10 });

if (lock) {
  // ロック獲得: 再生成担当
  const value = await compute();
  await redis.set(key, value, { EX: ttlSec });
  await redis.del(lockKey);
  return value;
}

// ロック未獲得: 少し待って再取得
await sleep(40);
return await redis.get(key);

注意点は、ロック TTL が短すぎると再生成中に失効し、二重計算になることです。処理時間の p99 を見て余裕を持って設定してください。

5. パターン3: TTL ジッターで期限切れを分散

同系統キーが同時に切れると負荷波形が尖ります。TTL にランダム幅を持たせるだけでかなり改善します。

1
2
3
4
5

function ttlWithJitter(baseSec: number, jitterSec: number) {
  return baseSec + Math.floor(Math.random() * jitterSec);
}

await redis.set(key, value, { EX: ttlWithJitter(300, 90) });

300 秒固定より、300〜390 秒の分布にすると、同時失効が目に見えて減ります。

6. パターン4: stale-while-revalidate

高可用性が重要な API では、期限切れ直後でも古い値を短時間返しつつ、裏で更新する手法が有効です。

データ構造例:

1
2
3
4
5

{
  "value": {"items": [...]},
  "hardExpireAt": 1700000000,
  "softExpireAt": 1699999700
}

• now < softExpireAt: 新鮮データ
• softExpireAt <= now < hardExpireAt: 古い値を返しつつ非同期更新
• hardExpireAt <= now: 同期再生成

この方式はピーク帯の体感性能を維持しやすく、DB 保護にも強いです。

7. 失敗時フォールバックを設計する

キャッシュ再生成が失敗したときの動作を明確にしておくと、障害時の揺れが減ります。

推奨順序:

1. stale データがあれば返す
2. stale もなければ軽量な代替レスポンス
3. 最後に明示エラー（再試行可能）

「毎回 DB にフォールバック」は危険です。障害時に DB をさらに追い込むため、回路遮断（circuit breaker）とセットで設計すべきです。

8. 監視で見るべき指標

対策の効果はメトリクスで評価します。

• cache hit ratio
• key 単位の miss burst（短時間 miss 件数）
• 再生成処理の同時実行数
• DB クエリ QPS と接続待ち時間

Prometheus を使う場合、以下のようなカウンタを実装すると分析しやすいです。

• cache_requests_total{key_group, result="hit|miss|stale"}
• cache_rebuild_total{key_group, result="ok|error"}
• cache_lock_contention_total{key_group}

9. 導入手順（既存システム向け）

Step 1: 熱いキーを特定

アクセス上位 20 キーを抽出し、まずそこだけ対策します。

Step 2: singleflight + ジッター導入

実装コストが低く、効果が高い組み合わせです。

Step 3: 分散ロック導入

複数インスタンス環境で必須。ロック競合率も計測する。

Step 4: stale-while-revalidate 追加

高トラフィック API へ段階適用。UX と DB 安定性が両立しやすい。

10. よくある失敗例

失敗1: TTL を長くしてごまかす

データ鮮度要件を満たせず、別の問題が出ます。期限延長は応急処置に留める。

失敗2: 分散ロックだけで安心する

ロックが取れない側の待機戦略がないと、スパイクは残ります。待機・再取得・stale 応答まで設計が必要です。

失敗3: miss 率しか見ない

miss が少なくても、特定キーへの burst が強ければ障害は起きます。キーグループ単位で観測してください。

11. 実運用チェックリスト

• 熱いキーを定義し、キーグループで計測している
• singleflight もしくは同等の同時実行制御がある
• TTL にジッターを導入している
• 分散ロックの TTL が処理時間 p99 を上回る
• stale-while-revalidate の返却条件が明確
• 障害時フォールバック（回路遮断含む）がある

まとめ

Redis キャッシュスタンピード対策は、キャッシュを置くことではなく「miss 後の世界を設計する」ことです。

• 同時再生成を止める
• 失効タイミングを分散する
• 期限切れ直後の応答を制御する

この3点を実装すれば、ピーク時の DB 崩壊リスクは大幅に下げられます。まずはアクセス上位キーから段階導入し、メトリクスで効果を確認してください。仕組みとして回り始めると、トラフィック増加に対する耐性が目に見えて改善します。

12. キャッシュキー設計の実務ポイント

スタンピード対策では、アルゴリズム以前にキー設計が重要です。user:123:timeline のような粒度が粗すぎるキーは、人気ユーザーにアクセスが集中したとき一気にホットスポットになります。可能なら page や segment を分割し、巨大レスポンスを小さく分けると miss 時の再生成コストを抑えられます。

また、キーの命名規約をチームで統一しておくと観測しやすくなります。service:domain:resource:variant 形式で揃えれば、メトリクス集計時に key_group を自動分類しやすく、どの領域で burst が起きているかを短時間で判断できます。運用性を上げるキー設計は、性能改善と同じくらい価値があります。

本番運用で厄介なのは、エラーが「たまに」しか出ない障害です。PostgreSQL のデッドロックはその代表で、発生頻度は低くてもビジネス影響が大きいことが多いです。決済や在庫更新で発生すると、リトライが雪だるま式に増え、アプリ全体の遅延を引き起こします。

本記事では、デッドロック発生時に現場でそのまま使える手順を、初動対応・再現・恒久対策の順で整理します。

1. まず理解すべき前提

デッドロックは「どちらかが悪い」ではなく、ロック順序が循環したときに必ず起きる現象です。PostgreSQL は循環を検出すると、どちらか一方のトランザクションを強制中断します。

典型的な症状:

• ERROR: deadlock detected
• API の一部がランダムに 500 を返す
• リトライ実装により DB 負荷が上振れ

ここで重要なのは、単純なタイムアウトと混同しないことです。タイムアウトは待ち時間超過、デッドロックは循環待ちです。対策が違います。

2. 初動でやること（5〜15分）

2-1. エラーログの採取

まず、DB 側ログに詳細を出す設定があるか確認します。

1
2
3

SHOW log_lock_waits;
SHOW deadlock_timeout;
SHOW log_min_error_statement;

推奨設定（本番）:

log_lock_waits = on
deadlock_timeout = '1s'
log_min_error_statement = error

deadlock_timeout を短めにすることで、待ちが長引いたケースの追跡がしやすくなります。

2-2. 現在のロック状況を確認

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

SELECT
  a.pid,
  a.usename,
  a.application_name,
  a.state,
  a.query,
  l.locktype,
  l.mode,
  l.granted,
  a.query_start
FROM pg_stat_activity a
JOIN pg_locks l ON a.pid = l.pid
WHERE a.datname = current_database()
ORDER BY a.query_start;

見るべき点は「長く生きているトランザクション」と「granted = false が連鎖している箇所」です。

3. 再現手順を作る（原因特定の最短ルート）

デッドロックは再現しないと直せません。以下のような単純ケースをまず作ります。

セッション A

1
2
3
4
5

BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
-- ここで待機
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;

セッション B

1
2
3
4
5

BEGIN;
UPDATE accounts SET balance = balance - 50 WHERE id = 2;
-- ここで待機
UPDATE accounts SET balance = balance + 50 WHERE id = 1;
COMMIT;

更新順序が逆なので、容易に循環が起きます。

この再現が取れたら、アプリコード上でも「同じテーブルを複数行更新する順序」が一定かどうかを調べます。

4. 原因の8割は「更新順序の不一致」

多くのプロダクトで見つかるのは次のパターンです。

1. バッチ処理は id ASC で更新
2. API リクエストは受信順で更新
3. 並行処理時に順序が逆転

この場合、解決策は明確で、全経路でロック取得順序を統一します。

例（Node.js / TypeScript）:

1
2
3
4
5

const ids = [fromAccountId, toAccountId].sort((a, b) => a - b);

await tx.query('SELECT id FROM accounts WHERE id = ANY($1) ORDER BY id FOR UPDATE', [ids]);

// その後に更新

FOR UPDATE を先に順序付きで取得することで、アプリ層の揺らぎを DB で吸収できます。

5. 実装レベルの対策パターン

5-1. トランザクションを短くする

デッドロックは「ロック保持時間」が長いほど発生しやすくなります。トランザクション内で外部 API 呼び出しをしていないか確認してください。これは最優先で排除します。

5-2. 失敗時のリトライを制御する

無制限リトライは障害増幅器です。指数バックオフ + 上限回数で制御します。

1
2
3
4
5
6
7
8

for (let attempt = 1; attempt <= 3; attempt++) {
  try {
    return await runTx();
  } catch (e: any) {
    if (!String(e.message).includes('deadlock detected') || attempt === 3) throw e;
    await sleep(50 * 2 ** attempt);
  }
}

5-3. 楽観ロックの導入

更新競合が多い領域では version カラムを使った楽観ロックが有効です。衝突時にアプリで再計算できます。

6. 監視・運用面の改善

恒久対策を完了させるには、再発を検知できる状態を作る必要があります。

推奨メトリクス:

• deadlock 発生回数 / 分
• lock wait 時間 p95
• 失敗リトライ回数
• 長時間トランザクション件数

SQL 例（長時間 tx 検知）:

1
2
3
4
5

SELECT pid, now() - xact_start AS tx_age, query
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
  AND now() - xact_start > interval '30 seconds'
ORDER BY tx_age DESC;

この結果を可視化し、閾値超過で通知するだけでも再発時の初動が速くなります。

7. 障害対応時の意思決定フレーム

デッドロックが継続しているとき、現場は次の順序で判断すると迷いません。

1. 影響範囲（どの API / どの機能か）を確定
2. 失敗処理を一時停止できるか判断（バッチ停止、機能フラグ）
3. ロック順序統一のホットフィックス可否
4. デプロイまでの間、リトライ制御で被害抑制

「根本修正が間に合わない」ケースでも、リトライと負荷制御でユーザー影響を減らせます。

8. よくあるアンチパターン

アンチパターン1: SERIALIZABLE に上げて解決した気になる

隔離レベルを上げるだけでは、設計上の競合は消えません。むしろリトライ増加で負荷が悪化することがあります。

アンチパターン2: SELECT ... FOR UPDATE を乱用する

広範囲ロックは別の待ちを生みます。最小対象だけをロックし、順序を統一することが本質です。

アンチパターン3: アプリログだけ見て DB ログを見ない

デッドロックの循環情報は DB 側ログにしか出ないことが多いです。必ず DB ログを一次情報として扱ってください。

9. すぐ使えるチェックリスト

• deadlock detected の実例ログを保存した
• ロック状況を pg_stat_activity と pg_locks で取得した
• 再現 SQL を作成し、原因パターンを確認した
• 更新順序を全経路で統一した
• リトライ回数とバックオフを制限した
• 監視メトリクスを追加した

まとめ

PostgreSQL デッドロック対策は、魔法の設定値を探す作業ではありません。ポイントは一貫しており、

• ログで事実を取る
• 再現を作る
• ロック順序を統一する

この 3 ステップで大半の問題は改善します。障害対応時は焦って設定を増やすより、まず「どの順序で誰がロックを取ったか」を可視化することが最短ルートです。

10. チーム運用に落とし込むためのルール化

技術対策ができても、運用ルールがないと再発します。特に効果が高いのは「PR テンプレートにロック観点を入れる」ことです。たとえば 複数行更新の順序は統一されているか、トランザクション内で外部I/Oをしていないか をチェック項目にするだけで、設計時点で多くの問題を防げます。

さらに、負荷試験シナリオに競合ケース（同時更新）を追加してください。通常の性能試験は平均応答時間を見るだけで終わりがちですが、デッドロックは並行競合を作らないと検出できません。QA と開発が協調して「再現しにくい障害を再現するテスト」を用意できると、運用品質が一段上がります。

複数リポジトリを運用していると、ほぼ同じ CI 設定を各リポジトリにコピーし続ける状態になりがちです。最初は早く見えますが、半年後には「どこに正解があるのかわからない」状態になります。セキュリティパッチを当てたいだけなのに 20 リポジトリを横断修正し、1つだけ取りこぼして監査で指摘される、というのは珍しくありません。

この問題に効くのが GitHub Actions の workflow_call を使った再利用ワークフローです。ただし、単に共通化するだけでは逆に運用事故が増えることがあります。重要なのは、共通化の粒度、権限境界、変更リリース方法を最初に設計することです。

本記事では、実運用で詰まりやすいポイントを中心に、導入から定着までを具体的に解説します。

1. 再利用ワークフローの基本方針

まず押さえるべき方針は次の 3 つです。

1. 再利用ワークフローは「プラットフォーム製品」として扱う
2. 呼び出し側（各アプリ repo）は薄く保つ
3. 破壊的変更はバージョンを切って段階移行する

「共通化＝1ファイルに全部詰め込む」ではありません。lint, test, build, deploy を1個にまとめると、対象外プロジェクトまで影響します。まずは小さく分割し、必要なものだけ組み合わせられる構造にします。

2. 推奨ディレクトリ構成

共通ワークフローを専用 repo に分離しておくと、監査や変更履歴の管理が容易になります。

1
2
3
4
5
6
7
8
9

org-ci-workflows/
  .github/workflows/
    ci-node.yml
    ci-python.yml
    security-scan.yml
    release-tag.yml
  docs/
    onboarding.md
    migration-checklist.md

呼び出し側は以下のように最小化します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

name: ci
on:
  pull_request:
  push:
    branches: [main]

jobs:
  node-ci:
    uses: your-org/org-ci-workflows/.github/workflows/ci-node.yml@v1
    with:
      node-version: "22"
      run-e2e: false
    secrets: inherit

この形の利点は、アプリチームが理解すべき YAML が減ることです。CI の標準知識が全員に伝播し、レビューも速くなります。

3. 実務で効く入力設計（inputs）

inputs は API 設計だと考えるべきです。曖昧な真偽値が増えると、挙動が読めなくなります。

悪い例

• enable_special_mode: true
• quick: true

良い例

• test-scope: unit|integration|full
• build-target: web|api|worker
• upload-artifact: true|false

再利用ワークフロー側では型とデフォルト値を明示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

on:
  workflow_call:
    inputs:
      test-scope:
        required: false
        type: string
        default: "unit"
      upload-artifact:
        required: false
        type: boolean
        default: true

入力名を自然言語に寄せすぎないのがコツです。将来の運用者が見て意味がぶれない命名に寄せます。

4. セキュリティ設計：permissions を最小化する

再利用ワークフローの導入後に増える事故が「権限過剰」です。permissions: write-all を残したまま運用すると、意図しないトークン利用で供給網リスクが高まります。

推奨はジョブ単位での最小権限化です。

1
2
3
4

permissions:
  contents: read
  pull-requests: write
  actions: read

デプロイやタグ作成など書き込みが必要な処理だけ、専用ジョブに分離して contents: write を付与します。CI と CD の境界を分けるだけで、攻撃面積をかなり削減できます。

5. キャッシュ設計でハマらないための実践

Actions の高速化でよく使う actions/cache は、キー設計を誤ると逆効果になります。

• キーが粗い: 依存不整合で不安定化
• キーが細かすぎる: キャッシュヒット率低下

Node の例:

1
2
3
4
5
6
7

- uses: actions/setup-node@v4
  with:
    node-version: ${{ inputs.node-version }}
    cache: npm

- run: npm ci
- run: npm test

まずは setup-* の組み込みキャッシュを優先し、複雑な手動キャッシュは必要になってから追加する方が安全です。

6. 導入手順（3週間での現実的移行）

Week 1: 現状分析

1. 全 repo の workflow を収集
2. 共通ジョブを抽出（lint/test/build/security）
3. 失敗率の高い処理を特定

Week 2: 共通 repo 構築

1. org-ci-workflows を作成
2. 2〜3 種類の再利用ワークフローを作る
3. テンプレート repo で先行検証

Week 3: 段階移行

1. 低リスク repo から順次移行
2. 失敗ログを収集し API（inputs）を微調整
3. v1 タグを固定し、全体展開

重要なのは、一気に全 repo を置き換えないことです。先行導入で「どの入力が不足しているか」を把握し、後続 repo の移行コストを下げます。

7. 変更管理：main 直参照を禁止する

呼び出し側で @main を使うと、共通 repo の更新が即時反映されます。これは便利ですが、本番では危険です。事故時に「いつ壊れたか」が追跡しづらくなります。

実運用では次を推奨します。

• 呼び出しは @v1 などのタグ固定
• 破壊的変更は v2 を新規発行
• 重大修正のみ v1.x に backport

さらに、変更通知テンプレートを用意しておくと移行が速くなります。

1
2
3
4
5
6

[CI Workflow Update]
- Target: ci-node.yml
- Change: npm audit step added
- Impact: build time +20-40 sec
- Action Required: none (v1.3.0 auto pickup)
- Rollback: use v1.2.4

8. 監視指標（導入効果を数字で見る）

再利用ワークフローを入れたら、以下を最低でも計測します。

• CI 平均実行時間
• PR あたり失敗回数
• ワークフロー設定変更に伴う障害件数
• セキュリティ警告検出率

導入後 1 か月で、設定差分の削減 と 障害切り分け時間の短縮 が見えてくるはずです。数字が出ない場合は、共通化の粒度が粗すぎる可能性があります。

9. よくある失敗と対策

失敗1: 共通化しすぎて柔軟性が消える

対策: 80%共通 + 20%ローカル上書きの構造にする。例外を許容する。

失敗2: 例外入力が増えて API が壊れる

対策: 四半期ごとに inputs を棚卸し。未使用入力を削除し、破壊的変更はメジャーバージョンへ。

失敗3: Platform Team しか触れない

対策: docs/onboarding.md を整備し、アプリチームが PR で改善できる運用にする。

10. そのまま使える導入チェックリスト

• 共通 repo を作成し、責任者を明確化した
• workflow_call の入力仕様を文書化した
• permissions を最小権限に設定した
• 呼び出し側でタグ固定（@v1）を徹底した
• 先行 repo で 1 週間運用検証した
• ロールバック手順を README に記載した

まとめ

GitHub Actions の再利用ワークフローは、単なる YAML 共通化ではなく、組織の開発基盤を製品として運用する取り組みです。導入の成否は、技術よりも運用設計に左右されます。

• 入力仕様を API として設計する
• 権限を最小化し事故半径を縮小する
• バージョン固定で変更を可観測にする

この3点を守るだけで、CI/CD は「壊れやすい魔法」から「改善可能な仕組み」に変わります。まずは 1 つの再利用ワークフローから始め、3 週間で小さく成功を作るのが最短ルートです。

MCP（Model Context Protocol）は、LLM と外部ツールを接続する強力な仕組みです。便利な一方で、本番運用では「権限の過剰付与」「監査不能」「障害時の暴走」が起きやすく、設計を誤ると一気にリスクが跳ね上がります。

本記事では、MCP サーバーを業務利用する前提で、安全性・可観測性・運用性を満たす設計パターンをまとめます。PoC から本番へ上げる際のチェックリストとして使える構成にしています。

1. MCP本番運用で先に決めるべきこと

最初に決めるべきは、技術スタックではなく「権限境界」です。

• どのエージェントが、どのツールを使えるか
• 書き込み系操作（作成・更新・削除）の承認方式
• 外部送信（メール、投稿、通知）の監査ルール
• 失敗時の停止条件（fail-open か fail-closed か）

ここを決めずに実装を始めると、あとから制約を入れられず、結果として運用停止になります。

2. 推奨アーキテクチャ：Control Plane と Tool Plane の分離