運用ドキュメントの構造化(案)
16 likes3,938 views
議論の叩き台資料のため、逐次更新予定です。 (完成度は低いです。ご了承ください。)
![Operation Lab
運用設計ラボ
ドキュメントテーマによる価値 (仮説)
activity活動
変化
状
態
• 反復・再利用性の高いドキュメント(資産性ドキュメント)。
• 「変化」「活動」の起点・終点となる最も重要なドキュメント
• 何らかの形で売却できる場合「収益性」があると言える。
• 反復作成されるが再利用はしにくい。(費用性ドキュメント)
• 「運用の費用対効果」を説明するためのドキュメントとなるた
め「収益性」があると考えることもできる。
• 「活動」の蓄積が変化を生む。
• [留意]「変化させない事」が重要とされる業務もある。
• 反復作成されるが再利用はしにくい。(費用性ドキュメント)
• コストが直接配賦されれば「収益性」があるが、共通配賦され
る場合は、作成自体が「運用コスト」と評価される。
What
何を書く?
出典: Internet Week 2011 「運用ドキュメント2011 ∼手軽にスピーディに継続的に保守するためのツール入門」 Part-1
Quality
Delivery
Cost
Qualityの向上
Deliveryの改善
活動=Cost](https://image.slidesharecdn.com/20140622-structure-document-140622012920-phpapp02/85/-5-320.jpg)
運用ドキュメントの構造化(案)
- 1. Operation Lab 運用設計ラボ 運用ドキュメントの構造化(案) 運用設計ラボ合同会社 シニアアーキテクト 波田野 裕一 2014-06-22 メモ書き第2版 議論の叩き台につき未完成 (適宜更新予定)
- 2. Operation Lab 運用設計ラボ 主張: クラウド時代の運用ドキュメンテーション • WhatやHowはコード(Infrastructure As Code)に残るが、Whyは人 が自らドキュメントに書かなければ残らない。 • クラウド時代になって、オンプレミスと比較してあらゆる制約が減少。 制約が無い中で「なぜそうしたか(Why)」を残す重要性が増加。 • 人(Why)とシステム(What/How)が分担してドキュメントを書く時代。 How + Why = KnowHow 実装 設計 運用現場の資産 出典: JAWS-UG東京第22回勉強会「運用自動化時代のドキュメンテーショント」 (2014-06)
- 4. Operation Lab 運用設計ラボ ドキュメントテーマの3類型 時間軸 activity活動 状 態 変化後 変化 変化前 What 何を書く? SCA分析 (仮称) ‣Status(状態) ‣Change(変化) ‣Activity (活動) 出典: Internet Week 2011 「運用ドキュメント2011 ∼手軽にスピーディに継続的に保守するためのツール入門」 Part-1
- 5. Operation Lab 運用設計ラボ ドキュメントテーマによる価値 (仮説) activity活動 変化 状 態 • 反復・再利用性の高いドキュメント(資産性ドキュメント)。 • 「変化」「活動」の起点・終点となる最も重要なドキュメント • 何らかの形で売却できる場合「収益性」があると言える。 • 反復作成されるが再利用はしにくい。(費用性ドキュメント) • 「運用の費用対効果」を説明するためのドキュメントとなるた め「収益性」があると考えることもできる。 • 「活動」の蓄積が変化を生む。 • [留意]「変化させない事」が重要とされる業務もある。 • 反復作成されるが再利用はしにくい。(費用性ドキュメント) • コストが直接配賦されれば「収益性」があるが、共通配賦され る場合は、作成自体が「運用コスト」と評価される。 What 何を書く? 出典: Internet Week 2011 「運用ドキュメント2011 ∼手軽にスピーディに継続的に保守するためのツール入門」 Part-1 Quality Delivery Cost Qualityの向上 Deliveryの改善 活動=Cost
- 6. Operation Lab 運用設計ラボ 6つのドキュメント要素 activity活動 変化 状 態 /activity.rst /change.rst /define/ 人による活動情報 人による変化情報 • ドキュメントを利用する活動のト ラッカー • ドキュメント自体のトラッカ (更 新、要望) • 変化(実績)レポート (外部) • ドキュメントのリポジトリ(web) 人による状態情報 費用性ドキュメント 収益性ドキュメント 資産性ドキュメント バージョン管理の対象 システムの状態情報 システムによる随時更新 実装 設計 Why What How 「振り返り」(顧客レポートや考課に活用) 「事業継続性」「再現性」「反復性」などの基盤 システムの変化情報システムの活動情報 インクルード対象 インクルード対象 インクルード対象 • ログ • アラート • MRTG/DDR • CloudWatch • CloudFormation • OpsWorks (Chef) • AMI情報、など 「説明責任」(証拠、エビデンス) Quality Delivery Cost インクルード対象 QCD(F)のための基礎情報 議論ポイント 議論ポイント 議論ポイント
- 8. Operation Lab 運用設計ラボ 余談: サービスの立ち位置 (「設計」の最上位) ミッション ポリシー サービス 理想 制約 現実的な落しどころ ここまで書けるか? /define/mission /define/policy /define/service 対立
- 9. Operation Lab 運用設計ラボ サービス サービス運用アーキテクチャの全体像 (仮説) 作 業 カ タ ロ グ サ ー ビ ス カ タ ロ グ リソースカタログ 運用フロー ライブラリ 情報 要員 予算 OperatorUser 人による状態情報
- 10. Operation Lab 運用設計ラボ 「人による状態情報」ドキュメント構造 /define/service/ service-catalog/ ユーザが利用する公式情報 resource-catalog/ work-catalog/ サービスカタログ 作業カタログリソースカタログ リソースに関する公式情報 運用現場が利用する情報 インクルード インクルード • 第1レベル: リソース別 • 第2レベル: 利用形態別 • API • CLI • WebUIなど 運用フロー ライブラリ インクルードインクルード lib/
- 12. Operation Lab 運用設計ラボ 「システムによる状態情報」ドキュメント構造 /define/service/resource-catalog/automation/(シンボリックリンク) • 単体構成情報 (JSON、ソースコードなど) • 単体定義情報 (replace定義など) • 関係情報 (定義間の関係、構成間の関係) • ディレクトリ構成 • 第一レベル: リソース別 (プロダクト毎) • 第二レベル: 取得方法別 (API/CLI/WebUI) システムによる随時自動更新 議論ポイント
- 13. Operation Lab 運用設計ラボ 人による変化情報の構造 変化 人による変化情報 • 変化(実績)レポート (外部) • ドキュメントのリポジトリ(web) 「振り返り」(顧客レポートや考課に活用) ヒトによる収益性ドキュメント Quality Delivery
- 14. Operation Lab 運用設計ラボ 「人による変化情報」ドキュメント構造 /change.rst 人による変化情報 • 変化(実績)レポート (外部) • ドキュメントのリポジトリ(web) 「振り返り」(顧客レポートや考課に活用)
- 15. Operation Lab 運用設計ラボ システムの変化情報の構造 変化 「振り返り」(顧客レポートや考課に活用) システムの変化情報 インクルード対象 • MRTG/DDR • CloudWatch システムによる収益性ドキュメント Quality Delivery 議論ポイント
- 17. Operation Lab 運用設計ラボ 人による活動情報の構造 • ドキュメントを利用する活動のト ラッカー • ドキュメント自体のトラッカ (更 新、要望) activity活動 /activity.rst 人による活動情報 「説明責任」(証拠、エビデンス) ヒトによる費用性ドキュメント Cost
- 18. Operation Lab 運用設計ラボ • ドキュメントを利用する活動のトラッカー • ドキュメント自体のトラッカ (更新、要望) 「説明責任」(証拠、エビデンス) 「人による活動情報」ドキュメント構造 /activity.rst 人による活動情報
- 19. Operation Lab 運用設計ラボ システムの活動情報の構造 activity活動 /activity.rst システムの活動情報 インクルード対象 • ログ • アラート 「説明責任」(証拠、エビデンス) システムによる費用性ドキュメント Cost 議論ポイント
- 20. Operation Lab 運用設計ラボ システムの活動情報 •ログ •アラート •PullRequestでのレビュー •実際のtaskでの説明 (資産性の可能性あり) 「説明責任」(証拠、エビデンス) 「システムの活動情報」ドキュメント構造 インクルード対象外部ドキュメント 議論ポイント
- 22. Operation Lab 運用設計ラボ 運用ドキュメントのマップ • /define/ • mission/ • policy/ • service/ • service-catalog/ (ユーザ向けメニュー) • work-catalog/ (運用現場向けメニュー) • resource-catalog/ (API/CLI/WebUIなどのリファレンス) • プロダクト別ドキュメント • automation/ (外部情報へのシンボリックリンク) • lib/ (手順パーツ、スクリプト、関数、ライブラリ) • /activity.rst • /change.rst • /words.rst (用語定義)
- 23. Operation Lab 運用設計ラボ プロダクトドキュメントのマップ • /define/ • work-catalog/ (運用現場向けメニュー) • resource-catalog/ • (API/CLI/WebUIなどのリファレンス) • automation/ (外部情報へのシンボリックリンク) • lib/ (手順パーツ、スクリプト、関数、ライブラリ) • /activity.rst • /change.rst • /words.rst (用語定義)
- 25. Operation Lab 運用設計ラボ memo • プロダクト単体のドキュメントについては、このモデル のサブセット&独立リポジトリで疎結合ドキュメンテー ションを実現するべき • ドキュメントのtopレベル • resource-catalog(リファレンス/マニュアル) • work-catalog(作業手順) • lib(自動化ライブラリ)