SSMJP-20200520-NLOG2N2

手順書の書き方LT お前らの手順書の書き方は間違えている @nlog2n2 Sekiguchi Toshihiro

今日話すこと 手順書の書き方について書こうとしたら、 オペレーションのお作法みたいになったでござる。

質問です

手順書、何で書いてますか？ 30 56 53 8 https://www.menti.com/tr3nsuipzn

• https://www.menti.com/tr3nsuipzn

圧倒的O ffi アンケート結果 ce

1. よくもらう手順

1. アプリケーション部門からよくもらう手順書 tar -zxvf 20211231.tar.gz cd 20211231 ./bin/release.sh cat ./log/release.log( successと出てたらOK）

1. アプリケーション部門からよくもらう手順書 tar -zxvf 20211231.tar.gz cd 20211231 ./bin/release.sh cat ./log/release.log( successと出てたらOK） こんな手順書が仮にあったとしましょう。 どのあたりが問題だと思いますか？

1. アプリケーション部門からよくもらう手順書 tar -zxvf 20211231.tar.gz cd 20211231 ./bin/release.sh cat ./log/release.log( successと出てたらOK） 左側の手順書の良くないところ • • • • • • • • ログイン元の端末情報が存在しない ログイン先の端末情報が存在しない 20211231.tar.gz の説明が存在しない どのユーザーでログインするか指定されていない どのディレクトリで実施するか指定されていない ./bin/release.sh の内容を引継を行なっていない ./bin/release.sh の実行ユーザーが誰か分からない log に success って、過去のものと今回の物を分別 する方法が記載されていない こんな手順書が仮にあったとしましょう。 どのあたりが問題だと思いますか？ • サービスの確認がログのみになっている • 疎通確認、サービス確認、稼働しているポートの確認 などが存在しない • コンテナの中で実行している可能性もあるが、どこで → 取り急ぎ、右側の内容が頭によぎる 実施する作業なのか記載されていない • 冗長系なら片系落としながら作業なのかも不明

2. 修正

2. 修正 0. 前提情報及び作業環境へのログイン • 作業は、踏み台サーバを経由して、本番のサーバで実施する。 • 作業者の作業端末を使い ssh でログインを行う。 • 事前作業で /var/ssmjp/src の配下に 20211231.tar.gz のファイルを置いている。 • 20211231.tar.gz の中には、Webサイトの証明書、軽微な不具合修正を行なったソースコードがあ り、./bin/release.sh を実行することでリリースされる。修正内容は、Github の XXXX を参照。 • リリース作業は ssmjp-ope のユーザでシェルを実行する。パスワード等はユーザ管理表を参照。 0.1 本番サーバへのログイン $ ssh -A -p XXXX [email protected] $ ssh -A -p XXXX [email protected] 0.2 作業環境の確認 $ hostname * ssmjp.ad.jp と表示されること $ pwd * /home/ec2-user と表示されること $ cd /var/ssmjp/src $ ls -ltr | grep "20211231.tar.gz" 1. リリース作業の開始 1.1 左側の手順書の良くないところ • • • • • • • • ログイン元の端末情報が存在しない ログイン先の端末情報が存在しない 20211231.tar.gz の説明が存在しない どのユーザーでログインするか指定されていない どのディレクトリで実施するか指定されていない ./bin/release.sh の内容を引継を行なっていない ./bin/release.sh の実行ユーザーが誰か分からない log に success って、過去のものと今回の物を分別 する方法が記載されていない • サービスの確認がログのみになっている • 疎通確認、サービス確認、稼働しているポートの確認 などが存在しない • コンテナの中で実行している可能性もあるが、どこで 実施する作業なのか記載されていない • 冗長系なら片系落としながら作業なのかも不明

ツッコミが間に合わん！！！ と言うわけで、こう書けや！とうい内容をまとめていく。

3.手順書を書くときの基本方針

3.手順書を書くときの基本方針 1. 作業ログを残す準備をしよう 2. 日本語はしっかり書く 3. 作業内容を共有できる項番をつける 4. history コマンド打てば、どこで何をしたか分かるように書く history コマンドは考古学

3.1 作業ログを残す準備をしよう Mac OS（標準のターミナル) script コマンド、tee コマンドを使ってログを残す。 script コマンドだと、ターミナルの起動時のサイズで行数、列数が設定されてしま うみたい。制御文字も入るので可読性に難あり。less -r しがち。 Mac OS（⌘+Shift+5 で録画） MacOSの標準機能で付いている録画機能。標準の録画ファイルは重たいので FFmpeg コマンドで mp4 に変換して NAS に保存する。手順書を残す時間的な余 裕がないときに使う。 Windows Teraterm にログ設定をすると良い。ログファイル名はカスタマイズが可能なの で、ホスト名̲YYYYmmdd̲HHMMSS.log とかにするのがお勧め。

3.2 日本語で作業内容を書く 検証環境で手順の検証が終わったら、オペレーションの内容をできるだけ詳細 に日本語で書きましょう。メンテナンス計画書、メンテナンス手順書の2つが あることが望ましい状態です。 メンテナンス計画書 (技術的なことは書かない) 通し番号、タイトル、日時、担当者、レビュー担当者、作業目的、作業内 容、メンテナンスアナウンス、影響範囲等 メンテナンス手順書 (技術的なことも書く) メンテナンス計画書の通し番号、構成管理上の参考資料の場所、事前作業、 本番作業、切り戻し手順、事後作業

3.2 日本語で作業内容を書く メンテナンス手順書 事前作業、本番作業、切り戻し手順、事後作業に関しては、以下のフォーマットで書くようにして います。色が使えるなら色を使いましょう。 1. 本番作業 1.1 作業タイトル 1.1.1 作業内容 作業内容に関する説明書き コマンド1 コマンド2 コマンド3 ＊確認コマンドと予想される結果 1.2 作業タイトル（続く）

3.3 作業内容を共有できる項番をつける 各作業に番号をつけましょう。 どこの作業をしているのか、他者に共有しやすくなります。 Slack でメンテナンスの状況報告 メンテナンスの事前レビュー メンテナンス失敗時の事後報告 番号をつける副次的な効果として、手順書がそれっぽく見えます。

3.4 どこで何をしたか分かるように書く 3.4.1 誰がどこにログインするか書こう 3.4.2 絶対パスで書く 3.4.3 ユーザー、権限周りは事前に確認する 3.4.4 前後の確認は awk, grep, di を有効に使う 3.4.5 ダイイングメッセージ性のあるコマンドを使う ff 3.4.6 手順書を作るシェルを書く

3.4.1 誰がどこにログインするか書こう ログイン（ログオン）するための情報を書きましょう。 IPアドレス（ホスト名、IPアドレス、IPv6アドレス） プロトコル（telnet、SSH、RDP、etc...) ポート番号 ユーザー名、パスワード ログインするためのアプリケーション（terminal、RDP、teraterm、etc) 間違った端末でオペレーションしないように、ログイン後、hostname , pwd コマンドでオペレーションの場所を確認することをお勧めします。

