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

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

2 2 文書作成ソフトからの脱却アジェンダ  1. 自己紹介  2. 結論  3. 動機 
4. 実現に向けた動き  5. 仕組み  6. ビフォーアフター  7. 苦労話  8. 再度結論  9. おわりに 

3 3 自己紹介  • Terui Kei / 照井渓  –
@teru_kei  • 株式会社ハートビーツ  – 2020年11月入社  – MSP事業部エンジニアリンググループ 

4 4 株式会社ハートビーツ  • 2005年創業  • 80名規模、エンジニア率80%以上  – MSP事業  •
インフラ運用のアウトソーサー  • 監視、設計、構築  • クラウド導入支援、コンサルティング  – 開発事業 

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

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

7 7 ご紹介：監視仕様書って？  ❖ 下記のような内容の文書  ▪ アラート対応手順  ▪ アラート発生時の対応フロー  ▪
監視対象のサーバ・リソースの一覧  ▪ 監視項目の一覧  ▪ 弊社・お客様の連絡窓口情報  ▪ ネットワーク・アプリケーションの構成図　などなど 

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

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

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

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

13 13 動機２  • 以前は、監視仕様書をWordで作成していた  – OSに依存なく編集可能にしたい  • ハートビーツでは、社員の端末OS選択が自由  •
WordはWindowsに最適化されている  • Mac/Linux環境でフォーマットが崩れる問題 

14 14 動機３  • 以前は、監視仕様書をWordで作成していた  – バックアップ運用をやめ、バージョン管理したい  • バックアップファイルが共有ドライブを圧迫  •
更新履歴を目で追うのが大変  – diff でチェックできるようにしたい 

16 16 実現に向けた動き  • 社内GitLab上にあるプロジェクト「hb-zatsu」  – みんなで「雑なアイデアを共有する場」として存在  – Issueに仕様書手書き作成の辛さが書き込まれる  –
30環境同時受注が発生、手作業での限界感強まる  • 有志6名によるタスクフォースチーム結成 

17 17 実現に向けた動き  • 目標：手作業によるWord文書更新から脱却する！  – Markdown で書いて Git で管理したい 
– Word仕様書に遜色ない内容で PDF 出力したい  • 2ヶ月程でMarkdown仕様書生成システムを作成  • 半年ほどかけて半自動生成の機能が追加され完成 

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

20 20 使用ツール  ➔ Markdown  ➔ Gitlab  ◆ Gitlab CI/CD 
➔ Docker  ➔ Mkdocs  ◆ HEARTBEATS Flavored Markdown extension（hbfm）  ➔ wkhtmltopdf  ➔ Jenkins 

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

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

23 23 再掲：監視仕様書って？  ❖ 下記のような内容の文書  ▪ アラート対応手順  ▪ アラート発生時の対応フロー  ▪
監視対象のサーバ・リソースの一覧  ▪ 監視項目の一覧  ▪ 弊社・お客様の連絡窓口情報  ▪ ネットワーク・アプリケーションの構成図　などなど 

24 24 再掲：監視仕様書って？  ❖ 下記のような内容の文書  ▪ アラート対応手順  ▪ アラート発生時の対応フロー  ▪
監視対象のサーバ・リソースの一覧  ▪ 監視項目の一覧  ▪ 弊社・お客様の連絡窓口情報  ▪ ネットワーク・アプリケーションの構成図　などなど  脱Wordしたけど  Markdownの  手書きも大変！  自動生成したい！ 

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

26 26 Kinjiro Generator のざっくりした仕組み  1. 案件コードをフォームに入力  2. 必要なアラート対応手順をチェックボックスで選択  3.
生成ボタンを押下  4. 案件データベースと監視ツールAPIから情報取得  5. 監視対象サーバと監視項目の一覧を取得  6. 監視仕様書全体のMarkdownが生成される 

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

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

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

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

33 33 表現力アップのために  ★ HEARTBEATS Flavored Markdown extension（hbfm）  ◦ 弊社ハートビーツにて作成 
◦ Markdown 側で使用可能な記法を追加  ◦ Mkdocs に組み込んで使用  ◦ GitHub、PyPI で公開 

34 34 表現力アップのために  ★ HEARTBEATS Flavored Markdown extension（hbfm）   ◦
文字色指定機能  ◦ 相互参照機能  ◦ 表内リスト機能 

35 35 表現力アップのために  ★ hbfmは何故必要だったか？  ◦ お客様にとっての可読性向上  ◦ 運用チームにとっての可読性向上  ▪
運用チームは監視仕様書を手順書として使う  ▪ 作業ミスを起こさない為にも可読性は大切 

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

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

40 40 おわりに  紹介した事例についてご興味ある方は  弊社ハートビーツまでお問い合わせください🤝    ★ HEARTBEATS Flavored Markdown
extension 公開中  ◦ https://github.com/heartbeatsjp/markdown-extension-hbfm 

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

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

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

Other Decks in Business

Featured

Transcript

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

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