diff --git a/README.rst b/README.rst index 9932b271..286badc1 100644 --- a/README.rst +++ b/README.rst @@ -15,27 +15,27 @@ Application Data Protection as a Service for OpenStack Mission Statement ***************** -* Formalize Application Data Protection in OpenStack (APIs, Services, Plugins, …) -* Be able to protect Any Resource in OpenStack(as well as their dependencies) -* Allow Diversity of vendor solutions, capabilities and implementations - without compromising usability +To protect the Data and Metadata that comprises an OpenStack-deployed +Application against loss/damage (e.g. backup, replication) by providing a +standard framework of APIs and services that allows vendors to provide plugins +through a unified interface Open Architecture """"""""""""""""" Design for multiple perspectives: -* User : Protect App Deployment +* User: Protect App Deployment * Configure and manage custom protection plans on the deployed resources (topology, VMs, volumes, images, …) -* Admin : Define Protectable Resources +* Admin: Define Protectable Resources * Decide what plugins protect which resources, what is available for the user * Decide where users can protect their resources -* Vendors : Standard API for protection products +* Vendors: Standard API for protection products * Create plugins that implement Protection mechanisms for different OpenStack resources diff --git a/doc/images/3-tier-app.png b/doc/images/3-tier-app.png new file mode 100644 index 00000000..a2e654da Binary files /dev/null and b/doc/images/3-tier-app.png differ diff --git a/doc/images/3-tirApp.png b/doc/images/3-tirApp.png deleted file mode 100644 index 4f226e68..00000000 Binary files a/doc/images/3-tirApp.png and /dev/null differ diff --git a/doc/source/index.rst b/doc/source/index.rst index 8b90ac0d..5a134cf7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,15 +1,24 @@ -.. smaug documentation master file, created by - sphinx-quickstart on Tue Jul 9 22:26:36 2013. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +================================== +Smaug: Application Data Protection +================================== -Welcome to smaug's documentation! -======================================================== +Introduction +============ +Smaug is an OpenStack project that provides a pluggable framework for +protecting and restoring Data and Metadata that comprises an OpenStack-deployed +application - Application Data Protection as a Service. -Contents: +Mission Statement +~~~~~~~~~~~~~~~~~ +To protect the Data and Metadata that comprises an OpenStack-deployed +Application against loss/damage (e.g. backup, replication) by providing a +standard framework of APIs and services that allows vendors to provide plugins +through a unified interface +Using Smaug +=========== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 readme installation @@ -18,8 +27,7 @@ Contents: releasenotes Smaug Specs -================= - +=========== .. toctree:: :maxdepth: 1 diff --git a/doc/source/installation.rst b/doc/source/installation.rst index edfa9e0b..4de29943 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,4 +1,70 @@ ============ Installation ============ -TODO Add Installation Guide + +Single-node Devstack Installation +================================= +In order to install Smaug using Devstack on a single node, add the following to +your local.conf, under [[local|localrc]]: + +.. code-block:: none + + enable_plugin smaug http://git.openstack.org/openstack/smaug master + enable_plugin smaug-dashboard http://git.openstack.org/openstack/smaug-dashboard master + enable_service smaug-api + enable_service smaug-operationengine + enable_service smaug-protection + # Smaug Dashboard depends on Horizon + enable_service smaug-dashboard + +Depenencies +=========== + +Heat +~~~~ + +.. code-block:: none + + enable_service h-eng h-api h-api-cfn h-api-cw + +Swift (recommended) +~~~~~~~~~~~~~~~~~~~ + +Essential for the basic protection provider. + +.. code-block:: none + + SWIFT_REPLICAS=1 + SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5 + SWIFT_DATA_DIR=$DEST/data + enable_service s-proxy s-object s-container s-account + +Cinder (optional) +~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + enable_service cinder c-api c-vol c-sch c-bak + +Glance (optional) +~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + enable_service g-api g-reg + +Nova (optional) +~~~~~~~~~~~~~~~ + +.. code-block:: none + + enable_service n-cpu n-api n-crt n-cond n-sch n-novnc n-cauth + + +Neutron (optional) +~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + enable_service neutron q-svc q-agt q-dhcp q-meta + disable_service n-net diff --git a/doc/source/readme.rst b/doc/source/readme.rst index afaac62d..079428f9 100644 --- a/doc/source/readme.rst +++ b/doc/source/readme.rst @@ -1,54 +1,54 @@ -.. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/Smaug.png - :alt: Smaug - :align: center + +============ +Introduction +============ + +.. contents:: :depth: 2 What is Smaug? ============== -Smaug is an OpenStack project that provides a framework for Application -Data Protection as a Service. +Smaug is an OpenStack project that provides a pluggable framework for +protecting and restoring Data and Metadata that comprises an OpenStack-deployed +application - Application Data Protection as a Service. -It is named after the famous dragon from J.R.R. Tolkien's The "Hobbit", -which was known to hoard and guard the treasures of the people. +.. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/Smaug.png + :alt: Smaug + :align: center + :height: 150px -Mission & Scope -=============== +It is named after the famous dragon from J.R.R. Tolkien's The "Hobbit", which +was known to hoard and guard the treasures of the people. -Formalize Application Data Protection and Disaster recovery in OpenStack -(APIs, Services, Plugins ...) +Mission Statement +~~~~~~~~~~~~~~~~~ +To protect the Data and Metadata that comprises an OpenStack-deployed +Application against loss/damage (e.g. backup, replication) by providing a +standard framework of APIs and services that allows vendors to provide plugins +through a unified interface -Be able to protect Any Resource in OpenStack(as well as their -dependencies) - -Allow Diversity of vendor solutions, capabilities and implementations -without compromising usability. Typical Use Case: 3-Tier Cloud App ================================== 3-Tier Cloud App Web/App/DB -.. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/ - 3-tirApp.png +.. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/3-tirApp.png :alt: 3-Tier Cloud App :width: 600 - :height: 455 :align: center -In order to provide full Protection for this typical use case, we would -have to protect many resources, which have some dependency between them. -The following diagram demonstrates how this dependency looks, in the -form of a tree: +In order to provide full Protection for this typical use case, we would have to +protect many resources, which have some dependency between them. The following +diagram demonstrates how this dependency looks, in the form of a tree: -.. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/ - resource_tree_architecture.png +.. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/resource_tree_architecture.png :alt: Resource Tree :width: 600 - :height: 455 :align: center -These resources can be divided into groups, each of which will be -handled by a different plugin in Smaug: +These resources can be divided into groups, each of which will be handled by a +different plugin in Smaug: - Volume - VM @@ -64,6 +64,7 @@ Protection Providers .. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/ protection_provider.png + :width: 600 Protection providers are defined by the administrator for each tenant. The encapsulate every aspect of the protection procedure, namely, where to place @@ -73,14 +74,14 @@ back up data, and restore data. Since there could be many protection providers with varied features and options each protection provider exposes what options it provides for each protectable. -This allows the UI to dynamically adapt to each provider and show the user -what options are available, what they mean and what values are supported. +This allows the UI to dynamically adapt to each provider and show the user what +options are available, what they mean and what values are supported. This allows us to extend the providers without updates to Smaug and allow provider implementation to easily add specialize options. Example -======= +~~~~~~~ Let’s take the OpenStack::Cinder::Volume resource *Protect* action. @@ -151,7 +152,6 @@ High Level Architecture high_level_architecture.png :alt: Solution Overview :width: 600 - :height: 455 :align: center The system is built from independent services and a scalable *Workflow @@ -162,33 +162,37 @@ Smaug API Service .. image:: https://raw.githubusercontent.com/openstack/smaug/master/doc/images/ smaug-api.png + :width: 600 -These top-level north-bound APIs expose Application Data Protection -services to the Smaug user. +These top-level north-bound APIs expose Application Data Protection services to +the Smaug user. -The purpose of the services is to maximize flexibility and accommodate -for (hopefully) any kind of protection for any type of resource, whether -it is a basic OpenStack resource (such as a VM, Volume, Image, etc.) or -some ancillary resource within an application system that is not managed -in OpenStack (such as a hardware device, an external database, etc.). +The purpose of the services is to maximize flexibility and accommodate for +(hopefully) any kind of protection for any type of resource, whether it is a +basic OpenStack resource (such as a VM, Volume, Image, etc.) or some ancillary +resource within an application system that is not managed in OpenStack (such as +a hardware device, an external database, etc.). Resource (Protectable) API --------------------------- -Enables the Smaug user to access information about which resource types are protectable (i.e. can be protected by Smaug). -In addition, enables the user to get additional information on each resource type, such as a list of actual instances and their dependencies. +Enables the Smaug user to access information about which resource types are +protectable (i.e. can be protected by Smaug). In addition, enables the user to +get additional information on each resource type, such as a list of actual +instances and their dependencies. Provider API --------------- -Enables the Smaug user to list available providers and get parameters and result schema super-set for all plugins of a specific Provider. +Enables the Smaug user to list available providers and get parameters and +result schema super-set for all plugins of a specific Provider. Plan API -------- -This API enables the Smaug user to access the protection Plan registry -and do the following operations: +This API enables the Smaug user to access the protection Plan registry and do +the following operations: - Plan CRUD. - List Plans. @@ -206,8 +210,8 @@ This API enables the Smaug user to manage protection Operations: Checkpoint API --------------- -This API enables the Smaug user to access and manage the checkpoints stored -in the protection provider: +This API enables the Smaug user to access and manage the checkpoints stored in +the protection provider: - List all checkpoints given a Bank ID. - Show Information on a given checkpoint ID. @@ -224,17 +228,17 @@ This API enables the Smaug user restore a checkpoint on to a restore target: Smaug Schedule Service ====================== -This subsystem is responsible for scheduling and orchestrating the -execution of *Protection Plans*. +This subsystem is responsible for scheduling and orchestrating the execution of +*Protection Plans*. -The implementation can be replaced by any other external solution since it -uses only functions that are available through the north-bound API. +The implementation can be replaced by any other external solution since it uses +only functions that are available through the north-bound API. Once an entity is created it can be tracked through the north-bound API as well so that monitoring the operations is independent from the scheduler. -It will be responsible for executing the automatic operations to specific -tasks and tracking them. +It will be responsible for executing the automatic operations to specific tasks +and tracking them. Automatic Operation ------------------- @@ -250,11 +254,10 @@ Trigger Engine This sub-component of the Schedule Service is responsible for generating triggers to begin the execution of the Plan Orchestration. -It can be done based on a Timer or an Event Collector - Open to -implementation. +It can be done based on a Timer or an Event Collector - Open to implementation. -In the first version of Smaug reference implementation, it will only -provide time-based triggering. +In the first version of Smaug reference implementation, it will only provide +time-based triggering. Scheduled Operation ------------------- @@ -273,27 +276,26 @@ This subsystem is responsible for handling the following tasks: WorkFlow Engine --------------- -This pluggable component is responsible for executing and orchestrating -the flow of the plan across all protection providers. +This pluggable component is responsible for executing and orchestrating the +flow of the plan across all protection providers. Communication and Meetings ========================== -Smaug Launchpad Link\ https://launchpad.net/smaug - -Smaug Code Review\ https://review.openstack.org/#/q/smaug+status:open,n,z - -Smaug Code Repository\ https://github.com/openstack/smaug - -Smaug daily IRC Channel: #openstack-smaug - -Smaug bi-weekly IRC Meeting on (even) Tuesday at 1400 UTC in #openstack-meeting -at freenode:\ http://eavesdrop.openstack.org/#Smaug_Project_Meetingtion(s). - -Smaug Trello Board\ https://trello.com/b/Sudr4fKT/smaug +- Smaug Launchpad Link: \ https://launchpad.net/smaug +- Smaug Code Review: \ https://review.openstack.org/#/q/smaug+status:open,n,z +- Smaug Code Repository: \ https://github.com/openstack/smaug +- Smaug daily IRC Channel: #openstack-smaug +- Smaug weekly IRC Meeting on **even** Tuesday at 1500 UTC + and on **odd** Tuesday at 0900 UTC in + #openstack-meeting at freenode: \ + https://wiki.openstack.org/wiki/Meetings/smaug +- Smaug Trello Board: \ https://trello.com/b/Sudr4fKT/smaug Additional references ------------------------ -`Tokyo summit talk `_ -`Smaug overview slide `_ -`Smaug Overview blog `_ +===================== + +- `OpenStack Tokyo Summit 2015 talk `_ +- `OpenStack Austin Summit 2016 talk `_ +- `Smaug overview slide `_ +- `Smaug overview blog `_ diff --git a/doc/source/specs/index.rst b/doc/source/specs/index.rst index 9711ef96..4f3859dc 100644 --- a/doc/source/specs/index.rst +++ b/doc/source/specs/index.rst @@ -1,26 +1,5 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - Convention for heading levels: - ======= Heading 0 (reserved for the title in a document) - ------- Heading 1 - ~~~~~~~ Heading 2 - +++++++ Heading 3 - ''''''' Heading 4 - (Avoid deeper levels because they do not render well.) - Smaug Specs -================= +=========== This section contains detailed specification documents for different features inside Smaug.