3.4.2 絶対パスで書く 操作するファイル、ディレクトリの指定を絶対パスにすることで、history の前 後のコマンドに依存せず、何の作業したか理解がしやすくなります。 cd, cp, touch, mkdir などでパスを指定するときは絶対パス rm -rf とかついうっかり "rm -rf /" とかしちゃうとアレでアレでアレ 例外的に、シェルスクリプト、Python、Ruby、Perl などのプログラムの 実行に関しては相対パスで手順を作成する

3.4.3 ユーザー、権限周りは事前に確認する 何かと検証環境では、sudo su で root ユーザーになりがち。 事前作業や構成管理の段階で、パーミッションの確認をした上で手順書を書きま しょう。 ls -ltr | grep "<対象の絶対パス>" で権限を確認し、手順書へ反映します。 手順書のコマンドの行頭に＄＃を手順書内に書たりします。 必要に応じて、シェルスクリプトには chmod +x XXX.sh とかしましょう。 特に手順でシェルを実行するコマンドの場合は、事前に本番環境のユーザー・グ ループ・パーミッションすべて確認しておく方が無難です。

3.4.4 前後の確認は awk, grep, diff を有効に使う

作業後の効果確認には、cat, di , grep -o, awk -F "区切り文字" '{print $X}'
などで、変更の確認するのがベター。

ff

よほど複雑じゃない限り、目grep でも良い気がする

3.4.5 ダイイングメッセージ性のあるコマンドを使う Vim, Emacs, Nano 戦争に終止符を打とう エディタで開いて設定ファイルなどを編集すると、history しても、何をどのように変更し たか分からなくなる。 基本的には sed, echo, touchなどにリダイレクト繋げて、コマンドにして手順書を書く。 docker コンテナの中の操作も１行のコマンドで行うようにしました。 インフラ設計として、ホストのディレクトリをマウントする設計に変えた方が良い気がして いますが、本番で動いているものを変更するのは難しいので、運用でカバー。 $ docker exec -it web cat /etc/nginx/nginx.conf | grep "worker̲processes" worker̲processes 1; $

