Upgrade to Pro — share decks privately, control downloads, hide ads and more …

文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~

A2a7a8a59c8b67c1369cc3c6be33c37c?s=47 Kei Terui
June 23, 2022

文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~

Cloud Operator Days Tokyo 2022
文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~ 

A2a7a8a59c8b67c1369cc3c6be33c37c?s=128

Kei Terui

June 23, 2022
Tweet

Other Decks in Business

Transcript

  1. 1 1 文書作成ソフトからの脱却 
 ~Markdownによるアラート対応手順書CI/CD~
 株式会社ハートビーツ MSP事業部
 照井 渓(@teru_kei)
 2022/05

    @ CODT2022

  2. 2 2 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに

  3. 3 3 自己紹介
 • Terui Kei / 照井 渓
 –

    @teru_kei
 • 株式会社ハートビーツ
 – 2020年11月 入社
 – MSP事業部 エンジニアリンググループ

  4. 4 4 株式会社ハートビーツ
 • 2005年創業
 • 80名規模、エンジニア率80%以上
 – MSP事業
 •

    インフラ運用のアウトソーサー
 • 監視、設計、構築
 • クラウド導入支援、コンサルティング
 – 開発事業

  5. 5 5 ご紹介:MSP事業 提供サービス
 ★ 監視一次対応サービス
 ★ マネージドサービス
 


  6. 6 6 ご紹介:MSP事業 提供サービス
 ★ 監視一次対応サービス
 ★ マネージドサービス
 
 「監視仕様書」


    を作成・提供

  7. 7 7 ご紹介:監視仕様書って?
 ❖ 下記のような内容の文書
 ▪ アラート対応手順
 ▪ アラート発生時の対応フロー
 ▪

    監視対象のサーバ・リソースの一覧
 ▪ 監視項目の一覧
 ▪ 弊社・お客様の連絡窓口情報
 ▪ ネットワーク・アプリケーションの構成図 などなど

  8. 8 8 お詫び:本セッションの題名について
 文書作成ソフトからの脱却
 ~Markdownによるアラート対応手順書CI/CD~
 と題名をつけておりますが……
 実際には「アラート対応手順書」を内包している、
 「監視仕様書」の CI/CD についてお話します🙇


  9. 9 9 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  10. 10 10 監視仕様書が
 自動生成されるようになって
 最高
 結論


  11. 11 11 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  12. 12 12 動機1
 • 以前は、監視仕様書をWordで作成していた
 – 全て手作業で対応する為、作成・更新が大変
 • 新規作成の際はテンプレートから手入力で作成
 •

    Wordはコード化が難しく、自動化しづらい

  13. 13 13 動機2
 • 以前は、監視仕様書をWordで作成していた
 – OSに依存なく編集可能にしたい
 • ハートビーツでは、社員の端末OS選択が自由
 •

    WordはWindowsに最適化されている
 • Mac/Linux環境でフォーマットが崩れる問題

  14. 14 14 動機3
 • 以前は、監視仕様書をWordで作成していた
 – バックアップ運用をやめ、バージョン管理したい
 • バックアップファイルが共有ドライブを圧迫
 •

    更新履歴を目で追うのが大変
 – diff でチェックできるようにしたい

  15. 15 15 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  16. 16 16 実現に向けた動き
 • 社内GitLab上にあるプロジェクト「hb-zatsu」
 – みんなで「雑なアイデアを共有する場」として存在
 – Issueに仕様書手書き作成の辛さが書き込まれる
 –

    30環境同時受注が発生、手作業での限界感強まる
 • 有志6名によるタスクフォースチーム結成

  17. 17 17 実現に向けた動き
 • 目標:手作業によるWord文書更新から脱却する!
 – Markdown で書いて Git で管理したい


    – Word仕様書に遜色ない内容で PDF 出力したい
 • 2ヶ月程でMarkdown仕様書生成システムを作成
 • 半年ほどかけて半自動生成の機能が追加され完成

  18. 18 18 Markdown仕様書生成システム名
 Kinjiro 


  19. 19 19 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  20. 20 20 使用ツール
 ➔ Markdown
 ➔ Gitlab
 ◆ Gitlab CI/CD


    ➔ Docker
 ➔ Mkdocs
 ◆ HEARTBEATS Flavored Markdown extension(hbfm)
 ➔ wkhtmltopdf
 ➔ Jenkins

  21. 21 21 CI/CD ワークフロー図


  22. 22 22 CI/CD ワークフロー図
 HTMLライブプレビューを 見ながら
 Markdownを書く
 GitにpushされるとGitLab CIが発動 Docker上でビルドが実行され


    PDFが生成される
 JenkinsをKick
 PDFを
 Google Driveにデプロイ

  23. 23 23 再掲:監視仕様書って?
 ❖ 下記のような内容の文書
 ▪ アラート対応手順
 ▪ アラート発生時の対応フロー
 ▪

    監視対象のサーバ・リソースの一覧
 ▪ 監視項目の一覧
 ▪ 弊社・お客様の連絡窓口情報
 ▪ ネットワーク・アプリケーションの構成図 などなど

  24. 24 24 再掲:監視仕様書って?
 ❖ 下記のような内容の文書
 ▪ アラート対応手順
 ▪ アラート発生時の対応フロー
 ▪

    監視対象のサーバ・リソースの一覧
 ▪ 監視項目の一覧
 ▪ 弊社・お客様の連絡窓口情報
 ▪ ネットワーク・アプリケーションの構成図 などなど
 脱Wordしたけど
 Markdownの
 手書きも大変!
 自動生成したい!

  25. 25 25 仕様書自動生成システム名
 Kinjiro Generator 


  26. 26 26 Kinjiro Generator のざっくりした仕組み
 1. 案件コードをフォームに入力
 2. 必要なアラート対応手順をチェックボックスで選択
 3.

    生成ボタンを押下
 4. 案件データベースと監視ツールAPIから情報取得
 5. 監視対象サーバと監視項目の一覧を取得
 6. 監視仕様書全体のMarkdownが生成される

  27. 27 27 Kinjiro Generator の WebUI の様子
 OSやミドルウェアを選択するだけでMarkdownが生 成できる!!

  28. 28 28 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  29. 29 29 ビフォーアフター
 
 Before
 After
 フォーマット
 Word
 Markdown
 新規作成


    テンプレートを複製
 大半を自動生成
 更新方法
 共有ドライブ上で更新
 gitにpush
 更新管理
 バックアップ堆積
 gitでバージョン管理
 書面のPDF化
 保存時にPDFを選択
 CI/CDで自動生成
 
 つらい
 最高

  30. 30 30 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  31. 31 31 苦労話
 ★ 当初のPDFは、かなり寂しい見た目をしていた
 ◦ Wordに遜色ない表現力を持たせるのに苦労した
 ◦ 「Markdown文書」と「出力されるPDF」の乖離
 ◦

    Wordの偉大さも改めて感じた

  32. 32 32 苦労話
 ★ 地道な調整によって見た目を整えていった
 ◦ Mkdocsを使用してhtmlの表現力を借りる
 ▪ css調整、改ページのルール作成 etc…


    ▪ その中で hbfm が産まれた

  33. 33 33 表現力アップのために
 ★ HEARTBEATS Flavored Markdown extension(hbfm)
 ◦ 弊社ハートビーツにて作成


    ◦ Markdown 側で使用可能な記法を追加
 ◦ Mkdocs に組み込んで使用
 ◦ GitHub、PyPI で公開

  34. 34 34 表現力アップのために
 ★ HEARTBEATS Flavored Markdown extension(hbfm) 
 ◦

    文字色指定 機能
 ◦ 相互参照 機能
 ◦ 表内リスト 機能

  35. 35 35 表現力アップのために
 ★ hbfmは何故必要だったか?
 ◦ お客様にとっての可読性向上
 ◦ 運用チームにとっての可読性向上
 ▪

    運用チームは監視仕様書を手順書として使う
 ▪ 作業ミスを起こさない為にも可読性は大切

  36. 36 36 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  37. 37 37 監視仕様書が
 自動生成されるようになって
 最高
 結論


  38. 38 38 あらゆるドキュメントが
 自動生成されるようになれば
 いいのに
 結論


  39. 39 39 文書作成ソフトからの脱却 アジェンダ
 1. 自己紹介
 2. 結論
 3. 動機


    4. 実現に向けた動き
 5. 仕組み
 6. ビフォーアフター
 7. 苦労話
 8. 再度結論
 9. おわりに 

  40. 40 40 おわりに
 紹介した事例についてご興味ある方は
 弊社ハートビーツまでお問い合わせください🤝
 
 ★ HEARTBEATS Flavored Markdown

    extension 公開中
 ◦ https://github.com/heartbeatsjp/markdown-extension-hbfm

  41. 41 41 ご清聴頂きありがとうございました🙇