Docs: Arrange Contributor Guide
Change-Id: Ibda21080a200e4ea552d74a197b33381a1dd8964
|
@ -39,7 +39,7 @@ output/*/index.html
|
||||||
|
|
||||||
# Sphinx
|
# Sphinx
|
||||||
doc/build
|
doc/build
|
||||||
doc/source/api
|
doc/source/contributor/api
|
||||||
|
|
||||||
# pbr generates these
|
# pbr generates these
|
||||||
AUTHORS
|
AUTHORS
|
||||||
|
|
Before Width: | Height: | Size: 102 KiB After Width: | Height: | Size: 106 KiB |
Before Width: | Height: | Size: 147 KiB After Width: | Height: | Size: 79 KiB |
Before Width: | Height: | Size: 203 KiB After Width: | Height: | Size: 104 KiB |
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 32 KiB |
|
@ -1,8 +1,8 @@
|
||||||
.. _configuring:
|
.. _configuring:
|
||||||
|
|
||||||
=====================
|
===================
|
||||||
Configuration Options
|
Configuration Guide
|
||||||
=====================
|
===================
|
||||||
|
|
||||||
This section provides a list of all possible options for each configuration
|
This section provides a list of all possible options for each configuration
|
||||||
file.
|
file.
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
============
|
|
||||||
Contributing
|
|
||||||
============
|
|
||||||
.. include:: ../../CONTRIBUTING.rst
|
|
|
@ -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.
|
|
@ -1,5 +1,5 @@
|
||||||
Karobr Developer Reference
|
Developer Reference
|
||||||
==========================
|
===================
|
||||||
|
|
||||||
Code Reference
|
Code Reference
|
||||||
--------------
|
--------------
|
|
@ -1,6 +1,6 @@
|
||||||
======================================
|
=====================
|
||||||
Devstack Installation (for developers)
|
Devstack Installation
|
||||||
======================================
|
=====================
|
||||||
|
|
||||||
This type of installation is for developers or testing, and not for production.
|
This type of installation is for developers or testing, and not for production.
|
||||||
|
|
|
@ -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>`_
|
|
@ -16,21 +16,18 @@ standard framework of APIs and services that allows vendors to provide plugins
|
||||||
through a unified interface
|
through a unified interface
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 2
|
||||||
|
|
||||||
install/index
|
|
||||||
configuration/index
|
|
||||||
|
|
||||||
Using Karbor
|
Using Karbor
|
||||||
============
|
============
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 2
|
||||||
|
|
||||||
readme
|
readme
|
||||||
devstack-installation
|
|
||||||
usage
|
usage
|
||||||
contributing
|
install/index
|
||||||
releasenotes
|
configuration/index
|
||||||
|
|
||||||
Available Plugins
|
Available Plugins
|
||||||
=================
|
=================
|
||||||
|
@ -41,19 +38,21 @@ Available Plugins
|
||||||
protectable_plugins
|
protectable_plugins
|
||||||
protection_plugins
|
protection_plugins
|
||||||
|
|
||||||
Karbor Code Reference
|
Contributor Docs
|
||||||
=====================
|
================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
contributor/index
|
||||||
|
|
||||||
|
Release Notes
|
||||||
|
=============
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
devref/index
|
releasenotes
|
||||||
|
|
||||||
Karbor Specs
|
|
||||||
============
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
specs/index
|
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
============
|
==================
|
||||||
Installation
|
Installation Guide
|
||||||
============
|
==================
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
|
@ -3,8 +3,6 @@
|
||||||
Introduction
|
Introduction
|
||||||
============
|
============
|
||||||
|
|
||||||
.. contents:: :depth: 2
|
|
||||||
|
|
||||||
What is Karbor?
|
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
|
entities. This flexibility means that Karbor is agnostic to the relationship
|
||||||
between the resources being backed up.
|
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>`_
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
Karbor Specs
|
Specs
|
||||||
============
|
=====
|
||||||
|
|
||||||
This section contains detailed specification documents for
|
This section contains detailed specification documents for
|
||||||
different features inside Karbor.
|
different features inside Karbor.
|
||||||
|
|
|
@ -92,4 +92,5 @@ autodoc_exclude_modules =
|
||||||
karbor.services.protection.bank_plugins.*
|
karbor.services.protection.bank_plugins.*
|
||||||
karbor.services.protection.protectable_plugins.*
|
karbor.services.protection.protectable_plugins.*
|
||||||
karbor.services.protection.protection_plugins.*
|
karbor.services.protection.protection_plugins.*
|
||||||
|
api_doc_dir = contributor/api
|
||||||
warnerrors = true
|
warnerrors = true
|
||||||
|
|
2
tox.ini
|
@ -37,7 +37,7 @@ commands =
|
||||||
[testenv:docs]
|
[testenv:docs]
|
||||||
whitelist_externals = rm
|
whitelist_externals = rm
|
||||||
commands = rm -rf doc/build
|
commands = rm -rf doc/build
|
||||||
rm -rf doc/source/api
|
rm -rf doc/source/contributor/api
|
||||||
python setup.py build_sphinx
|
python setup.py build_sphinx
|
||||||
|
|
||||||
[testenv:debug]
|
[testenv:debug]
|
||||||
|
|