レガシーシステム刷新は冒険物語だと思う

この記事は 「レガシー」を保守したり、刷新したりするにあたり得られた知見・ノウハウ・苦労話 by Works Human Intelligence Advent Calendar 2024 への投稿となります。

普段はネタ記事ばかり書いていますが、今回は真面目な長文記事です。

※ 記載内容については上長から許可をいただいています。

私と会社について

• 会社員
  • 弊社9年目
• 役割
  • フルスタックエンジニアに近いポジション
• 最近の業務
  • システム保守の計画・実施
• システム構成
  • AWSをメインとしたクラウド環境

記事のテーマ

レガシーシステム（以下「レガシー」）の保守・刷新で得た知見や想いを綴ってます。
具体例として昨年実施したEC2の総入れ替えを中心に、ポエムな感じで記載しています。

EC2総入れ替えの概要

昨年、利用中のOSサポート終了に伴い、以下の流れでEC2全台再構築・再配置を行いました。

1. 現状のEC2リスト化
2. 移行先OS選定・新規EC2配置
3. 各ライブラリ・ミドルウェアのインストール・設定
4. アプリケーション配置
5. 段階的な切り替え

この記事では上記対応を話の軸にしています。

刷新活動で重要する3タスク

実際には3つどころでないですが、文量を考えて3つに絞りました。

1. レガシーの現状を[正確に]理解する
2. やることを決めて宣言する
3. やらないことを決めて宣言する

あくまで、私が大事だと思うだけで個人差があります。

1. レガシーの現状を「正確に」理解する

レガシーにはドキュメントが不十分な場合が大半で、「考古学者」のような発掘作業が必要です。

稀によくある状況ですが、今回のケースを一部抜粋します。

• AWSリソース管理状況
  • IaCとコンソール操作が混在
• サーバ上にのみ設定情報が存在
  • 各ミドルウェアの設定ファイル
  • サービスに利用する環境変数
• ライブラリ利用状況が複雑
  • パッケージマネージャーで導入
  • 担当者が手動ビルド
  • バージョンに差異

最近のサービスではコンテナ化等によりこれらの課題は大幅に減少します。
ただし、レガシーの場合は「考古学者」のように現状を発掘・把握する作業が必要です。

この理解フェーズを突破すれば、半分は終わったようなものです。
当たり前ですが、このフェーズが最も重要です。

余談ですが私は普段、低レイヤーから理解することを心がけています。

ネットワーク構成を理解する

今回はコンソールから直接作成されたリソースが多いので、AWS CLIを活用しつつ、コンソールを見て気合で頑張りました。

また、並行してシステムアーキテクチャ図を作成しました。
図式化にはdraw.ioを利用しましたが、場合によってはdiagramsなどを使うこともあります。

なお、draw.ioの出力画像にはメタデータ部分にダイアグラム情報が含まれるため、再編集が可能です。
画像コミットして編集できるなんて便利ですね。

構成図1 (抜粋)	構成図2 (抜粋)

ちなみに現在担当している案件では、さらに規模が大きかったため、AWS WorkLoadを活用しました。

ただし設計が不適切だと出力結果をそのまま利用することは難しいです。
そのため中間データとして活用しつつ、気合いで補完しました。
それでも作業効率は大幅に向上したので、状況に応じて検討すると良いでしょう。

最終的にはそれを中間データにして気合いで頑張りました。

適切に設計されている場合であれば自動運用も可能で、気合いに頼る必要はないかもしれません。

逆説的ですが、設計が適切かを確認するためにも一度ツールを試してみるのも良いでしょう。

なお、「気合い」という言葉を繰り返していますが、レガシー対応には考古学者のような情熱、読み解く力、そして忍耐が必要です。
中途半端な覚悟やスキルでは、ミイラ化してしまうかもしれません。

各マシンの役割を理解する

各マシンで利用されているライブラリやパッケージ、設定内容を把握することが重要です。
今回は下記事情があったので、AWS CLIを活用しつつ、コンソールを見て気合いで頑張りました。(2度目)

• サーバ上に直接ファイルで設定が保存されている
• 環境変数がマシンごとに異なる
• cronが各マシン上で手動編集されている
• パッケージを通さずビルドされたライブラリが存在
• AWS Systems Managerの設定が不適切
• など

AWS Systems Managerを適切に設定していれば、気合いを用いずとも利用パッケージやバージョンが簡単に把握でき、負担が軽減します。

今回救いだったのは、過去の担当者がAnsibleを残していたことです。
不完全ながらも、設定の大枠を迅速に理解できました。
ただし、冪等性を保ちAnsibleを記述・保守し続けるのは大変です。
場合によってはコンテナ化などの計画を検討するのも良いでしょう。

最後に、設定の差異を洗い出し、必要な設定だけを抽出して理解完了です。

ここで重要なのが「 決めつけないこと 」です。
見出しに 「正確に」と強調した理由はここにあります。
思い込みや決めつけが原因で大事故につながることもあるため、以下のようなケースに注意が必要です。

• 開発ドキュメントに記載があるから大丈夫
• Ansibleに記述があるから間違いない
• 信頼できる社内エンジニアの発言だから安心
• マシン名称から役割が分かるはず

これらはすべて過信のリスクをはらんでいます。
自分で確認・観測・計測する姿勢が最も大切です。

モニタリング環境を確認・整備する

モニタリング環境の確認・整備は、刷新成否を判断するうえで必須事項です。
現状を把握し、不足があれば事前に整備しましょう。

また、情報を一箇所に集約することも重要です。
刷新直後に「どこを確認すれば問題ないか」を即座に分析できる状態を作ります。

弊社では New Relic を利用しているので、こちらにメトリクスやエラー情報を集約しました。

マシンと実行プロセス	アプリケーションエラー

2. やることを決めて宣言する

現状を理解したら、次に「何をするか」を決めて合意形成を行います。

今回、会社側の要件はOSの更新のみでしたが、非機能要件を含め、このタイミングで実施すべき変更を提案しました。
特にマシンの再構築・再配置という大規模な変更はチャンスです。

また既存設定のそのまま移行が適切かどうかは検討が必要です。
次期バージョンで廃止予定の設定をそのまま引き継ぐべきではありません。
変更範囲を適切に抑え、原則として挙動を変えないことを前提に進めましょう。

実施した主な作業

• OS更新
  • 移行先OSの選定・検証
  • バージョンアップ対応と廃止ライブラリの移行
  • パッケージ管理外ライブラリの設定・ビルド
• 責務分割
  • PHPのプロセス分離
    • mod_php → php-fpm 移行
  • Webサーバ流入制御を一部 AWS WAF に切り出し
• ネットワーク設定見直し
  • 不要なネットワークピアリングの解除
  • サブネット設計と公開範囲の見直し
• 各種チューニング
  • インスタンスタイプ変更
  • ミドルウェアのパラメータ調整

挙動変わってるよね？というツッコミは尤もです。
変更範囲や影響については、関係者と合意形成しておきましょう。

そしてテストについても用意しておきましょう。
というより、普段からテストを書いてCIに組み込んでおきましょう。

3. やらないことを決めて宣言する

刷新の機会だからと、すべてを詰め込むのは避けるべきです。
変更が多すぎると問題発生時の原因切り分けが困難になり、不具合や障害を招くリスクも高まります。

そのため、明確な理由をもって「やらないこと」を決め、宣言することが「やること」と同じくらい重要です。

今回のケースでは以下を「やらないこと」としました。

• コンテナ化
• ログ転送基盤の変更

これらは刷新後に計画する方針とし、変更範囲を適切に絞りました。
（刷新後に計画が進まないリスクもありますが、それは別の話です）

また、「やるべきこと」「やらないこと」を宣言する際には、自己完結せず、関係者からの合意・承認を得ることを忘れないようにしましょう。

保守・刷新を通じて普段から意識してること

刷新のタイミングだけでなく、普段の開発活動でも意識しておくことも多いです。

名称・命名はしっかり考える

名称は非常に重要です。
関数名、リソース名、設定名など、あらゆる名称が対象です。

一度運用に乗せると名称の変更は極めて困難です。
以下のような汎用的すぎる名称を付けそうなときは立ち止まってください。

• common
• service
• admin
• getData

今回のケースでも不要と思われる機能に「common-service-common」などがあり、削除時に大きなリスクと恐怖を伴いました。

この恐怖を乗り越えるのは相当な気合いと覚悟が必要になので、触らぬ神に祟りなし、となって放置されがちです。

これらを回避するには、初めから適切な名称を付けることが重要です。

命名のコツを学ぶには、リーダブルコードなどを参考にすると良いでしょう。
また、CI/CDに命名ルールのチェックを組み込むのもおすすめです。

※参考: リーダブルコードの要点整理と活用法をまとめた | Qiita

そして命名を補完するためにコメントで説明するケースもありますが、あまりおすすめしません。
コメントを記載するなら「何をするか」よりも、「なぜそれをしないのか」に焦点を当てるべきです。

名称案に悩んだ際は、CopilotやChatGPTなどを活用すると良い提案を得られます。
現代のツールは非常に便利なので、積極的に活用しましょう。

※参考: 「コメントは書くな」 | Qiita

ただ個人開発や社内ツールなどは気分がアガる名称のほうがいい場合もあります。
ケースバイケースです。

ドキュメント整備に全力を注ぎすぎない

大前提としてドキュメントは大事です。
あくまでドキュメント作成自体が目的にならないように、という意味です。

難解な実装や仕様を補う超大作を作るより、実装や仕様そのものをシンプルにする方が効果的です。 禅
これにより、保守・刷新活動が格段に楽になります。

またドキュメントは保守性も意識して作成しましょう。
特にフォーマットの選定が重要です。
画像のみや特殊フォーマットなど、編集が困難な形式は避けるべきです。

理想は、更新差分が分かる形式で管理することです。
ｺﾚｶﾞﾑｽﾞｶｼｲ

少しずつ慎重に。時には大胆に。

保守と刷新は陰と陽、表裏一体です。
少しずつ進めるべきか、一気に進めるべきかの判断に正解はありません。
チームで議論し、状況に応じた最適なアプローチを模索しましょう。

システム変更の適用タイミングも同様です。
「秘密兵器を一発で華々しくリリース」などは映画の中だけです。
現実には、慎重かつ計画的なリリースが求められます。

リリース手法にはさまざまな選択肢があります。
適切な方法を選び、可能であれば普段から小さな試みを重ねて経験を積みましょう。
初めてのリリース方法は予想以上に緊張感を伴うものだからです。

※参考
リリース手法多すぎﾜﾛﾀｧ B/G、カナリア、機能フラグ、ダークローンチ、A/Bテスト | Qiita

対応ログを残す

「伝説のエンジニアがレガシーを一掃して去った。今では口伝が残るのみ。」

…カッコいいですが、現実では困ります。
また、担当者が在籍していても、当時の詳細を忘れてしまうことは意外と多いものです。

そのため、対応時のログを残すことが重要です。
次回の刷新時やトラブル対応時に、担当者が見返して役立ちます。

普段から記録する習慣をつけると、作業のベストパターンが見えてきます。
さらに、IaCを活用すれば、それ自体が具体的なログとなり、楽しながら記録を残すことができます。

情報集約 (※ほぼモザイク)	コンソールはキャプチャで楽

プランBを用意する

レガシー刷新は、新プロダクトや機能開発と比べ、失敗時のダメージが大きい場合が多いです。
そのため、入念な検証を行ったとしても、次善策としてプランBを用意しておくことが重要です。
刷新の適用計画と撤退計画はセットで考えましょう。

また、いきなり完璧なプランBを用意するのは難しいため、普段の開発活動でも「リリースが失敗したらどうするか」を常に意識することが大切です。

Before / After を記録する

刷新による影響を把握するため、結果を可能な限り定量的に記録しましょう。
正常に刷新できたか判断するうえでも重要です。
今回のケースでは、モニタリング環境を整備し、以下のような資料を作成しました。

加えて、設定コード削減量やファイル数の削減なども記録しました。

これは保守・刷新活動に限らず、LPOなど普段の開発活動においても必須のプロセスです。

評価されるようにする

保守・刷新活動は外から見ると「以前と何も変わらない」と見えがちで、新プロダクトや機能開発と比べて評価されにくい側面があります。

ただこれを軽視すると、評価されない上に華々しさも薄い仕事となり、保守刷新を希望する人材が不足するネガティブスパイラルに陥る可能性があります。

また自身が評価されないだけでなく、続く後輩も評価されない風土になってしまうので踏ん張りましょう。

評価を得るために私が意識してる点

• 成果を可能な限り定量化
  • コスト削減、稼働率向上、エラー発生率低下など
• 定量化が難しい部分は定性的に可視化
  • 図表やレポートを活用して直感的に伝える

今回は以下のような資料を用意しました。
（前項のBefore/After記録とも関連します）

設計観点	コスト観点

レガシーは単純な悪ではない

実はこれが今回最も伝えたいことです。

レガシーは時に「オワコン」として扱われがちですが、保守刷新が必要な時点で、それは価値を生み出し続けているシステムです。
価値のないプロダクトなら保守刷新の必要もありません。
むしろ、事業にとって重要な部分ほどレガシー化する傾向があります。

(一方で過去の経験を活かしてしっかり設計した新プロダクトに限って、早々に破棄されることもあります。悲しいね。)

今回刷新したシステムの大半は過去に私が作成した場所ではないです。

重要なのは、過去の担当者やプロダクトを批判するのではなく、どうすればいいか考えることです。
※偉そうに言ってますが、非常に難しくて私自身できていないこともあります

もし過去に対して文句を言いたくなるなら、まず当時の事業状況や背景を知る努力をしましょう。
その時代に自分がいたら、同じ選択をしていた可能性は十分にあります。
そして、同じ失敗を繰り返さないためにも、背景を理解することは大切です。

最後に個人的な感想

今回のマシン総入れ替えは諸事情により私単独の進行でした。
ただその間の事業施策全部は他メンバーにお願いして、刷新へ集中できる体制を整えました。

大変な作業でしたが、少数で進めたからこそ判断や適用のスピードを保つことができました。
個人的には、保守はチームで、刷新は少人数で実施するのが効果的だと感じています。

そして私は レガシー = 遺産 というフレーズだけで、刷新活動をやたら考古学に例えていますが、案外似ているところも多いと思います。

地図(ドキュメント)がない状態で現地(サーバ内)に向かい、危険な道(テストなし)を突き進み、謎の石碑(謎設定・コード)を解読して、宝(新システム)を手にして、無事に帰還(不具合0)しなくてはいけない。

むしろ、考古学と言うより冒険物語な気もしてます。

考古学が求めるものは事実だ。真理ではない。真理に興味がある者は哲学教室へ行け。失われた都市とか埋もれた宝は存在しない。地図の×印を掘って宝が出たためしはないのだ。
※ インディ・ジョーンズ シリーズより

未知のレガシー遺跡から無事脱出できたときの達成感は格別です。
みなさんもぜひ「冒険者」として挑戦してみてください。