From 9e7fa2d02f27e33b4b9c421efeb69ed52d58480c Mon Sep 17 00:00:00 2001 From: Oleg Gelbukh Date: Thu, 17 Oct 2013 13:26:28 +0000 Subject: [PATCH] [doc] Improve documentation Cleanup rules engine document Include all documents in the proposal document --- doc/openstack_architecture_model.rst | 3 +- doc/openstack_diagnostics_proposal.rst | 21 ++++++++++--- doc/openstack_integration.rst | 4 +-- doc/rules_engine.rst | 43 ++++++++++---------------- doc/service_architecture.rst | 10 ++++-- 5 files changed, 44 insertions(+), 37 deletions(-) diff --git a/doc/openstack_architecture_model.rst b/doc/openstack_architecture_model.rst index 07aefe9..786c490 100644 --- a/doc/openstack_architecture_model.rst +++ b/doc/openstack_architecture_model.rst @@ -1,5 +1,4 @@ -======================= -ARCHITECTURE DATA MODEL +Architecture Data Model ======================= Overview diff --git a/doc/openstack_diagnostics_proposal.rst b/doc/openstack_diagnostics_proposal.rst index 500cf40..adb0fb9 100644 --- a/doc/openstack_diagnostics_proposal.rst +++ b/doc/openstack_diagnostics_proposal.rst @@ -1,15 +1,18 @@ +============================== OPENSTACK DIAGNOSTICS PROPOSAL ============================== +.. contents:: + Project Name ------------- +============ **Official:** OpenStack Diagnostics **Codename:** Rubick -Overview --------- +OVERVIEW +======== The typical OpenStack cloud life cycle consists of 2 phases: @@ -90,5 +93,13 @@ TripleO Heat and configuration files templates). Dependencies ------------ -Design ------- +DESIGN +====== + +.. include:: service_architecture.rst + +.. include:: rules_engine.rst + +.. include:: openstack_integration.rst + +.. include:: openstack_architecture_model.rst diff --git a/doc/openstack_integration.rst b/doc/openstack_integration.rst index 44699f1..82d2c78 100644 --- a/doc/openstack_integration.rst +++ b/doc/openstack_integration.rst @@ -1,5 +1,5 @@ -DIAGNOSTICS INTEGRATION WITH OPENSTACK -====================================== +Integration with OpenStack +========================== ------------------------------------- Integration with OpenStack Deployment diff --git a/doc/rules_engine.rst b/doc/rules_engine.rst index 7878fba..976c700 100644 --- a/doc/rules_engine.rst +++ b/doc/rules_engine.rst @@ -1,32 +1,11 @@ -PRODUCTION RULES ENGINE +Production Rules Engine ======================= This document describes rules engine used for inspection and diagnostics of OpenStack configuration. ----------------- -Proposal Summary ----------------- - -With this proposal we want to introduce a project aimed to enhance and simplify -operatinal maintenance of OpenStack cloud. Project provides service which uses -rule-based engine to inspect configurations of OpenStack -platform and find all kinds of architecture- and configuration-level glitches -and inconsistencies. - -*# describe motivation behind rules -# describe rules reuse -# desribe rule-based inspection -# example rule -# mandatory rules vs. best-practice rules* - -This engine will provide hints and best practices to increase reliability and -operational resilience of the cloud. - -#FIXME: move this part to document rules_engine.rst - -Rules-based approach to diagnostics ------------------------------------ +Summary +------- The consistent configuration across all components is essential to OpenStack cloud operation. If something is wrong with configuration, you as an operator @@ -40,8 +19,20 @@ rules to be operational. On the other hand, if you know rules which your configuration breaks, you can identify incorrect parameters reliably and easy. That is how production rules or diagnostic systems work. +Example production rule +----------------------- + Example production rule for OpenStack system could be:: - if (condition)parameter) is (value) then (check_parameter_1) must be (value) and - (check_parameter_2) must be (value) + Given (condition_parameter_1) is (value) and + (condition_parameter_2) is (value) + then (check_parameter_1) must be (value) +Rule-based inspection +--------------------- + +Store and reuse rules +--------------------- + +Sanity checks vs best practices +------------------------------- diff --git a/doc/service_architecture.rst b/doc/service_architecture.rst index 9e9b450..ecc1d31 100644 --- a/doc/service_architecture.rst +++ b/doc/service_architecture.rst @@ -1,5 +1,11 @@ -=================== -RUBICK ARCHITECTURE +Design & Architecture =================== +This section describes design and architecture of OpenStack Diagnostics (Rubik) +service. + +Service includes the following components: + +* + .. image:: images/service_architecture.png