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 に落とし込む

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

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

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 ステップを運用手順書の先頭に置くだけで、一次対応の速度と品質が安定します。特に「誰が見ても同じ順序で確認できる」状態を作ることが、夜間障害時の認知負荷を大きく下げます。

Kubernetes で障害が起きたとき、技術力より先に問われるのは「順序」です。順序が崩れると、正しいコマンドを打っていても復旧が遅れます。逆に、判断フレームが決まっていれば、難しい障害でも被害を最小化できます。

本記事では、実運用で使える障害対応ランブックを、初動 15 分・復旧 60 分を目安に具体化します。対象は EKS/GKE/AKS を含む一般的な Kubernetes 本番環境です。

1. 最初の5分：人と情報の交通整理

まずやるべきは技術調査ではなく、交通整理です。

• インシデントの指揮者（IC）を1人決める
• ログ担当、メトリクス担当、アプリ担当を分ける
• Slack/Discord の専用チャンネルを作る
• 5分ごとの時系列ログ（タイムライン）を残す

この段階で「誰が何を見ているか」が曖昧だと、同じ調査を3人で繰り返し、誰も復旧判断をしない状態になります。ICは手を動かさず、意思決定に集中するのが基本です。

2. 5〜15分：影響範囲の特定

次に「どのユーザーに、どの機能で、何%の影響があるか」を確定します。

2-1. まず全体の健康状態

1
2
3

kubectl get nodes
kubectl get pods -A --field-selector=status.phase!=Running
kubectl get events -A --sort-by=.lastTimestamp | tail -n 50

見るポイント:

• Node が NotReady になっていないか
• 特定 namespace だけで CrashLoopBackOff が増えていないか
• 直近イベントに FailedScheduling や Back-off restarting failed container がないか

2-2. SLO/SLIから影響を数値化

「遅い気がする」ではなく、以下を数値で押さえます。

• エラー率（5xx / total）
• p95 / p99 レイテンシ
• リクエスト成功率
• 影響時間（何時何分から）

復旧優先順位は「売上影響」「決済影響」「ログイン影響」で並べると迷いにくいです。

3. 典型障害ごとの切り分けテンプレート

3-1. Podが再起動ループする

1
2

kubectl describe pod <pod-name> -n <ns>
kubectl logs <pod-name> -n <ns> --previous

判断軸:

1. アプリ起因（例: マイグレーション失敗、環境変数不足）
2. リソース起因（OOMKill, CPU スロットリング）
3. 依存先起因（DB接続失敗、外部APIタイムアウト）

OOMKill が見えたら、即座に requests/limits の見直し候補です。緊急回避として replicas を増やすより、まずメモリリークや一時的負荷スパイクの切り分けを優先します。

3-2. Podは生きているのに503が増える

1
2
3

kubectl get endpoints -n <ns>
kubectl describe svc <service> -n <ns>
kubectl get deploy <deploy> -n <ns> -o yaml | grep -n "readinessProbe\|livenessProbe"

よくある原因:

• readinessProbe が厳しすぎて endpoint から外れ続ける
• 依存先劣化で app は起動しているが実処理が詰まる
• HPA は増えているが、DB 接続プールが上限で飽和

このケースでは「Pod数が多いのにエラーが減らない」ので、アプリ外（DB、キュー、外部API）を疑うのが早いです。

3-3. 特定ノードでのみ障害

1
2
3

kubectl describe node <node>
kubectl top node
kubectl get pods -A -o wide | grep <node>

ノード隔離が必要なら、以下で新規スケジュールを止めます。

1
2

kubectl cordon <node>
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

drain は影響が大きい操作なので、IC の明示承認を挟むのが安全です。

4. 復旧アクションの優先順位（実務向け）

障害中は「恒久対策」を始めないこと。順番は固定します。

1. 被害抑制: feature flag で重い機能を止める
2. 暫定復旧: 直前の安定リビジョンへロールバック
3. 性能確保: replicas/HPA 一時調整、キュー消化速度調整
4. 恒久対策: 根本修正は障害収束後にPRで実施

4-1. ロールバックの型を決めておく

1
2
3

kubectl rollout history deployment/<deploy> -n <ns>
kubectl rollout undo deployment/<deploy> -n <ns> --to-revision=<rev>
kubectl rollout status deployment/<deploy> -n <ns>

ポイントは「戻す判断に迷わない基準」を事前に定義しておくことです。

• 5分間で 5xx > 2% 継続
• p95 が通常比 2倍超を 10分継続
• ログイン/決済失敗が監視閾値超え

