運用ドキュメントの構造化(案)

Operation Lab運用設計ラボ

運用ドキュメントの構造化(案)運用設計ラボ合同会社シニアアーキテクト波田野裕一

2014-06-22 メモ書き第2版

議論の叩き台につき未完成 (適宜更新予定)


主張: クラウド時代の運用ドキュメンテーション

• WhatやHowはコード(Infrastructure As Code)に残るが、Whyは人が自らドキュメントに書かなければ残らない。

• クラウド時代になって、オンプレミスと比較してあらゆる制約が減少。制約が無い中で「なぜそうしたか(Why)」を残す重要性が増加。

• 人(Why)とシステム(What/How)が分担してドキュメントを書く時代。

How + Why = KnowHow実装設計運用現場の資産

出典: JAWS-UG東京第22回勉強会「運用自動化時代のドキュメンテーショント」 (2014-06)


価値基準によるドキュメントの構造


ドキュメントテーマの3類型

時間軸 activity活動

状態

変化後

変化

変化前

What何を書く?

SCA分析 (仮称)

‣Status(状態)

‣Change(変化)

‣Activity (活動)

出典: Internet Week 2011 「運用ドキュメント2011 ～手軽にスピーディに継続的に保守するためのツール入門」 Part-1


ドキュメントテーマによる価値 (仮説)

activity活動

変化

状態

• 反復・再利用性の高いドキュメント(資産性ドキュメント)。 • 「変化」「活動」の起点・終点となる最も重要なドキュメント • 何らかの形で売却できる場合「収益性」があると言える。

• 反復作成されるが再利用はしにくい。(費用性ドキュメント) • 「運用の費用対効果」を説明するためのドキュメントとなるため「収益性」があると考えることもできる。

• 「活動」の蓄積が変化を生む。 • [留意]「変化させない事」が重要とされる業務もある。

• 反復作成されるが再利用はしにくい。(費用性ドキュメント) • コストが直接配賦されれば「収益性」があるが、共通配賦される場合は、作成自体が「運用コスト」と評価される。

What何を書く?

出典: Internet Week 2011 「運用ドキュメント2011 ～手軽にスピーディに継続的に保守するためのツール入門」 Part-1

QualityDelivery

Cost

Qualityの向上Deliveryの改善

活動=Cost


6つのドキュメント要素

activity活動変化状態

/activity.rst /change.rst /define/人による活動情報人による変化情報

• ドキュメントを利用する活動のトラッカー

• ドキュメント自体のトラッカ (更新、要望)

• 変化(実績)レポート (外部) • ドキュメントのリポジトリ(web)

人による状態情報

費用性ドキュメント収益性ドキュメント資産性ドキュメント

バージョン管理の対象

システムの状態情報

システムによる随時更新

実装

設計 Why

WhatHow

「振り返り」(顧客レポートや考課に活用) 「事業継続性」「再現性」「反復性」などの基盤

システムの変化情報システムの活動情報

インクルード対象インクルード対象インクルード対象

• ログ • アラート

• MRTG/DDR • CloudWatch

• CloudFormation • OpsWorks (Chef) • AMI情報、など

「説明責任」(証拠、エビデンス)

QualityDelivery

Cost

インクルード対象

QCD(F)のための基礎情報

議論ポイント議論ポイント議論ポイント


運用ドキュメントの構造

状態


バージョン管理の対象

設計 Why

ヒトによる資産性ドキュメント


余談: サービスの立ち位置 (「設計」の最上位)

ミッションポリシー

サービス

理想制約

現実的な落しどころ

ここまで書けるか?

/define/mission /define/policy

/define/service

対立


サービス

サービス運用アーキテクチャの全体像 (仮説)

作業カタログ

サービスカタログ

リソースカタログ

運用フローライブラリ

情報要員予算

OperatorUser



「人による状態情報」ドキュメント構造/define/service/

service-catalog/

ユーザが利用する公式情報resource-catalog/ work-catalog/

サービスカタログ作業カタログリソースカタログ

リソースに関する公式情報運用現場が利用する情報

インクルードインクルード• 第1レベル: リソース別 • 第2レベル: 利用形態別

• API • CLI • WebUIなど

運用フローライブラリ

インクルードインクルードlib/


システムの状態情報の構造

状態

システムの状態情報

システムによる随時更新

実装 WhatHow

システムによる資産性ドキュメント

議論ポイントインクルード対象


「システムによる状態情報」ドキュメント構造/define/service/resource-catalog/automation/(シンボリックリンク)

• 単体構成情報 (JSON、ソースコードなど) • 単体定義情報 (replace定義など) • 関係情報 (定義間の関係、構成間の関係)

• ディレクトリ構成 • 第一レベル: リソース別 (プロダクト毎) • 第二レベル: 取得方法別 (API/CLI/WebUI)

システムによる随時自動更新議論ポイント


人による変化情報の構造

変化人による変化情報

• 変化(実績)レポート (外部) • ドキュメントのリポジトリ(web)

「振り返り」(顧客レポートや考課に活用)

ヒトによる収益性ドキュメント

QualityDelivery


「人による変化情報」ドキュメント構造/change.rst

人による変化情報• 変化(実績)レポート (外部) • ドキュメントのリポジトリ(web)



システムの変化情報の構造

変化


システムの変化情報


• MRTG/DDR • CloudWatch

システムによる収益性ドキュメント

QualityDelivery

議論ポイント



システムの変化情報


•MRTG/DDR •CloudWatch

「システムの変化情報」ドキュメント構造外部ドキュメント

議論ポイント


人による活動情報の構造

• ドキュメントを利用する活動のトラッカー

• ドキュメント自体のトラッカ (更新、要望)

activity活動

/activity.rst

人による活動情報


ヒトによる費用性ドキュメント

Cost


• ドキュメントを利用する活動のトラッカー • ドキュメント自体のトラッカ (更新、要望)


「人による活動情報」ドキュメント構造/activity.rst

人による活動情報


システムの活動情報の構造

activity活動

/activity.rst

システムの活動情報


• ログ • アラート


システムによる費用性ドキュメント

Cost

議論ポイント


システムの活動情報 •ログ •アラート •PullRequestでのレビュー •実際のtaskでの説明 (資産性の可能性あり)


「システムの活動情報」ドキュメント構造インクルード対象外部ドキュメント

議論ポイント


ドキュメントマップ


運用ドキュメントのマップ• /define/

• mission/ • policy/ • service/

• service-catalog/ (ユーザ向けメニュー) • work-catalog/ (運用現場向けメニュー) • resource-catalog/ (API/CLI/WebUIなどのリファレンス)

• プロダクト別ドキュメント • automation/ (外部情報へのシンボリックリンク)

• lib/ (手順パーツ、スクリプト、関数、ライブラリ) • /activity.rst • /change.rst • /words.rst (用語定義)


プロダクトドキュメントのマップ• /define/

• work-catalog/ (運用現場向けメニュー) • resource-catalog/

• (API/CLI/WebUIなどのリファレンス) • automation/ (外部情報へのシンボリックリンク)

• lib/ (手順パーツ、スクリプト、関数、ライブラリ) • /activity.rst • /change.rst • /words.rst (用語定義)


memo


memo• プロダクト単体のドキュメントについては、このモデルのサブセット&独立リポジトリで疎結合ドキュメンテーションを実現するべき

• ドキュメントのtopレベル • resource-catalog(リファレンス/マニュアル) • work-catalog(作業手順) • lib(自動化ライブラリ)


http://www.operation-lab.co.jp/

http://www.operation-lab.co.jp/

Engineering

運用ドキュメントの構造化(案)