株式会社カミナシで VPoE を務めている pospome です。 (´・ω・`)
最近業務でインフラ作業の手順書について関わることがあったので、 自分が思う理想の手順書についてまとめようと思います。
作業手順書はとても重要
プロダクトを開発・運用する過程で、たまーに発生するのがインフラ作業です。 AWSのコンソール画面やTerraformで簡単に変更できるような設定・作業であれば、わざわざ手順書を作る必要もないと思いますが、 複雑な作業になると手順書を作る機会があると思います。
pospomeも過去に複雑なインフラ作業を経験したことがありますが、そういった作業はとっても緊張します。 心臓がドキドキするし、「変なことが起こりませんよーに」と思いながらやった記憶があります。 そして、インフラ作業はミスしたときのダメージが大きかったり、やり直すにも関係各所との調整が必要だったりします。
インフラ作業の手順書は、そういった中で、自信を持って作業ができるかどうかを左右するとても重要なドキュメントです。 しっかり準備して、安心安全に作業を完了させましょう。
手順書を書くときに気をつけるポイント
ここからpospome個人が思う "気をつけるポイント" を記載します。
1枚のドキュメントで完結させること
手順書が複数のドキュメントで構成されると、それらのドキュメントを行ったり来たりする必要があります。 作業当日の緊張した場面で、ドキュメントをあっちこっち参照するのは意外とストレスがかかります。
「このドキュメントの作業は終わったから、前のドキュメントに戻って・・・どこまでやったんだっけ・・・」
こんなことを考えながら作業するのは避けたいところです。 手順書は1枚のドキュメントになっており、それだけ見ていればいいようにするのが好ましいと思います。
上から下に読んでいけばいい構成にすること
手順書が1枚のドキュメントだったとしても、あっちこっちスクロールしながら作業を進めるのはストレスになります。 上から下に読んでいけばいい構成にすることも重要です。
コピペするだけでいいようにすること
作業時はとっても緊張するので、頭で何かを考える余地は可能な限りなくしたいところです。
「あれ、この作業ってどのボタンを押すんだっけ?」
「この設定を有効にするチェックボックスが見当たらないぞ・・・?」
なんてことにならないようにしましょう。
具体的には以下を徹底すると良いと思います。
- ターミナルなどに入力するコマンドはコピペして実行できるように記載すること。
- コンソール画面の作業はスクショを貼って、どのような作業をすればいいか明確にすること。
どのボタンを押すのか、どのチェックボックスをON/OFFにするのか、などなど・・・スクショに加えて文章での説明があるとよいです。 - Terraformでの変更はPull Requestを事前に作っておくこと。
当日はそのPRをmergeすればOKな状態にしておきましょう。mergeする際にConflictが発生すると焦ってしまうので、PRを作るタイミングは気をつけましょう（もしくは最新の変更を取り込んでおくこと）。
他人がレビューできるようにすること
気をつけて書いた手順書も意外と抜け漏れがあるものです。 コードやDesign Docと同じように手順書もチームメンバーにレビューしてもらいましょう。 そのときに気をつけなければいけないのが "他人がレビューできる品質/構成になっているか" です。
"手順書を書くときに気をつけるポイント" として以下の3点を紹介してきましたが、 以下が守られていない手順書だとレビューすることが困難になってしまいます。
- 1枚のドキュメントで完結させること
- 上から下に読んでいけばいい構成にすること
- コピペするだけでいいようにすること
レビューするのが困難な手順書だと、 レビューする側も「まあ・・・いーんじゃない・・・」みたいな感じでちゃんとレビューできなかったりするので、 手順書は頑張って書きましょう。
理想はパブリッククラウドの手順書
あーだこーだ言ってきましたが、自分が手順書として参考にするのは "パブリッククラウドの手順書" です。 パブリッククラウドの手順書は初心者であっても目的を達成できるような作りになっているので、自分としては理想の手順書に近いと思っています。
例えば以下は AWS ECS の手順書です。
AWS CLI を使用した Amazon ECS マネージドインスタンスのタスクの作成方法について説明します。 - Amazon Elastic Container Service
↑のように "誰でもできる", "誰でも理解できる" ようになっていると良いかなーと思います。 良い手順書のイメージが持てない方は参考にするとよいのではないでしょうか。
まとめ
ということで、今回は自分が理想とするインフラ作業の手順書についてまとめました。
手順書が必要なインフラ作業は機会としては少ないかもしれません。 しかし、だからこそ実施する際にはしっかり準備して、失敗しないようにしたいですね。
宣伝
株式会社カミナシでは以下のポジションをすごく募集しています。 興味のある方は応募してみてください。