基準がないと、誰も責任を取りたくなくて引き延ばしになります。

5. 事後対応（Postmortem）で必ず残すべきもの

障害対応の価値は、復旧速度だけではありません。再発率を下げて初めて完了です。

最低限残す項目:

• 発生時刻、検知時刻、復旧時刻
• ユーザー影響（件数、売上影響）
• 技術的原因（直接原因 / 背景要因）
• うまくいった対応、失敗した判断
• 再発防止のアクション（担当者・期限付き）

5-1. アクションを「監視」に落とす

「次は気をつける」は効果ゼロです。必ず機械化します。

例:

• CrashLoopBackOff > N件 を5分継続で即アラート
• DB接続待ち時間の p95 をダッシュボード化
• リリース直後30分は自動で高感度監視モード

6. そのまま使える障害対応チェックリスト

初動チェック（0〜15分）

• IC決定、連絡チャンネル作成
• 影響範囲（機能・ユーザー・売上）を数値化
• Node / Pod / Event の全体確認
• 直近デプロイ有無の確認

復旧チェック（15〜60分）

• 被害抑制（feature flag / トラフィック制御）
• ロールバック判断基準を満たすか確認
• 復旧後 15 分の再監視（再発確認）
• ユーザー向けステータス更新

事後チェック（24時間以内）

• Postmortem 作成
• 再発防止チケット発行
• 監視ルール・Runbook 更新

まとめ

Kubernetes 障害対応は、個人技で勝つゲームではありません。誰でも同じ順序で動ける運用設計が最も効きます。特に「初動の交通整理」「ロールバック基準の明文化」「事後の監視自動化」の3点は、復旧時間と再発率を同時に改善します。

次の障害が来たときに迷わないよう、今日のうちにこのランブックを自チーム用に1ページ化しておくことを強くおすすめします。

7. 障害を早く終わらせるための役割分担テンプレート

実際の現場では、技術調査よりコミュニケーションで詰まることが多いです。そこで、あらかじめ役割を固定しておくと復旧が速くなります。

• IC（Incident Commander）: 優先順位決定、Go/No-Go判断、対外連絡承認
• Ops Lead: クラスタ状態確認、ロールバック実行、インフラ変更の安全確認
• App Lead: アプリログ解析、機能フラグ切り替え、暫定パッチ判断
• Comms: 社内・顧客向けステータス更新、問い合わせ窓口統一

この分担があると、「調査担当が勝手に危険操作を実施する」「連絡が多重化して混乱する」といった二次被害を防げます。

8. よくあるアンチパターンと回避策

アンチパターン1: まず再デプロイしてしまう

原因が不明なまま再デプロイすると、証拠ログを失い再現不能になります。最低限 events と previous logs を保存してから操作します。

アンチパターン2: 「たぶん直った」でクローズする

復旧後 15 分の監視を省くと、同じ障害が波状的に再発します。復旧宣言は「指標が閾値内で安定した」ことを条件にします。

アンチパターン3: 障害後の改善が担当者依存

改善をドキュメント化せず担当者の記憶に任せると、同じ夜間障害を繰り返します。Runbook への反映までをインシデント完了条件に含めるべきです。

FastAPI は開発速度が高く、PoC から本番まで一気に進めやすいフレームワークです。しかし、早く作れることと安全に運用できることは別問題です。実際の障害は、コードの正しさよりも運用の隙から発生します。

本記事では、FastAPI を本番で安心して運用するためのハードニング手順を、実装可能な形でまとめます。対象は「すでにAPIが動いているが、運用強度を上げたい」チームです。

1. 入口防御：TLS、ヘッダ、レート制限

TLS終端とForwardedヘッダ

ロードバランサ配下で動かす場合、X-Forwarded-For と X-Forwarded-Proto の扱いを明確にします。誤るとクライアントIPが取れず、監査も制限も機能しません。

1
2
3
4
5

from fastapi import FastAPI
from starlette.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(TrustedHostMiddleware, allowed_hosts=["api.example.com", "*.example.com"])

allowed_hosts をワイルドにしすぎると Host Header Injection の温床になります。

セキュリティヘッダ

最低限次を返します。

• Strict-Transport-Security
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy

APIでも無関係ではありません。管理画面やドキュメントUIを守る意味があります。

レート制限

ブルートフォースと突発負荷に備え、IPまたはAPIキー単位でレート制限を設定します。

• 認証系: 5 req/min
• 通常API: 60 req/min
• 高負荷検索: 20 req/min

