本番デプロイ後の後処理記録 — ドキュメント更新・IaC設計の修正・チームへの引き継ぎ

前回の記事では、Canary SG の作成から ECS SG へのルール追加、Pulumi デプロイまでの当日作業を書きました。

今回はその翌日以降の話です。「本番デプロイが完了した後」の後処理を記録しておきます。

デプロイ当日の記録を書いて満足しがちですが、実際にはその後にやることがけっこうあります。ドキュメントの状態更新、方針変更の記録、チームへのコミュニケーション設計。地味ですが、残しておかないと数週間後に「あれどうなったっけ」が起きます。

作業の全体像

今回やったこと:

順番に書いていきます。

1. エンドポイント追跡ドキュメントの状態更新

まず機械的な作業から。監視エンドポイントの進捗を管理しているドキュメントがあり、各エンドポイントに「設定済み（dev）」「確認済み」「設定済み（prod）」といったステータスを持たせていました。

本番デプロイが完了したので、全エンドポイントを 設定済み（prod） に更新する作業です。

<!-- 変更前 -->
- **ステータス:** 設定済み（dev）

<!-- 変更後 -->
- **ステータス:** 設定済み（prod）

これは単純な一括更新なのですが、Claude Code に読み込ませてフェーズごとに確認しながら進めました。「確認済み」と「設定済み（dev）」が混在していて、どちらも最終的には 設定済み（prod） になるべき状態だったので、差分を見ながら一件ずつ確認できたのが良かったです。

2. IaC設計方針の変更をドキュメントに残す

ここが今回いちばん「やっておいてよかった」と思う作業です。

経緯

前回の記事でも少し触れましたが、当初の設計では SG（セキュリティグループ）も Pulumi で管理する予定でした。ところが実際に動かしてみると、Terraform 側のデプロイが走ったタイミングで Pulumi が設定した SG ルールが剥がれてしまい、監視疎通ができなくなるという問題が発生しました。

原因は単純で、Terraform と Pulumi が同じリソースを「自分のもの」と認識して競合していました。Terraform のデプロイが走ると、Terraform の定義が正とみなされ、Pulumi が追加した SG ルールが消える、という動きです。

対応策として、SG は既存の Terraform 管理に寄せ、監視リソース（Canary / Alarm / SNS）は引き続き Pulumi で管理するという形に方針を変更しました。責務の境界を明確にすることで競合を回避しています。

[Pulumi 管理]
  ├─ IAM Role / Policy  : Canary 実行用ロール
  ├─ CloudWatch Synthetics Canary × N
  ├─ CloudWatch Alarm × N
  ├─ SNS Topic
  └─ SNS Subscription

[Terraform 管理（既存の仕組み）]
  └─ Security Group / Rules  : Canary から監視対象への疎通許可

ドキュメントの更新方針：打ち消し線で経緯を残す

変更箇所をどう記録するかで少し迷いました。単純に「古い記述を消して新しい記述に差し替える」という方法もあります。でも今回は打ち消し線で古い記述を残しつつ、新しい方針を追記する形を選びました。

<!-- 変更前 -->
AWS リソースの構築は Pulumi（IaC）で行う — 全社的に採用が進められている方針に準拠する。
手作業での設定は技術的負債となるため、Canary / Alarms / SNS 等の監視リソースは
すべてコードで管理する

<!-- 変更後 -->
~~AWS リソースの構築は Pulumi（IaC）で行う — 全社的に採用が進められている方針に準拠する。
手作業での設定は技術的負債となるため、Canary / Alarms / SNS 等の監視リソースは
すべてコードで管理する~~

AWS リソースの構築は Pulumi（IaC）と Terraform を併用する — Canary / Alarms / SNS 等の
監視リソースは Pulumi で管理する。ただしセキュリティグループ（SG）は既存の Terraform 管理の
仕組みに寄せる。理由: SG を Pulumi で管理していたところ、Terraform 側のデプロイが走った際に
Pulumi で設定した SG ルールが剥がれ、監視疎通ができなくなる事象が発生したため。
SG は Terraform、その他の監視リソースは Pulumi、と責務を明確に分離する

なぜ消さないかというと、「なぜこうなったのか」の経緯を残したかったからです。新しい方針だけが書かれていると、後から読んだ人（あるいは数ヶ月後の自分）が「なんで Pulumi と Terraform を両方使ってるんだっけ」と疑問に思ったとき、答えが見当たらない。打ち消し線を使うことで「もともとはこうする予定だったが、こういう問題があって変えた」という流れが一目でわかります。

