Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.
@nlog2n2
Sekiguchi Toshihiro
手順書の書き方LT
お前らの手順書の書き方は間違えている
今日話すこと
手順書の書き方について書こうとしたら、
オペレーションのお作法みたいになったでござる。
質問です
手順書、何で書いてますか?
30 56 53 8
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 ...
1. アプリケーション部門からよくもらう手順書
こんな手順書が仮にあったとしましょう。


どのあたりが問題だと思いますか?
→ 取り急ぎ、右側の内容が頭によぎる
tar -zxvf 20211231.tar.gz
cd 20211231
./...
2. 修正
2. 修正
0. 前提情報及び作業環境へのログイン
• 作業は、踏み台サーバを経由して、本番のサーバで実施する。
• 作業者の作業端末を使い ssh でログインを行う。
• 事前作業で /var/ssmjp/src の配下に 20211231....
ツッコミが間に合わん!!!
と言うわけで、こう書けや!とうい内容をまとめていく。
3.手順書を書くときの基本方針
3.手順書を書くときの基本方針
1. 作業ログを残す準備をしよう


2. 日本語はしっかり書く


3. 作業内容を共有できる項番をつける


4. history コマンド打てば、どこで何をしたか分かるように書く


history コマン...
3.1 作業ログを残す準備をしよう
Mac OS(標準のターミナル)


script コマンド、tee コマンドを使ってログを残す。