Redis バックエンド方式にして、アプリ再起動でカウンタが失われないようにします。

2. 認証・認可の落とし穴を塞ぐ

JWT検証の必須項目

exp だけ見て通す実装は危険です。少なくとも次を検証します。

• iss（発行者）
• aud（想定利用先）
• nbf（有効開始）
• kid に基づく鍵ローテーション

認可は「エンドポイント単位」ではなく「リソース単位」

/users/{id} のアクセス時に、path パラメータの id とトークンの主体を照合しない事故は頻発します。FastAPI の dependency で統一的に実施します。

1
2
3

def authorize_user_resource(current_user, target_user_id: str):
    if not (current_user.is_admin or current_user.user_id == target_user_id):
        raise HTTPException(status_code=403, detail="forbidden")

3. 入出力の安全化：Pydanticだけでは不十分

Pydantic は型安全に強いですが、ビジネス制約は別で実装が必要です。

• 文字列長上限
• 許可文字セット
• SQL/NoSQLインジェクションの危険文字
• HTML/Markdown サニタイズ

特に検索APIやエクスポートAPIは、クエリ文字列が巨大化しやすく DoS の入口になります。max_length を必ず定義してください。

4. 性能ハードニング：ワーカ・DB・タイムアウト

Uvicorn/Gunicorn 構成

CPUコア数に応じて worker を決めます。目安は workers = 2 * core + 1 から開始し、実測で調整。

1

gunicorn app.main:app -k uvicorn.workers.UvicornWorker --workers 5 --bind 0.0.0.0:8000 --timeout 30

DB接続プール

asyncpg や SQLAlchemy async engine のプール上限を設定しないと、ピーク時に接続飽和します。

• min: 5
• max: 30（DB性能と相談）
• pool timeout: 5s

タイムアウト戦略

上流・下流の timeout を揃えないと、雪崩障害が発生します。

• 外部API呼び出し: connect 1s / read 3s
• DBクエリ: statement timeout 2s（重処理は別キュー）
• API全体: 10s で fail fast

5. 例外設計と障害時の挙動

本番障害では「500が出ること」より「500の意味が不明」なことが問題です。エラーレスポンス形式を固定し、trace_id を必ず返します。

1
2
3
4
5
6
7

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "unexpected error",
    "trace_id": "8f3d..."
  }
}

内部例外はそのまま返さず、ログ側に stack trace を記録。ユーザーには安全な文言のみ返却します。

6. 可観測性：ログ・メトリクス・トレース

構造化ログ

JSON ログを標準化し、次を必須項目にします。

• timestamp
• level
• service
• trace_id
• user_id（可能なら）
• endpoint
• latency_ms

メトリクス

最低限:

• RPS
• エラー率（4xx/5xx）
• P50/P95/P99 latency
• DB遅延
• 外部API失敗率

トレース

OpenTelemetry で endpoint → service → DB をつなぐと、障害切り分けが劇的に速くなります。

7. デプロイ戦略：壊さずに出す

推奨は Blue/Green か Canary。FastAPI 単体の問題より、周辺設定差異が事故の原因になります。

リリース前チェックリスト:

1. DB migration の後方互換性
2. 依存ライブラリ脆弱性スキャン
3. load test（代表3API）
4. rollback 手順の実行確認
5. feature flag で段階有効化

8. 運用で効くインシデント訓練

月1回、次の擬似障害を実施すると運用強度が上がります。

• DB遅延 3秒化
• 外部API 30% 失敗
• メモリリーク発生
• JWT鍵ローテーション失敗

重要なのは、復旧時間だけでなく「誰が何を見て判断したか」を記録することです。Runbook の更新まで含めて初めて訓練が完結します。

9. すぐ使える最小ハードニングチェック

• Host ヘッダ制限
• JWT iss/aud/exp/nbf 検証
• 全エンドポイントに認可 dependency
• 外部API timeout/retry/circuit breaker
• JSON 構造化ログ + trace_id
• P95 latency 監視とアラート
• rollback 手順が5分で実行可能

この 7 項目が揃うだけで、障害時の被害規模は大きく下がります。

まとめ

FastAPI は高速開発の武器ですが、本番運用では「早く作る」より「安全に壊れる」設計が重要です。入口防御、認証認可、性能制御、観測性、リリース運用をセットで整備すれば、チームは安心して機能開発に集中できます。

もし何から始めるか迷うなら、まずは trace_id 付きの構造化ログと timeout 統一から着手してください。最小の投資で、運用の見通しが一気に良くなります。