Terraform と Pulumi の競合：何が起きていたのか

少し補足しておきます。IaC ツールを複数混在させると、同じリソースを「どちらが管理しているか」の衝突が起きる可能性があります。

今回の場合、Pulumi で SG ルールを追加したとき、Terraform 側の state にはそのルールが存在しない状態になっていました。そのため Terraform が terraform apply を実行すると「自分の定義にないルールが存在する → 削除する」という動きになってしまいました。

対処方法としては大きく二つあります。

1. どちらか一方に寄せる

今回採用したアプローチ。SG は Terraform 管理に完全に寄せ、Pulumi は SG を触らない。シンプルで競合が起きない。

2. Terraform 側で lifecycle { ignore_changes } を使う

Terraform に「このリソースの特定フィールドは変更を無視する」と伝える方法です。ただし設定が複雑になりやすく、意図しないリソース変更を見逃すリスクもあります。

今回はすでに稼働中の Terraform 管理の仕組みがあったので、それに乗る形が最もリスクが低い判断でした。

3. 開発チームへの引き継ぎコミュニケーション設計

本番デプロイが完了した段階で、開発チームに確認してもらいたい事項が残っていました。

最初、Claude Code にドラフトを作ってもらった連絡文がこんな感じでした。

（開発チームの担当者）さん

お疲れ様です。外形監視の本番デプロイが完了しました。

つきましては、3 月の打ち合わせでアクションアイテムとして挙がっていた「監視間隔の検討」と、運用フェーズに入るための「アラート閾値の方針」について…（中略）

1. 各エンドポイントの監視間隔（dev / prod）
- 現在は仮設定として全エンドポイント rate(30 minutes) で稼働中
- 監視間隔を短くするほど障害検知は早くなりますが、その分コストが増加します
- dev / prod それぞれで、どの粒度で検知できれば運用上十分か方針をご共有ください
2. アラート閾値・発火条件の方針
- 現在は上記の仮決めに沿って設定中
…（続く）

長い。これを読むのやだと思ったので、MTG で一度話した方が早いという判断に切り替えました。最終的に送った連絡文はこんな感じです。

（担当者）さん

お疲れ様です。外形監視、本番までのデプロイが完了しました。ご対応ありがとうございました。

運用フェーズに入るにあたり、以下 2 点について方針を握りたく、共有カレンダーに MTG を登録しました。ご確認をお願いします。

- 監視間隔の最終決定（3 月のアクションアイテムの件）
- アラート閾値・発火条件の方針（仮決め内容の確定 + 今後の調整方針）

所要時間は 15〜30 分程度を想定しています。

ご都合が合わない場合はお知らせください、調整します。よろしくお願いいたします。

ポイントは「共有カレンダーに先に登録してから連絡する」という順番にしたことです。候補日を聞いて、相手が答えて、そこからまた調整して、という往復を省略できます。

また、「詳細は MTG で話しましょう」という形にすることで、連絡文の中で全てを説明しようとする必要がなくなりました。選択肢の整理（コスト試算の比較表など）は MTG 資料として準備しておく方が、読む側も検討しやすいです。

振り返り

デプロイ当日の記録を前回書きましたが、正直なところ後処理の方が時間がかかった感覚があります。

ドキュメントの状態更新を先に。まずステータスを更新して「完了した」という事実を確定させる。これが先送りになると「あのエンドポイントってもう prod にデプロイしたんだっけ」という曖昧さが生まれます。

設計変更は消さずに経緯を残す。打ち消し線を使って「もともとこうする予定だったが、こういう理由で変えた」というストーリーをドキュメントに持たせる。Git の commit history でも追えますが、ドキュメント内に文脈として書いてある方が圧倒的に読みやすいです。

コミュニケーションの設計は「最小往復」を意識する。選択肢を文章で渡すより、MTG で直接話す方が早いケースは多い。カレンダーを先に押さえてから連絡する、というのも小さいですが効果のある工夫でした。

本番デプロイが完了してもしばらくは「運用開始直後」の状態が続きます。監視間隔や閾値の最終確定、チームへの引き継ぎ、ドキュメントのメンテナンス。今回の記録がその参考になれば。

参考

ドキュメントの書き方や残し方を体系的に学びたい方には、以下が参考になります。

設計変更の経緯を記録するアプローチ（ADR など）について深掘りしたい場合は、こちらも参考になります。

エンジニア間・チーム間のコミュニケーション設計を学びたい方には以下の書籍がおすすめです。