Docs: Arrange Contributor Guide

Change-Id: Ibda21080a200e4ea552d74a197b33381a1dd8964
This commit is contained in:
Yuval Brik 2017-07-26 13:42:59 +03:00
parent 42c0264a4e
commit a78fc9d545
17 changed files with 204 additions and 190 deletions

2
.gitignore vendored
View File

@ -39,7 +39,7 @@ output/*/index.html
# Sphinx
doc/build
doc/source/api
doc/source/contributor/api
# pbr generates these
AUTHORS

Binary file not shown.

Before

Width:  |  Height:  |  Size: 102 KiB

After

Width:  |  Height:  |  Size: 106 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 147 KiB

After

Width:  |  Height:  |  Size: 79 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 203 KiB

After

Width:  |  Height:  |  Size: 104 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 32 KiB

View File

@ -1,8 +1,8 @@
.. _configuring:
=====================
Configuration Options
=====================
===================
Configuration Guide
===================
This section provides a list of all possible options for each configuration
file.

View File

@ -1,4 +0,0 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst

View File

@ -0,0 +1,136 @@
============
Architecture
============
High Level Architecture
=======================
.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
high_level_architecture.png
:alt: Solution Overview
:width: 600
:align: center
The system is built from independent services and a scalable *Workflow
engine* that ties them together:
API Service
===========
.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
karbor-api.png
:width: 600
These top-level north-bound APIs expose Application Data Protection services to
the Karbor 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.).
Resource (Protectable) API
--------------------------
Enables the Karbor user to access information about which resource types are
protectable (i.e. can be protected by Karbor). 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 Karbor 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 Karbor user to access the protection Plan registry and do
the following operations:
- Plan CRUD.
- List Plans.
- Starting and suspending of plans.
Automatic Operation API
-----------------------
This API enables the Karbor user to manage protection Operations:
- Create a checkpoint for a given Protection Plan.
- Delete unneeded checkpoints from the provider.
- Query the status on a given Operation ID.
Checkpoint API
--------------
This API enables the Karbor user to access and manage checkpoints stored in
the protection provider:
- List all checkpoints given a Bank ID.
- Show Information on a given checkpoint ID.
- Delete a checkpoint.
- Create a checkpoint.
Restore API
-----------
This API enables the Karbor user to restore a checkpoint onto a restore target:
- Create restored system from a checkpoint.
Operation Engine Service
========================
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.
Once an entity is created, it can be tracked through the north-bound API,
so monitoring the operations is independent from the scheduler.
It will be responsible for the automatic execution of specific operations
and tracking them.
Automatic Operation
-------------------
Automatic operations are the core of the scheduler. They define higher level
automatic logic. A simple scenario is a set of scheduled operations that
perform basic APIs at a specific trigger. There will also be complex scheduling
policies available that perform multiple north-bound basic APIs.
Trigger Engine
--------------
This sub-component of the schedule service is responsible for generating
triggers, which begin the execution of the Plan Orchestration.
It can be done based on a timer or an event collector, based on implementation.
In the first Karbor reference implementation, the trigger engine will only
provide time-based triggers.
Scheduled Operation
-------------------
This sub-component of the schedule service is responsible for holding the
mapping between a trigger and operation(s).
Protection Service
==================
This subsystem is responsible for handling the following tasks:
- Operation Execution
- Protection Provider management
WorkFlow Engine
---------------
This pluggable component is responsible for executing and orchestrating the
flow of the plan across all protection providers.

View File

@ -1,5 +1,5 @@
Karobr Developer Reference
==========================
Developer Reference
===================
Code Reference
--------------

View File

@ -1,6 +1,6 @@
======================================
Devstack Installation (for developers)
======================================
=====================
Devstack Installation
=====================
This type of installation is for developers or testing, and not for production.

View File

@ -0,0 +1,36 @@
=========================
Contributor Documentation
=========================
.. toctree::
:maxdepth: 2
architecture
devstack-installation
../specs/index
devref/index
Communication and Meetings
==========================
- Karbor Launchpad Link: \ https://launchpad.net/karbor
- Karbor Code Review: \ https://review.openstack.org/#/q/karbor+status:open,n,z
- Karbor Code Repository: \ https://github.com/openstack/karbor
- Karbor daily IRC Channel: #openstack-karbor
- Karbor IRC Meeting: every two weeks (on odd weeks) on Tuesday at 0900 UTC in
#openstack-meeting (IRC webclient).
ICS File: http://eavesdrop.openstack.org/calendars/karbor-team-meeting.ics
Additional Info: https://wiki.openstack.org/wiki/Meetings/karbor
Additional References
=====================
- `OpenStack Tokyo Summit 2015 talk <http://www.slideshare.net/gampel/openstack-tokyo-talk-application-data-protection-service>`_
- `OpenStack Austin Summit 2016 talk <https://www.youtube.com/watch?v=_tVYuW_YMB8>`_
- `OpenStack Barcelona Summit 2016 talk <https://www.youtube.com/watch?v=YFfcmGMn3M4>`_
- `OpenStack Boston Summit 2017 talk <https://www.youtube.com/watch?v=0l3zcmNboDQ>`_
- `Karbor overview slide <https://docs.google.com/presentation/d/1JYO1VIlTkGTF6lvKEMcsHkaST3mYFxuarpcNTJ3HBhk/edit?usp=sharing>`_
- `Karbor overview blog <http://blog.gampel.net/2015/12/karbor-application-data-protection-for.html>`_

View File

@ -16,21 +16,18 @@ standard framework of APIs and services that allows vendors to provide plugins
through a unified interface
.. toctree::
:maxdepth: 1
:maxdepth: 2
install/index
configuration/index
Using Karbor
============
.. toctree::
:maxdepth: 1
:maxdepth: 2
readme
devstack-installation
usage
contributing
releasenotes
install/index
configuration/index
Available Plugins
=================
@ -41,19 +38,21 @@ Available Plugins
protectable_plugins
protection_plugins
Karbor Code Reference
=====================
Contributor Docs
================
.. toctree::
:maxdepth: 2
contributor/index
Release Notes
=============
.. toctree::
:maxdepth: 1
devref/index
Karbor Specs
============
.. toctree::
:maxdepth: 1
specs/index
releasenotes
Indices and tables
==================

View File

@ -1,6 +1,6 @@
============
Installation
============
==================
Installation Guide
==================
.. toctree::
:maxdepth: 1

View File

@ -3,8 +3,6 @@
Introduction
============
.. contents:: :depth: 2
What is Karbor?
===============
@ -137,155 +135,3 @@ protectables during set up as long as the protection provider can handle those
entities. This flexibility means that Karbor is agnostic to the relationship
between the resources being backed up.
High Level Architecture
=======================
.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
high_level_architecture.png
:alt: Solution Overview
:width: 600
:align: center
The system is built from independent services and a scalable *Workflow
engine* that ties them together:
Karbor API Service
==================
.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
karbor-api.png
:width: 600
These top-level north-bound APIs expose Application Data Protection services to
the Karbor 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.).
Resource (Protectable) API
--------------------------
Enables the Karbor user to access information about which resource types are
protectable (i.e. can be protected by Karbor). 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 Karbor 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 Karbor user to access the protection Plan registry and do
the following operations:
- Plan CRUD.
- List Plans.
- Starting and suspending of plans.
Automatic Operation API
-----------------------
This API enables the Karbor user to manage protection Operations:
- Create a checkpoint for a given Protection Plan.
- Delete unneeded checkpoints from the provider.
- Query the status on a given Operation ID.
Checkpoint API
--------------
This API enables the Karbor user to access and manage checkpoints stored in
the protection provider:
- List all checkpoints given a Bank ID.
- Show Information on a given checkpoint ID.
- Delete a checkpoint.
- Create a checkpoint.
Restore API
-----------
This API enables the Karbor user to restore a checkpoint onto a restore target:
- Create restored system from a checkpoint.
Karbor Schedule Service
=======================
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.
Once an entity is created, it can be tracked through the north-bound API,
so monitoring the operations is independent from the scheduler.
It will be responsible for the automatic execution of specific operations
and tracking them.
Automatic Operation
-------------------
Automatic operations are the core of the scheduler. They define higher level
automatic logic. A simple scenario is a set of scheduled operations that
perform basic APIs at a specific trigger. There will also be complex scheduling
policies available that perform multiple north-bound basic APIs.
Trigger Engine
--------------
This sub-component of the schedule service is responsible for generating
triggers, which begin the execution of the Plan Orchestration.
It can be done based on a timer or an event collector, based on implementation.
In the first Karbor reference implementation, the trigger engine will only
provide time-based triggers.
Scheduled Operation
-------------------
This sub-component of the schedule service is responsible for holding the
mapping between a trigger and operation(s).
Karbor Protection Service
=========================
This subsystem is responsible for handling the following tasks:
- Operation Execution
- Protection Provider management
WorkFlow Engine
---------------
This pluggable component is responsible for executing and orchestrating the
flow of the plan across all protection providers.
Communication and Meetings
==========================
- Karbor Launchpad Link: \ https://launchpad.net/karbor
- Karbor Code Review: \ https://review.openstack.org/#/q/karbor+status:open,n,z
- Karbor Code Repository: \ https://github.com/openstack/karbor
- Karbor daily IRC Channel: #openstack-karbor
- Karbor 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/karbor
Additional references
=====================
- `OpenStack Tokyo Summit 2015 talk <http://www.slideshare.net/gampel/openstack-tokyo-talk-application-data-protection-service>`_
- `OpenStack Austin Summit 2016 talk <https://www.youtube.com/watch?v=_tVYuW_YMB8>`_
- `Karbor overview slide <https://docs.google.com/presentation/d/1JYO1VIlTkGTF6lvKEMcsHkaST3mYFxuarpcNTJ3HBhk/edit?usp=sharing>`_
- `Karbor overview blog <http://blog.gampel.net/2015/12/karbor-application-data-protection-for.html>`_

View File

@ -1,5 +1,5 @@
Karbor Specs
============
Specs
=====
This section contains detailed specification documents for
different features inside Karbor.

View File

@ -92,4 +92,5 @@ autodoc_exclude_modules =
karbor.services.protection.bank_plugins.*
karbor.services.protection.protectable_plugins.*
karbor.services.protection.protection_plugins.*
api_doc_dir = contributor/api
warnerrors = true

View File

@ -37,7 +37,7 @@ commands =
[testenv:docs]
whitelist_externals = rm
commands = rm -rf doc/build
rm -rf doc/source/api
rm -rf doc/source/contributor/api
python setup.py build_sphinx
[testenv:debug]