10. セキュアな開発フローを維持するためのCI設定

本番ハードニングはコードだけでなく、CI フローで担保する必要があります。推奨するジョブは次の通りです。

1. 依存脆弱性スキャン（pip-audit / osv-scanner）
2. SAST（bandit など）
3. 型チェック（mypy）
4. 負荷テストのスモーク（k6）
5. OpenAPI 差分チェック（破壊的変更検出）

特に OpenAPI 差分チェックは有効です。意図しないレスポンス変更を早期に検知でき、フロントエンド障害を防げます。

11. バックアップと復旧を設計に含める

API 運用は「壊れない」ではなく「壊れても戻せる」が現実的です。最低限次を決めておきます。

• DB バックアップ頻度（例: 15分ごと増分、日次フル）
• 復旧目標（RTO/RPO）
• 復旧手順の担当と実行順

復旧訓練をしていないバックアップは、存在しないのと同じです。四半期に一度は検証環境でリストア演習を行ってください。

12. 監査対応を見据えたログ保全

B2B API では監査要件が後から増えることが多いです。最初から次を満たす設計にしておくと後で困りません。

• 監査ログとアプリログを分離
• 重要操作（権限変更、削除、課金操作）の証跡保存
• ログ保持期間の明確化（例: 180日）
• 改ざん検知（WORM ストレージや署名）

「誰が、いつ、何をしたか」を追えることは、障害解析だけでなく法務リスク低減にも直結します。

最終まとめ

FastAPI の本番運用は、フレームワーク知識だけでは足りません。セキュリティ、性能、可観測性、復旧性を一体で設計することが重要です。チェックリスト化し、CI と運用手順へ落とし込むことで、安定した開発速度を維持できます。

Kubernetes を導入した直後は「自動で効率化される」と期待されがちですが、実際には逆です。適切な運用ルールがないと、クラウド請求は静かに膨らみ続けます。

典型例は次の通りです。

• リクエスト/リミットが過大でノードが常時スカスカ
• 夜間トラフィック減少時も同じ台数を維持
• 開発環境が週末ずっと起動
• HPA が CPU しか見ておらず、キュー滞留を無視
• 過剰なストレージクラス（IOPS課金）を全環境で使用

本記事では、FinOps の考え方を用いて、Kubernetesコストを「見える化→改善→定着」の順に進める方法を解説します。

コスト削減の前に定義すべき指標

削減施策が失敗する理由は、目標が「安くする」しかないからです。最低でも次の 4 指標を定義します。

1. Unit Cost: 1リクエストあたりコスト / 1ジョブあたりコスト
2. Utilization: CPU・Memoryの実効使用率
3. Reliability: SLO 達成率（削減で品質を落とさない）
4. Waste Ratio: 予約/実使用の差分率

この4つを同時に追うと、単なるコストカットでなく「健全な最適化」になります。

ステップ1：可視化基盤を整える

1-1. Kubecost または OpenCost の導入

EKS/GKE/AKS いずれでも、namespace / deployment / label 単位で費用を把握できる状態にします。重要なのは team, service, env ラベルを強制することです。

推奨ラベル:

• cost-center
• owner
• environment（prod/stg/dev）
• criticality

ラベルがないと請求分析ができず、改善責任が曖昧になります。

1-2. 観測ダッシュボード

最初のダッシュボードは次を必須にします。

• Namespace別コスト（当日/前日比）
• Pod別 request/usage ギャップ
• ノード空き率（CPU、Memory）
• 時間帯別トラフィックとレプリカ数

ここまでで「どこが高いか」は見えます。次は「なぜ高いか」を潰します。

ステップ2：最も効果が高い改善施策

2-1. Right Sizing（最優先）

多くの環境で最大効果が出るのは request/limit の見直しです。VPA recommendation を参考に、まずは read-only で 2 週間観測します。

例:

• 現在: requests.cpu=1000m, 実使用 P95 が 220m
• 改善後: requests.cpu=300m

この1変更だけでノード数が 20〜35% 下がるケースがあります。

2-2. Cluster Autoscaler / Karpenter 最適化

オートスケーラーを入れていても、設定不備で縮退しないことが多いです。次をチェックします。

• scale down unneeded time が長すぎないか
• pod disruption budget が硬すぎないか
• daemonset が過剰にリソースを固定していないか

Karpenter なら Spot + On-Demand の比率制御を導入し、重要ワークロードのみ On-Demand 固定にします。

2-3. ワークロードの時間制御

