Reorganize Mogan docs
Change-Id: I7d9986a231e33e65bf364ae1f028c9b58bb075a1
This commit is contained in:
Zhenguo Niu
parent
c4fa5931b5
commit
068ba7e5cc
|
|
@ -0,0 +1,187 @@
|
|||
============
|
||||
mogan-dbsync
|
||||
============
|
||||
|
||||
The :command:`mogan-dbsync` utility is used to create the database schema
|
||||
tables that the mogan services will use for storage. It can also be used to
|
||||
upgrade existing database tables when migrating between
|
||||
different versions of mogan.
|
||||
|
||||
The `Alembic library <http://alembic.readthedocs.org>`_ is used to perform
|
||||
the database migrations.
|
||||
|
||||
Options
|
||||
=======
|
||||
|
||||
This is a partial list of the most useful options. To see the full list,
|
||||
run the following::
|
||||
|
||||
mogan-dbsync --help
|
||||
|
||||
.. program:: mogan-dbsync
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help message and exit.
|
||||
|
||||
.. option:: --config-dir <DIR>
|
||||
|
||||
Path to a config directory with configuration files.
|
||||
|
||||
.. option:: --config-file <PATH>
|
||||
|
||||
Path to a configuration file to use.
|
||||
|
||||
.. option:: -d, --debug
|
||||
|
||||
Print debugging output.
|
||||
|
||||
.. option:: --version
|
||||
|
||||
Show the program's version number and exit.
|
||||
|
||||
.. option:: upgrade, stamp, revision, version, create_schema
|
||||
|
||||
The :ref:`command <dbsync_cmds>` to run.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
Options for the various :ref:`commands <dbsync_cmds>` for
|
||||
:command:`mogan-dbsync` are listed when the :option:`-h` or :option:`--help`
|
||||
option is used after the command.
|
||||
|
||||
For example::
|
||||
|
||||
mogan-dbsync create_schema --help
|
||||
|
||||
Information about the database is read from the mogan configuration file
|
||||
used by the API server and conductor services. This file must be specified
|
||||
with the :option:`--config-file` option::
|
||||
|
||||
mogan-dbsync --config-file /path/to/mogan.conf create_schema
|
||||
|
||||
The configuration file defines the database backend to use with the
|
||||
*connection* database option::
|
||||
|
||||
[database]
|
||||
connection=mysql+pymysql://root@localhost/mogan
|
||||
|
||||
If no configuration file is specified with the :option:`--config-file` option,
|
||||
:command:`mogan-dbsync` assumes an SQLite database.
|
||||
|
||||
.. _dbsync_cmds:
|
||||
|
||||
Command Options
|
||||
===============
|
||||
|
||||
:command:`mogan-dbsync` is given a command that tells the utility what actions
|
||||
to perform. These commands can take arguments. Several commands are available:
|
||||
|
||||
.. _create_schema:
|
||||
|
||||
create_schema
|
||||
-------------
|
||||
|
||||
.. program:: create_schema
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for create_schema and exit.
|
||||
|
||||
This command will create database tables based on the most current version.
|
||||
It assumes that there are no existing tables.
|
||||
|
||||
An example of creating database tables with the most recent version::
|
||||
|
||||
mogan-dbsync --config-file=/etc/mogan/mogan.conf create_schema
|
||||
|
||||
revision
|
||||
--------
|
||||
|
||||
.. program:: revision
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for revision and exit.
|
||||
|
||||
.. option:: -m <MESSAGE>, --message <MESSAGE>
|
||||
|
||||
The message to use with the revision file.
|
||||
|
||||
.. option:: --autogenerate
|
||||
|
||||
Compares table metadata in the application with the status of the database
|
||||
and generates migrations based on this comparison.
|
||||
|
||||
This command will create a new revision file. You can use the
|
||||
:option:`--message` option to comment the revision.
|
||||
|
||||
This is really only useful for mogan developers making changes that require
|
||||
database changes. This revision file is used during database migration and
|
||||
will specify the changes that need to be made to the database tables. Further
|
||||
discussion is beyond the scope of this document.
|
||||
|
||||
stamp
|
||||
-----
|
||||
|
||||
.. program:: stamp
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for stamp and exit.
|
||||
|
||||
.. option:: --revision <REVISION>
|
||||
|
||||
The revision number.
|
||||
|
||||
This command will 'stamp' the revision table with the version specified with
|
||||
the :option:`--revision` option. It will not run any migrations.
|
||||
|
||||
upgrade
|
||||
-------
|
||||
|
||||
.. program:: upgrade
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for upgrade and exit.
|
||||
|
||||
.. option:: --revision <REVISION>
|
||||
|
||||
The revision number to upgrade to.
|
||||
|
||||
This command will upgrade existing database tables to the most recent version,
|
||||
or to the version specified with the :option:`--revision` option.
|
||||
|
||||
If there are no existing tables, then new tables are created, beginning
|
||||
with the oldest known version, and successively upgraded using all of the
|
||||
database migration files, until they are at the specified version. Note
|
||||
that this behavior is different from the :ref:`create_schema` command
|
||||
that creates the tables based on the most recent version.
|
||||
|
||||
An example of upgrading to the most recent table versions::
|
||||
|
||||
mogan-dbsync --config-file=/etc/mogan/mogan.conf upgrade
|
||||
|
||||
.. note::
|
||||
|
||||
This command is the default if no command is given to
|
||||
:command:`mogan-dbsync`.
|
||||
|
||||
.. warning::
|
||||
|
||||
The upgrade command is not compatible with SQLite databases since it uses
|
||||
ALTER TABLE commands to upgrade the database tables. SQLite supports only
|
||||
a limited subset of ALTER TABLE.
|
||||
|
||||
version
|
||||
-------
|
||||
|
||||
.. program:: version
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for version and exit.
|
||||
|
||||
This command will output the current database version.
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
============
|
||||
Contributing
|
||||
============
|
||||
.. include:: ../../CONTRIBUTING.rst
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
.. _code-contribution-guide:
|
||||
|
||||
=======================
|
||||
Code Contribution Guide
|
||||
=======================
|
||||
|
||||
This document provides some necessary points for developers to consider when
|
||||
writing and reviewing Mogan code. The checklist will help developers get
|
||||
things right.
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
If you're completely new to OpenStack and want to contribute to the mogan
|
||||
project, please start by familiarizing yourself with the `Infra Team's Developer
|
||||
Guide <http://docs.openstack.org/infra/manual/developers.html>`_. This will help
|
||||
you get your accounts set up in Launchpad and Gerrit, familiarize you with the
|
||||
workflow for the OpenStack continuous integration and testing systems, and help
|
||||
you with your first commit.
|
||||
|
||||
LaunchPad Project
|
||||
-----------------
|
||||
|
||||
Most of the tools used for OpenStack require a launchpad.net ID for
|
||||
authentication.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* https://launchpad.net
|
||||
* https://launchpad.net/mogan
|
||||
|
||||
Related Projects
|
||||
----------------
|
||||
|
||||
There are several projects that are tightly integrated with mogan and which are
|
||||
developed by the same community.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* https://launchpad.net/python-moganclient
|
||||
|
||||
Project Hosting Details
|
||||
-----------------------
|
||||
|
||||
Bug tracker
|
||||
http://launchpad.net/mogan
|
||||
|
||||
Mailing list (prefix Subject line with ``[mogan]``)
|
||||
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
|
||||
|
||||
Wiki
|
||||
http://wiki.openstack.org/Mogan
|
||||
|
||||
Code Hosting
|
||||
https://git.openstack.org/cgit/openstack/mogan
|
||||
|
||||
Code Review
|
||||
https://review.openstack.org/#/q/status:open+project:openstack/mogan,n,z
|
||||
|
||||
|
||||
Mogan API RPC Versions
|
||||
----------------------
|
||||
|
||||
* When the signature(arguments) of an RPC method is changed, the following things
|
||||
need to be considered:
|
||||
|
||||
- The RPC version must be incremented and be the same value for both the client
|
||||
(engine/rpcapi.py, used by mogan-api) and the server (engine/manager.py,
|
||||
used by mogan-engine).
|
||||
- New arguments of the method can only be added as optional. Existing arguments cannot be
|
||||
removed or changed in incompatible ways (with the method in older RPC versions).
|
||||
- Client-side can pin a version cap by passing ``version_cap`` to the constructor
|
||||
of oslo_messaging.RPCClient. Methods which change arguments should run
|
||||
client.can_send_version() to see if the version of the request is compatible with the
|
||||
version cap of RPC Client, otherwise the request needs to be created to work with a
|
||||
previous version that is supported.
|
||||
- Server-side should tolerate the older version of requests in order to keep
|
||||
working during the progress of live upgrade. The behavior of server-side should
|
||||
depend on the input parameters passed from the client-side.
|
||||
|
||||
Object Versions
|
||||
---------------
|
||||
* When Object classes (subclasses of mogan.objects.base.MoganObject) are modified, the
|
||||
following things need to be considered:
|
||||
|
||||
- The change of fields and the signature of remotable method needs a bump of object
|
||||
version.
|
||||
- The arguments of methods can only be added as optional, they cannot be
|
||||
removed or changed in an incompatible way.
|
||||
- Fields types cannot be changed. If it is a must, create a new field and
|
||||
deprecate the old one.
|
||||
- When new version objects communicate with old version objects,
|
||||
obj_make_compatible() will be called to convert objects to the target version during
|
||||
serialization. So objects should implement their own obj_make_compatible() to
|
||||
remove/alter attributes which was added/changed after the target version.
|
||||
- There is a test (object/test_objects.py) to generate the hash of object fields and the
|
||||
signatures of remotable methods, which helps developers to check if the change of
|
||||
objects need a version bump. The object fingerprint should only be updated with a
|
||||
version bump.
|
||||
|
|
@ -1,18 +1,63 @@
|
|||
.. mogan 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.
|
||||
===========================================
|
||||
Welcome to Mogan's developer documentation!
|
||||
===========================================
|
||||
|
||||
Welcome to mogan's documentation!
|
||||
========================================================
|
||||
Introduction
|
||||
============
|
||||
|
||||
Contents:
|
||||
Mogan is an OpenStack project dedicated for bare metal computing management,
|
||||
which is designed specifically for bare metals, so compared with Nova, we can
|
||||
provide a more lightweight and convenient platform with more advanced features
|
||||
by leveraging Ironic. Besides this, we also plan to support RSD, then we can
|
||||
not only provide Pre-set Configuration Servers, but also Custom Servers.
|
||||
|
||||
Site Notes
|
||||
----------
|
||||
|
||||
This site is primarily intended to provide documentation for developers
|
||||
interested in contributing to or working with mogan. It *also* contains
|
||||
references and guides for administrators which are not yet hosted elsewhere on
|
||||
the OpenStack documentation sites.
|
||||
|
||||
|
||||
Developer's Guide
|
||||
=================
|
||||
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
If you are new to mogan, this section contains information that should help
|
||||
you get started as a developer working on the project or contributing to the
|
||||
project.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
|
||||
contributing
|
||||
dev/dev-quickstart
|
||||
Developer Contribution Guide <dev/code-contribution-guide>
|
||||
Setting Up Your Development Environment <dev/dev-quickstart>
|
||||
|
||||
|
||||
Administrator's Guide
|
||||
=====================
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
There are many aspects of the Bare Metal Compute service which are environment
|
||||
specific. The following pages will be helpful in configuring specific aspects
|
||||
of mogan that may or may not be suitable to every situation.
|
||||
|
||||
You can use `tox -egenconfig` to generate the sample config file.
|
||||
|
||||
Command References
|
||||
==================
|
||||
|
||||
Here are references for commands not elsewhere documented.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
cmds/mogan-dbsync
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
@ -20,4 +65,3 @@ Indices and tables
|
|||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue