LIVESENSE ENGINEER BLOG

リブセンスエンジニアの活動や注目していることを発信しています

クラウド移行における設計という共通認識

これは SRE Advent Calendar 2023 DAY 22 の記事です。

はじめに

リブセンスでインフラグループに所属している鈴木です。競馬に行きすぎて、行ったことない地方競馬場が水沢と高知だけ1になりました。今後は釜山か済州2を考えています。
ところで、クラウド移行を複数経験したことで感じたことを共有しようと思います。なお本記事は第2回ゆるSRE勉強会の登壇資料をもとに作っています。

自分しかわからないPR

オンプレのVMで動いていた社内認証基盤をECS Fargateに移行する案件がありました。構成は下記となります。

  • nginxのリバースプロクシ
  • oauth2-proxyという様々なIDプロバイダに対応しているOSS
  • goで書かれた社内認証のアプリケーション

Google認証ができたら、とある管理画面に入れる認可をするといったものです。
このシステムをECSに移行する際、チームメンバーに設計の共有をせず、いきなりステージングを作るPRを出しました。TerraformによるクソデカPRです。
レビュワーからしたらよくわからなくて大きいPRが突然来ました。結果誰もレビューせず放置されていました。
わかります。自分も巨大なPRを見ると脳がフリーズします。後で見ようと新規タブで開いて、30分後に無意識に閉じたことは何回もあります。

なぜ読まれなかったのか

共通認識がなかった、それだけです。以下のことをしていなかったのが原因でした。

  • 共通認識が揃っていないと
    • そもそもの理解にコストがかかる
    • 読んだところで確認にコストがかかる
      • 結果、よくわからずに、そっ閉じされる
  • 共通認識とは?
    • どうしてそれをするのかという設計、意図などの共有のこと

実際のPR

システム名とかは念のため隠しましたmm

  • 悪い点
    • 基本設計レベルなのに、絵がなく辛い
    • 詳細設計レベルの情報や、検討レベルでの情報も混ざっている

設計という共通認識の重要性

移行というのは情報が大きく変わり、コミュニケーションコストが大きいです。単純に現状と移行後のアーキテクチャが2つ存在し、新規に作るより、他人に伝える時に2倍コストがかかります。
今回は、現状(オンプレ)と移行後(クラウド)の認識を共有しつつ進める必要がありました。コードの共有の前に、設計の共有をするのが正解でした。
設計という共通認識を共有することで、コミュニケーションコストを小さくすることができます。
個人的な感覚ですが、お客さんにヒアリングシートを作って送るのと、100行Pythonを書くのは同じくらいのコストだと思います。コミュニケーションコストは小さい方が絶対に良いです。

経緯を残すと++

基本設計や移行設計はもちろん、経緯を残すという観点でのADRも作った方がいいです。

  • オンプレのhogehogeをマネージドサービスに移行した
    • こういうのはインターネットにいくらでも情報があるし、ドキュメントにするまででもないか…と思いますが…
      • 技術的なことは調べればわかりますが、経緯は当時いた人しかわかりません、その経緯を残すことで、後から見たときに、なぜそうしたのかがわかります
      • 議事録があるならば、議事録からADRを作るのもありです
    • 移行に至った経緯、関係者の考え、何故そうなったのかを知るのは今いる人しかわかりません
      • それをADRとして残しましょう、資産になります
        • システムに敬意を持って経緯を残しましょう

ちいさくてかわいいPR

1つのPRで複数機能を追加したり、行数が多いと読む人が辛いです。PRを機能ごとに分割すると確認しやすく、レビュワーファーストです。
これをちいさくてかわいいPR、ちいかわPRと呼びます。ちいかわPRについての記事です。↓ made.livesense.co.jp

わかりやすいPRのTips

今までレビューしやすい思ったPRのTipsを紹介します。

  • 設計ドキュメントへのリンクが概要に貼られている
    • ドキュメントを書くまでもないなら、概要に設計が書かれている
  • 図があるといい
    • GitHubがMermaidに対応しているので、Mermaidで書くといい
      • Mermaind Live Editorはスイスイ書けておすすめです
      • ChatGPTに伝えると完璧ではないが、大枠の物を作ってくれたりします
  • ロジックなら
    • ロジックを日本語で完結に説明ないし、コメントを的確に入れる
  • パラメータ変更や追加なら
    • 移行だとPRが大きくなりがちです
      • 既存とのdiffがあると親切です(GitHubにはdiffシンタックスハイライトがあります)
      • nginxのconf200行を複数ファイルとか読めない
    • 既存実装のコピーなら、どこどこのコピーと明記してdiffを貼り付ける
      • ステージングを作った後の本番環境などなど…

例えばTerraformでECSから作るとします。

  • ECR/IAMロールから作る
    • どんなコンテナ/権限を使うかで後続作業がチョットわかる
    • タスクロールとタスク実行ロールのPRが来たら…
  • こうすると次にECSがくるのがわかる

直したPR

前よりは頭に入りやすい気がします

終わりに

自戒として書きました。日々レビュワーファーストに気をつけていきましょう。


  1. 家族・恋人・友人と行くのに最適なのは大井競馬場です、冬はイルミネーションもあります。昭和な感じを味わいたければ関東なら浦和、東海なら笠松がおすすめです。どちらもグルメが茶色くて美味しいです。笠松のどて煮を食べると頭上にピコンってランプがついた気がします。寿司を食べたければ金沢競馬です、有名な寿司屋の支店が競馬場にあります。ネタが午前中になくなるので早めに行きましょう。
  2. 日本にはないポニー競馬があります。行ってみたい。ダートコースだけというのもダート好きにたまらない。