開発・検証環境はスケジュール停止が有効です。平日 9:00-20:00 だけ稼働し、夜間/休日は scale to zero。

1
2

# 例: CronJobで夜間停止
kubectl scale deployment api-staging --replicas=0 -n staging

単純ですが、月額で大きく効きます。

2-4. HPA指標の改善

CPU のみでスケールすると、I/O 待ちやキュー詰まりを見逃します。Prometheus Adapter を使い、次の指標を追加します。

• queue length
• request latency P95
• in-flight request

結果として「必要な時だけ増やす」が実現し、過剰常時稼働を減らせます。

ステップ3：ストレージ/ネットワークの見直し

ストレージ

高IOPSディスクを全環境に使うのは典型的な浪費です。ワークロード特性でクラス分離します。

• DB本番: 高IOPS
• バッチ/開発: 標準クラス

スナップショット保持期間も要確認です。無制限保持は請求を圧迫します。

ネットワーク

クロスAZ通信量は見落とされがちです。チャットAPIや内部gRPCが高頻度だと、トラフィック課金が無視できません。依存サービスを同一AZに寄せる設計を検討します。

ガードレールを仕組み化する

最適化は一度で終わりません。再び膨らむので、CI/CD に制約を組み込みます。

• OPA/Gatekeeper で「requests未設定」を拒否
• ラベル欠落 (owner, cost-center) の manifest を reject
• 予算超過 namespace の新規デプロイを警告

さらに、週次で「Top Waste 10」を自動配信し、チームごとに改善オーナーを固定します。

実例：3か月で 32% 削減した手順

ある SaaS 環境（5クラスタ）で実施した順序は次の通りです。

1. 2週間の使用実績を収集
2. 上位20 deployment の rightsizing
3. staging/dev の時間停止
4. Spot 比率を 15% → 45% へ引き上げ
5. 高コストPVの棚卸し

結果:

• 月次コスト: -32%
• P95 レイテンシ: ほぼ維持
• インシデント増加: なし

ポイントは、SLO を維持しながら段階実施したことです。

よくある反論への回答

Q. 削減すると障害が増えるのでは？ A. いきなり下げると危険です。P95実績を基準に 10〜15% ずつ下げ、SLO と同時監視すれば安全に進められます。

Q. チームが協力しない A. コストを「共通責任」にすると進みません。namespaceごとに owner を明示し、改善期限を決めると動きます。

Q. どこから始めるべき？ A. Right Sizing と夜間停止です。最短で効果が出ます。

まとめ

Kubernetes コスト最適化は、節約テクニックの寄せ集めではありません。計測、改善、運用ガードレールをセットで回す FinOps プロセスです。

まずは「誰の、どのワークロードが、なぜ高いか」を可視化し、Right Sizing から着手してください。性能を落とさずにコストを下げる道筋は、思っているより現実的です。

実装テンプレート：無駄を自動検出する

可視化だけだと改善は進みません。週次で自動的に「無駄候補」を抽出してチームへ配信する仕組みを入れると、改善が継続します。

抽出ルール例:

• 7日平均で CPU 使用率 < 15% かつ request > 500m
• 夜間（0:00-6:00）にトラフィックほぼゼロなのに replicas > 1
• メモリ使用率 P95 < 40% が 14 日継続

このルールで候補を Slack/Discord に自動投稿し、オーナーと期限を付けるだけで改善率が上がります。

具体的なYAML見直し例

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

resources:
  requests:
    cpu: "250m"
    memory: "512Mi"
  limits:
    cpu: "500m"
    memory: "1Gi"

autoscaling:
  minReplicas: 1
  maxReplicas: 8
  targetCPUUtilizationPercentage: 65

ポイントは「requests を現実に寄せる」「limits を安全マージンに置く」「HPA で不足分だけ増やす」の3点です。

ガバナンス：コストを技術負債化させない

削減施策は放置すると必ず戻ります。そこで、リリースゲートに FinOps 観点を追加します。

• 新規サービスは cost label 必須
• request 未設定の Pod はデプロイ拒否
• 予算超過時は自動で注意喚起

さらに月次レビューで「削減額」だけでなく「SLO維持率」も一緒に報告することで、コスト最適化が品質改善と対立しない文化を作れます。

まとめ（実行順の再確認）

1. まず可視化（誰が何にいくら使っているか）
2. 次に Right Sizing と時間停止
3. 最後にガードレールをCI/CDに組み込む

この順番を守れば、短期の削減成果と中長期の運用安定を両立できます。