3.4.5 （例）crontab の編集作業 1. ログ取得定時実行停止 1.1 crontab の状態の確認 $ crontab -l | grep "^\*/10.*work.sh$" □*/10 * * * * ./home/vagrant/work.sh と表示されること 1.2 crontab コマンドでバックアップの取得 $ crontab -l > crontab $ cat crontab 1.3 ログ取得シェルのコメントアウト $ sed -i.bak -e 's/^/#/' crontab ff 1.4 差分の確認 $ di crontab crontab.bak □以下の内容が表示されること 1c1 < #*/10 * * * * ./home/vagrant/work.sh --> */10 * * * * ./home/vagrant/work.sh 1.5 crontab への適用 $ crontab crontab 1.6 crontab の状態の確認 $ crontab -l | grep "^#\*/10.*work.sh$" □ #*/10 * * * * ./home/vagrant/work.sh と表示されること 1.7 一時的なファイルの削除 $ rm -i crontab*

3.4.6 手順書を作るシェルを書く 定型作業に近い状態であれば、他人が手順書を同じように書くのは不可能か つ非効率なので、シェルスクリプトで手順書が出力されるように書く。 最近、同僚のロシア人に入力を、ハードコーディングしないで、変数の入力 は、インタラクティブにした方がいいよと指南された。いいマサカリ。

Tips

Tips1: よく使うショートカットキー • Linux • ctrl + l 画面をきれいにする • ctrl + r コマンドの履歴を出す（ctrl + n , ctrl + p ) • ctrl + a 行頭へ移動 • ctrl + e 行末へ移動 • ctrl + c プロセスを強制終了させる • Windows • Windows キー + R でファイル名を指定して実行を起動 • control 入力 コントロールパネル起動 • mstsc 入力 リモートデスクトップ起動 • cmd 入力 コマンドプロンプト起動

Tips2: 積極的に使っていきたいショートカットキー • Linux（bind -p で一覧が表示されるらしい。ほんまか？） • ctrl + u カーソル位置から行頭まで削除 • ctrl + k カーソル位置から行末まで削除 • ctrl + w カーソル位置の単語を削除 • ctrl + y 直前に削除した文字列を貼り付け • ctrl + z 処理を一時中断 • esc + f 一単語前へ移動 • esc + b 一単語後ろへ移動

Tips3: 良く使うコマンド sed , touch , echo にリダイレクト( > とか >> ) 闇に放り込む（/dev/null） 順番に並べて、値をまとめて、さらに順番に並べる( sort | uniq | sort ) bash で for 文で数値演算してたら awk に書き換える 最近知ったけど nohup XXXX & で ssh セッション切れてもバックグラウンドで実行（バッチ処理と かに便利） 複数行まとめて文字置換するときに perl を一時期使っていた for 文をワンライナーで、 for le in ̀ls -1̀ ; do echo $ le ; done 的なことはよくやる fi fi grep は偉大

FYI：Ansibleはありか？なしか？ 手順書としてはあり/ 引継資料としてはなし 引継資料として playbook のみを渡されたら、何を意図してコマンドが実施 されたかが不明になるため、ドキュメントが別途必要になる認識です。

FYI：メンテナンスアナウンス サービスを利用している人たちにメンテナンスやりますよ！と予告することが一 般的だと思います。 ここは技術関係ないところなので、フォーマットを先に作って組織内で決まっ た形を作っていると揉めることが減ります。

おしまい

スペシャルサンクス • 以下の素材やスライドデザインを参考にしました。 • プレゼンテーション用アイコン(yuyarinさん) https://github.com/yuyarin/presentation̲icons • 運用自動化、不都合な真実(波田野さん) https://speakerdeck.com/opelab/20171212-automation •

ボツ

3.最低限のドキュメントの準備 構成図（必須は赤文字） ● システムマップ、IPアドレスアサイン表、物理構成図、論理構成図、プロトコルフロー図 ● ディレクトリ構成、コンテナの構成、ミドルウェア設定、ログ設定 手順書 ● 作業目的、担当者、レビュー担当 ● 事前作業、本番作業、事後作業、切り戻し手順 ● アナウンスフォーマット ● 監視静観時のオペレーターの監視方法について

構成図 • システムマップ いわゆるポンチ絵。 システムの機能別にオブジェクトを配置して、なんの役割をしているか明確にする。 • NW図（物理） 物理的な構成を書く図。主にマシン名、ポート、VLANの関係などを洗い出すことが役割。 たまに変態構成をとる場合は、物理構成図が芸術的になる。 • 論理構成図 L7、L3の情報を洗い出す。単体の情報だと構成図として役割として微妙だが、通信別の流 れを明らかにすることで、どのようにメンテナンスするか、どのように監視するかなどが明 確になる。L2のスイッチは基本的に書かないが、メンテナンス用にIPアドレスが振られてい る場合は記載対象となるため注意。