script コマンドだと、ターミナルの起動時のサイズで行数、列数が設定されてしま
うみたい。制御文字も...
3.2 日本語で作業内容を書く
検証環境で手順の検証が終わったら、オペレーションの内容をできるだけ詳細
に日本語で書きましょう。メンテナンス計画書、メンテナンス手順書の2つが
あることが望ましい状態です。
メンテナンス計画書 (技術的なことは書...
3.2 日本語で作業内容を書く
メンテナンス手順書


事前作業、本番作業、切り戻し手順、事後作業に関しては、以下のフォーマットで書くようにして
います。色が使えるなら色を使いましょう。
1. 本番作業


1.1 作業タイトル


1.1.1...
3.3 作業内容を共有できる項番をつける
各作業に番号をつけましょう。


どこの作業をしているのか、他者に共有しやすくなります。
Slack でメンテナンスの状況報告
メンテナンスの事前レビュー
メンテナンス失敗時の事後報告


番号をつける...
3.4 どこで何をしたか分かるように書く
3.4.1 誰がどこにログインするか書こう
3.4.2 絶対パスで書く
3.4.3 ユーザー、権限周りは事前に確認する
3.4.4 前後の確認は awk, grep, di
ff
を有効に使う
3.4....
3.4.1 誰がどこにログインするか書こう
ログイン(ログオン)するための情報を書きましょう。
IPアドレス(ホスト名、IPアドレス、IPv6アドレス)
プロトコル(telnet、SSH、RDP、etc...)
ポート番号
ユーザー名、パスワー...
3.4.2 絶対パスで書く
操作するファイル、ディレクトリの指定を絶対パスにすることで、history の前
後のコマンドに依存せず、何の作業したか理解がしやすくなります。
cd, cp, touch, mkdir などでパスを指定するときは絶...
3.4.3 ユーザー、権限周りは事前に確認する
何かと検証環境では、sudo su で root ユーザーになりがち。


事前作業や構成管理の段階で、パーミッションの確認をした上で手順書を書きま
しょう。
ls -ltr ¦ grep "<対...
3.4.4 前後の確認は awk, grep, diff を有効に使う
作業後の効果確認には、cat, di
ff
, grep -o, awk -F "区切り文字" '{print $X}' 
などで、変更の確認するのがベター。


よほど複...
3.4.5 ダイイングメッセージ性のあるコマンドを使う
Vim, Emacs, Nano 戦争に終止符を打とう
エディタで開いて設定ファイルなどを編集すると、history しても、何をどのように変更し
たか分からなくなる。


基本的には s...
3.4.5 (例)crontab の編集作業
1. ログ取得定時実行停止


1.1 crontab の状態の確認
$ crontab -l ¦ grep "^*/10.*work.sh$"


□*/10 * * * * ./home/vag...
3.4.6 手順書を作るシェルを書く
定型作業に近い状態であれば、他人が手順書を同じように書くのは不可能か
つ非効率なので、シェルスクリプトで手順書が出力されるように書く。


最近、同僚のロシア人に入力を、ハードコーディングしないで、変数の入...
Tips
Tips1: よく使うショートカットキー
• Linux
• ctrl + l 画面をきれいにする
• ctrl + r コマンドの履歴を出す(ctrl + n , ctrl + p )
• ctrl + a 行頭へ移動
• ctrl + e ...
Tips2: 積極的に使っていきたいショートカットキー
• Linux(bind -p で一覧が表示されるらしい。ほんまか?)
• ctrl + u カーソル位置から行頭まで削除
• ctrl + k カーソル位置から行末まで削除
• ctrl...
Tips3: 良く使うコマンド
sed , touch , echo にリダイレクト( > とか >> )
闇に放り込む(/dev/null)
順番に並べて、値をまとめて、さらに順番に並べる( sort ¦ uniq ¦ sort )
bash...
FYI:Ansibleはありか?なしか?
手順書としてはあり/ 引継資料としてはなし


引継資料として playbook のみを渡されたら、何を意図してコマンドが実施
されたかが不明になるため、ドキュメントが別途必要になる認識です。
FYI:メンテナンスアナウンス
サービスを利用している人たちにメンテナンスやりますよ!と予告することが一
般的だと思います。
ここは技術関係ないところなので、フォーマットを先に作って組織内で決まっ
た形を作っていると揉めることが減ります。
おしまい
• 以下の素材やスライドデザインを参考にしました。
• プレゼンテーション用アイコン(yuyarinさん)


https://github.com/yuyarin/presentation_icons


• 運用自動化、不都合な真実(波田野...
Prochain SlideShare
Chargement dans…5
×

sur

ssmjp 20210520 nlog2n2 tejun Slide 1 ssmjp 20210520 nlog2n2 tejun Slide 2 ssmjp 20210520 nlog2n2 tejun Slide 3 ssmjp 20210520 nlog2n2 tejun Slide 4 ssmjp 20210520 nlog2n2 tejun Slide 5 ssmjp 20210520 nlog2n2 tejun Slide 6 ssmjp 20210520 nlog2n2 tejun Slide 7 ssmjp 20210520 nlog2n2 tejun Slide 8 ssmjp 20210520 nlog2n2 tejun Slide 9 ssmjp 20210520 nlog2n2 tejun Slide 10 ssmjp 20210520 nlog2n2 tejun Slide 11 ssmjp 20210520 nlog2n2 tejun Slide 12 ssmjp 20210520 nlog2n2 tejun Slide 13 ssmjp 20210520 nlog2n2 tejun Slide 14 ssmjp 20210520 nlog2n2 tejun Slide 15 ssmjp 20210520 nlog2n2 tejun Slide 16 ssmjp 20210520 nlog2n2 tejun Slide 17 ssmjp 20210520 nlog2n2 tejun Slide 18 ssmjp 20210520 nlog2n2 tejun Slide 19 ssmjp 20210520 nlog2n2 tejun Slide 20 ssmjp 20210520 nlog2n2 tejun Slide 21 ssmjp 20210520 nlog2n2 tejun Slide 22 ssmjp 20210520 nlog2n2 tejun Slide 23 ssmjp 20210520 nlog2n2 tejun Slide 24 ssmjp 20210520 nlog2n2 tejun Slide 25 ssmjp 20210520 nlog2n2 tejun Slide 26 ssmjp 20210520 nlog2n2 tejun Slide 27 ssmjp 20210520 nlog2n2 tejun Slide 28 ssmjp 20210520 nlog2n2 tejun Slide 29 ssmjp 20210520 nlog2n2 tejun Slide 30 ssmjp 20210520 nlog2n2 tejun Slide 31 ssmjp 20210520 nlog2n2 tejun Slide 32 ssmjp 20210520 nlog2n2 tejun Slide 33 ssmjp 20210520 nlog2n2 tejun Slide 34
Prochain SlideShare
What to Upload to SlideShare
Suivant
Télécharger pour lire hors ligne et voir en mode plein écran

5 j’aime

Partager

Télécharger pour lire hors ligne

ssmjp 20210520 nlog2n2 tejun

Télécharger pour lire hors ligne

手順書の書き方

ssmjp 20210520 nlog2n2 tejun

  1. 1. @nlog2n2 Sekiguchi Toshihiro 手順書の書き方LT お前らの手順書の書き方は間違えている
  2. 2. 今日話すこと 手順書の書き方について書こうとしたら、 オペレーションのお作法みたいになったでござる。
  3. 3. 質問です
  4. 4. 手順書、何で書いてますか? 30 56 53 8 https://www.menti.com/tr3nsuipzn
  5. 5. アンケート結果 圧倒的O ffi ce
  6. 6. 1. よくもらう手順
  7. 7. 1. アプリケーション部門からよくもらう手順書 tar -zxvf 20211231.tar.gz cd 20211231 ./bin/release.sh cat ./log/release.log( successと出てたらOK)
  8. 8. 1. アプリケーション部門からよくもらう手順書 こんな手順書が仮にあったとしましょう。 
 どのあたりが問題だと思いますか? tar -zxvf 20211231.tar.gz cd 20211231 ./bin/release.sh cat ./log/release.log( successと出てたらOK)
  9. 9. 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 って、過去のものと今回の物を分別 する方法が記載されていない • サービスの確認がログのみになっている • 疎通確認、サービス確認、稼働しているポートの確認 などが存在しない • コンテナの中で実行している可能性もあるが、どこで 実施する作業なのか記載されていない • 冗長系なら片系落としながら作業なのかも不明
  10. 10. 2. 修正
  11. 11. 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 ec2-user@step.ssmjp.ad.jp   $ ssh -A -p XXXX ec2-user@ssmjp.ad.jp  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 って、過去のものと今回の物を分別 する方法が記載されていない • サービスの確認がログのみになっている • 疎通確認、サービス確認、稼働しているポートの確認 などが存在しない • コンテナの中で実行している可能性もあるが、どこで 実施する作業なのか記載されていない • 冗長系なら片系落としながら作業なのかも不明
  12. 12. ツッコミが間に合わん!!! と言うわけで、こう書けや!とうい内容をまとめていく。
  13. 13. 3.手順書を書くときの基本方針
  14. 14. 3.手順書を書くときの基本方針 1. 作業ログを残す準備をしよう 
 2. 日本語はしっかり書く 
 3. 作業内容を共有できる項番をつける 
 4. history コマンド打てば、どこで何をしたか分かるように書く 
 history コマンドは考古学 

  15. 15. 3.1 作業ログを残す準備をしよう Mac OS(標準のターミナル) 
 script コマンド、tee コマンドを使ってログを残す。 
 script コマンドだと、ターミナルの起動時のサイズで行数、列数が設定されてしま うみたい。制御文字も入るので可読性に難あり。less -r しがち。 Mac OS( +Shift+5 で録画) 
 MacOSの標準機能で付いている録画機能。標準の録画ファイルは重たいので FFmpeg コマンドで mp4 に変換して NAS に保存する。手順書を残す時間的な余 裕がないときに使う。 Windows 
 Teraterm にログ設定をすると良い。ログファイル名はカスタマイズが可能なの で、ホスト名_YYYYmmdd_HHMMSS.log とかにするのがお勧め。
  16. 16. 3.2 日本語で作業内容を書く 検証環境で手順の検証が終わったら、オペレーションの内容をできるだけ詳細 に日本語で書きましょう。メンテナンス計画書、メンテナンス手順書の2つが あることが望ましい状態です。 メンテナンス計画書 (技術的なことは書かない) 
 通し番号、タイトル、日時、担当者、レビュー担当者、作業目的、作業内 容、メンテナンスアナウンス、影響範囲等 メンテナンス手順書 (技術的なことも書く) 
 メンテナンス計画書の通し番号、構成管理上の参考資料の場所、事前作業、 本番作業、切り戻し手順、事後作業
  17. 17. 3.2 日本語で作業内容を書く メンテナンス手順書 
 事前作業、本番作業、切り戻し手順、事後作業に関しては、以下のフォーマットで書くようにして います。色が使えるなら色を使いましょう。 1. 本番作業 
 1.1 作業タイトル 
 1.1.1 作業内容 
    作業内容に関する説明書き 
     コマンド1 
     コマンド2 
     コマンド3 
      *確認コマンドと予想される結果 
 1.2 作業タイトル(続く)
  18. 18. 3.3 作業内容を共有できる項番をつける 各作業に番号をつけましょう。 
 どこの作業をしているのか、他者に共有しやすくなります。 Slack でメンテナンスの状況報告 メンテナンスの事前レビュー メンテナンス失敗時の事後報告 
 番号をつける副次的な効果として、手順書がそれっぽく見えます。
  19. 19. 3.4 どこで何をしたか分かるように書く 3.4.1 誰がどこにログインするか書こう 3.4.2 絶対パスで書く 3.4.3 ユーザー、権限周りは事前に確認する 3.4.4 前後の確認は awk, grep, di ff を有効に使う 3.4.5 ダイイングメッセージ性のあるコマンドを使う 3.4.6 手順書を作るシェルを書く
  20. 20. 3.4.1 誰がどこにログインするか書こう ログイン(ログオン)するための情報を書きましょう。 IPアドレス(ホスト名、IPアドレス、IPv6アドレス) プロトコル(telnet、SSH、RDP、etc...) ポート番号 ユーザー名、パスワード ログインするためのアプリケーション(terminal、RDP、teraterm、etc) 間違った端末でオペレーションしないように、ログイン後、hostname , pwd コマンドでオペレーションの場所を確認することをお勧めします。
  21. 21. 3.4.2 絶対パスで書く 操作するファイル、ディレクトリの指定を絶対パスにすることで、history の前 後のコマンドに依存せず、何の作業したか理解がしやすくなります。 cd, cp, touch, mkdir などでパスを指定するときは絶対パス rm -rf とかついうっかり "rm -rf /" とかしちゃうとアレでアレでアレ 例外的に、シェルスクリプト、Python、Ruby、Perl などのプログラムの 実行に関しては相対パスで手順を作成する
  22. 22. 3.4.3 ユーザー、権限周りは事前に確認する 何かと検証環境では、sudo su で root ユーザーになりがち。 
 事前作業や構成管理の段階で、パーミッションの確認をした上で手順書を書きま しょう。 ls -ltr ¦ grep "<対象の絶対パス>" で権限を確認し、手順書へ反映します。 手順書のコマンドの行頭に$#を手順書内に書たりします。 必要に応じて、シェルスクリプトには chmod +x XXX.sh とかしましょう。 特に手順でシェルを実行するコマンドの場合は、事前に本番環境のユーザー・グ ループ・パーミッションすべて確認しておく方が無難です。
  23. 23. 3.4.4 前後の確認は awk, grep, diff を有効に使う 作業後の効果確認には、cat, di ff , grep -o, awk -F "区切り文字" '{print $X}'  などで、変更の確認するのがベター。 
 よほど複雑じゃない限り、目grep でも良い気がする
  24. 24. 3.4.5 ダイイングメッセージ性のあるコマンドを使う Vim, Emacs, Nano 戦争に終止符を打とう エディタで開いて設定ファイルなどを編集すると、history しても、何をどのように変更し たか分からなくなる。 
 基本的には sed, echo, touchなどにリダイレクト繋げて、コマンドにして手順書を書く。 docker コンテナの中の操作も1行のコマンドで行うようにしました。 
 インフラ設計として、ホストのディレクトリをマウントする設計に変えた方が良い気がして いますが、本番で動いているものを変更するのは難しいので、運用でカバー。 $ docker exec -it web cat /etc/nginx/nginx.conf ¦ grep "worker_processes" worker_processes 1; $
  25. 25. 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 
 1.4 差分の確認 $ di ff 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*
  26. 26. 3.4.6 手順書を作るシェルを書く 定型作業に近い状態であれば、他人が手順書を同じように書くのは不可能か つ非効率なので、シェルスクリプトで手順書が出力されるように書く。 
 最近、同僚のロシア人に入力を、ハードコーディングしないで、変数の入力 は、インタラクティブにした方がいいよと指南された。いいマサカリ。
  27. 27. Tips
  28. 28. Tips1: よく使うショートカットキー • Linux • ctrl + l 画面をきれいにする • ctrl + r コマンドの履歴を出す(ctrl + n , ctrl + p ) • ctrl + a 行頭へ移動 • ctrl + e 行末へ移動 • ctrl + c プロセスを強制終了させる • Windows • Windows キー + R でファイル名を指定して実行を起動 • control 入力 コントロールパネル起動 • mstsc 入力 リモートデスクトップ起動 • cmd 入力 コマンドプロンプト起動
  29. 29. Tips2: 積極的に使っていきたいショートカットキー • Linux(bind -p で一覧が表示されるらしい。ほんまか?) • ctrl + u カーソル位置から行頭まで削除 • ctrl + k カーソル位置から行末まで削除 • ctrl + w カーソル位置の単語を削除 • ctrl + y 直前に削除した文字列を貼り付け • ctrl + z 処理を一時中断 • esc + f 一単語前へ移動 • esc + b 一単語後ろへ移動
  30. 30. Tips3: 良く使うコマンド sed , touch , echo にリダイレクト( > とか >> ) 闇に放り込む(/dev/null) 順番に並べて、値をまとめて、さらに順番に並べる( sort ¦ uniq ¦ sort ) bash で for 文で数値演算してたら awk に書き換える 最近知ったけど nohup XXXX & で ssh セッション切れてもバックグラウンドで実行(バッチ処理と かに便利) 複数行まとめて文字置換するときに perl を一時期使っていた for 文をワンライナーで、 for fi le in `ls -1` ; do echo $ fi le ; done 的なことはよくやる grep は偉大
  31. 31. FYI:Ansibleはありか?なしか? 手順書としてはあり/ 引継資料としてはなし 
 引継資料として playbook のみを渡されたら、何を意図してコマンドが実施 されたかが不明になるため、ドキュメントが別途必要になる認識です。
  32. 32. FYI:メンテナンスアナウンス サービスを利用している人たちにメンテナンスやりますよ!と予告することが一 般的だと思います。 ここは技術関係ないところなので、フォーマットを先に作って組織内で決まっ た形を作っていると揉めることが減ります。
  33. 33. おしまい
  34. 34. • 以下の素材やスライドデザインを参考にしました。 • プレゼンテーション用アイコン(yuyarinさん) 
 https://github.com/yuyarin/presentation_icons 
 • 運用自動化、不都合な真実(波田野さん) 
 https://speakerdeck.com/opelab/20171212-automation • スペシャルサンクス
  • HotakaNoda

    May. 22, 2021
  • syuichitsuji

    May. 21, 2021
  • ssuserd84216

    May. 21, 2021
  • masahitofujishima

    May. 21, 2021
  • YujiOkazawa

    May. 21, 2021

手順書の書き方

Vues

Nombre de vues

3 640

Sur Slideshare

0

À partir des intégrations

0

Nombre d'intégrations

754

Actions

Téléchargements

13

Partages

0

Commentaires

0

Mentions J'aime

5

×