Do some documentation cleanup
Adjust some of the documenation to better reflect reality. - Reflect how prepare stage builds a source RPM repo and the building stage builds a binary RPM repo. - Restructure to better show the architecture page in the initial table of contents instead of hidden under the developer section. - Adjust line length to be in the < 80 restriction just for ease of reading and editing... - Adjust some of the links... Change-Id: Idb0ca60e20ea65d743e601c38bd89c0b9392a231
This commit is contained in:
Joshua Harlow
@@ -4,7 +4,8 @@
|
|||||||
ANVIL Documentation
|
ANVIL Documentation
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
.. rubric:: Everything about ANVIL, a set of **python** scripts and utilities to forge raw openstack into a productive tool!
|
.. rubric:: Everything about ANVIL, a set of **python** scripts and utilities
|
||||||
|
to forge raw openstack into a productive tool!
|
||||||
|
|
||||||
|
|
||||||
----
|
----
|
||||||
@@ -13,9 +14,9 @@ ANVIL Documentation
|
|||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
topics/summary
|
topics/summary
|
||||||
|
topics/architecture
|
||||||
topics/gettingstarted
|
topics/gettingstarted
|
||||||
topics/docs
|
topics/docs
|
||||||
topics/qanda
|
topics/qanda
|
||||||
topics/bugshugscode
|
topics/bugshugscode
|
||||||
topics/examples
|
topics/examples
|
||||||
|
|
||||||
|
|||||||
140
docs/source/topics/architecture.rst
Normal file
140
docs/source/topics/architecture.rst
Normal file
@@ -0,0 +1,140 @@
|
|||||||
|
.. _architecture:
|
||||||
|
|
||||||
|
========================
|
||||||
|
How anvil is architected
|
||||||
|
========================
|
||||||
|
|
||||||
|
This little ``HOWTO`` can be used by those who wish to understand how anvil
|
||||||
|
does things and why some of its architectural decisions were made.
|
||||||
|
|
||||||
|
^^^^^^^
|
||||||
|
History
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
Once upon a time there was a idea of replacing the then
|
||||||
|
existing `devstack <http://devstack.org/>`_ with a more robust, more
|
||||||
|
error-tolerant and more user/developer friendly OpenStack
|
||||||
|
setup toolkit. Since the existing `devstack <http://devstack.org/>`_ did (and
|
||||||
|
still does not support very well) complex intercomponent (and interpackage
|
||||||
|
management system) dependencies and
|
||||||
|
installing/packaging/starting/stopping/uninstalling of OpenStack components.
|
||||||
|
|
||||||
|
To solve this problem it was thought that there could be a toolkit that could
|
||||||
|
handle this better. It would also be in Python the language of choice for the
|
||||||
|
rest of the OpenStack components thus making it easier to understand for
|
||||||
|
programmers who are already working in OpenStack code. Thus *devstack2* was
|
||||||
|
born which was later renamed *devstack.py* and after a little while once
|
||||||
|
again got renamed to *anvil*.
|
||||||
|
|
||||||
|
^^^^^^^^^
|
||||||
|
Structure
|
||||||
|
^^^^^^^^^
|
||||||
|
|
||||||
|
Anvil is designed to have the following set of software components:
|
||||||
|
|
||||||
|
* **Actions:** an action is a sequence of function calls on a set of
|
||||||
|
implementing classes which follows a logically flow from one step to the
|
||||||
|
next. At the end of each step an action may choose to negate a step of
|
||||||
|
another action.
|
||||||
|
|
||||||
|
* Preparing
|
||||||
|
|
||||||
|
* Downloading source code
|
||||||
|
* Post-download patching of the source code
|
||||||
|
* Deep dependency & requirement analysis
|
||||||
|
* Downloading and packaging of missing python dependencies
|
||||||
|
* Packaging downloaded source code into SRPMs (aka source ``RPMs``) that
|
||||||
|
is placed into a SRPM repository.
|
||||||
|
|
||||||
|
* Building
|
||||||
|
|
||||||
|
* Creation of a binary RPM repository with all built packages and
|
||||||
|
dependencies (converting the prepared source RPMs into binary RPMs).
|
||||||
|
|
||||||
|
* Install
|
||||||
|
|
||||||
|
* Configuring.
|
||||||
|
* Pre-installing.
|
||||||
|
* Installing packages from previously prepared repositories.
|
||||||
|
* Post-installing.
|
||||||
|
|
||||||
|
* Uninstall
|
||||||
|
|
||||||
|
* Unconfiguring.
|
||||||
|
* Pre-uninstalling.
|
||||||
|
* Uninstalling previously installed packages.
|
||||||
|
* Post-uninstalling.
|
||||||
|
|
||||||
|
* Starting
|
||||||
|
|
||||||
|
* Pre-starting.
|
||||||
|
* Starting.
|
||||||
|
* Post-starting.
|
||||||
|
|
||||||
|
* Stopping.
|
||||||
|
* Testing.
|
||||||
|
|
||||||
|
* **Phases:** a phase is a step of an action which can be tracked as an
|
||||||
|
individual unit and can be marked as being completed. In the above install
|
||||||
|
action for each component that installed when each step occurs for that
|
||||||
|
component it will be recorded into a file so that if ``ctrl-c`` aborts anvil
|
||||||
|
and later the install is restarted anvil can notice that the previous phases
|
||||||
|
have already been completed and those phases can be skipped.
|
||||||
|
|
||||||
|
* This is how anvil does action and step resuming.
|
||||||
|
|
||||||
|
* **Components:** a component is a class which implements the above
|
||||||
|
steps (which are literally methods on an instance) and is registered with
|
||||||
|
the persona and configuration to be activated. To aid in making it easier
|
||||||
|
to add in new components a set of *generic* base classes exist that provide
|
||||||
|
common functionality that should work in most simplistic installs. These can
|
||||||
|
be found in ``anvil/components/``. All current components that exist
|
||||||
|
either use these base classes directly or inherit from them and override
|
||||||
|
functions to provide additional capabilities needed to perform the specified
|
||||||
|
action.
|
||||||
|
|
||||||
|
* **Distributions:** a distribution is a yaml file that is tied to a operating
|
||||||
|
system distribution and provides references for components to use in a
|
||||||
|
generic manner. Some of these references include how to map a
|
||||||
|
components ``pip-requires`` file dependencies to distribution specific
|
||||||
|
dependencies (possibly using ``yum`` or ``apt``) or what non-specified
|
||||||
|
dependencies are useful in getting the component up and running (such as
|
||||||
|
``guestfish`` for image mounting and manipulation). Other helpful references
|
||||||
|
include allowing for components to specify standard identifiers for
|
||||||
|
configuration such as ``pip``. This allows the underlying yaml file to map
|
||||||
|
the ``pip`` command to a distribution-centric command (in RHEL it it's
|
||||||
|
really named ``pip-python``), see the *commands* key in the yaml files for
|
||||||
|
examples of these settings. Note that each distribution yaml file that exists
|
||||||
|
in ``conf/distros`` provides this set of references for each component and
|
||||||
|
gets selected based on the yaml key in that file named *platform_pattern*.
|
||||||
|
|
||||||
|
* **Configuration:** central to how anvil operates is the ability to be largely
|
||||||
|
configuration driven (code when you need it but avoid it if you can).
|
||||||
|
Distributions as seen by the ``conf/distros`` folder specify
|
||||||
|
distribution-specific *configuration* that can be referenced by standard keys
|
||||||
|
by a given component. Each component also receives additional
|
||||||
|
configuration (accessible via a components ``get_option`` function) via the
|
||||||
|
yaml files specified in ``conf/components`` which provides for a way to have
|
||||||
|
configuration that is not distribution specific but instead is component
|
||||||
|
specific (say for configuring *nova* to use kvm instead of qemu).
|
||||||
|
|
||||||
|
* This configuration drive approach (as much as can be possible) was a key
|
||||||
|
design goal that drives how anvil was and is developed. It has even seemed
|
||||||
|
to be ahead of its time due to how anvil has a distribution yaml file that
|
||||||
|
has specified component dependencies long before the OpenStack community
|
||||||
|
even recognized such a dependency list was useful.
|
||||||
|
|
||||||
|
* **Personas:** a persona is a way for anvil to know what components (and
|
||||||
|
possibly subsystems of those components) you wish to have the given action
|
||||||
|
applied to. Since not everyone can agree on what is an install of OpenStack
|
||||||
|
this concept allows for those who wish to have a different set to do so. It
|
||||||
|
is as all other configuration another yaml file and can be examined by
|
||||||
|
looking into the ``conf/personas`` folders.
|
||||||
|
|
||||||
|
* Each yaml file contains the list of components to be performed for the
|
||||||
|
given action, a simple set of options for those components (for options
|
||||||
|
that may not be applicable to be in the component configuration yaml) and
|
||||||
|
which subsystems a given component will have enabled (if the component
|
||||||
|
supports this concept) as well as which distribution the persona
|
||||||
|
supports (if there is a desire to restrict a given persona to a given
|
||||||
|
distribution this field can be used to accomplish that goal).
|
||||||
@@ -4,20 +4,8 @@
|
|||||||
Bugs & Hugs & Code
|
Bugs & Hugs & Code
|
||||||
==================
|
==================
|
||||||
|
|
||||||
Community
|
ANVIL is an open-source tool released under the `apache version 2.0 license`_.
|
||||||
=========
|
It *depends* on its **community** to keep it alive.
|
||||||
|
|
||||||
ANVIL is an open-source tool released under the `apache version 2.0 license`_. It *depends* on its **community** to keep it alive.
|
|
||||||
|
|
||||||
Links
|
|
||||||
-----
|
|
||||||
|
|
||||||
Please visit as often as you want at the following urls:
|
|
||||||
|
|
||||||
- http://launchpad.net/anvil (blueprints for features, bugs, q/a...)
|
|
||||||
- https://launchpad.net/~anvil-dev (talk to the devs directly)
|
|
||||||
|
|
||||||
Help and developer work/time is always much appreciated!
|
|
||||||
|
|
||||||
IRC
|
IRC
|
||||||
===
|
===
|
||||||
@@ -29,30 +17,45 @@ Source code
|
|||||||
|
|
||||||
The source code is on github located at:
|
The source code is on github located at:
|
||||||
|
|
||||||
https://github.com/stackforge/anvil/
|
http://git.openstack.org/cgit/stackforge/anvil (mirrored @
|
||||||
|
http://github.com/stackforge/anvil/).
|
||||||
|
|
||||||
Feel free to fork it and contribute to it.
|
Feel free to fork it and `contribute`_ to it.
|
||||||
|
|
||||||
Bugs
|
Bugs
|
||||||
----
|
====
|
||||||
|
|
||||||
https://bugs.launchpad.net/anvil
|
http://bugs.launchpad.net/anvil
|
||||||
|
|
||||||
Branches
|
Branches
|
||||||
--------
|
========
|
||||||
|
|
||||||
Stable *branches* can also be downloaded:
|
Anvil tries to work across different OpenStack releases as of the `havana`_
|
||||||
|
release...
|
||||||
https://github.com/stackforge/anvil/branches
|
|
||||||
|
|
||||||
|
If it does not work across the *majority* of OpenStack `releases`_ please file
|
||||||
|
a `bug`_.
|
||||||
|
|
||||||
Hacking
|
Hacking
|
||||||
=======
|
=======
|
||||||
|
|
||||||
Feel free to hack but please try to follow the `hacking guidelines`_.
|
Feel free to hack but please try to follow the `hacking guidelines`_.
|
||||||
|
|
||||||
|
Links
|
||||||
|
=====
|
||||||
|
|
||||||
.. _apache version 2.0 license: https://github.com/stackforge/anvil/blob/master/LICENSE
|
Please visit as often as you want at the following urls:
|
||||||
.. _launchpad’s issue tracking system: http://launchpad.net/anvil
|
|
||||||
.. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/HACKING.md
|
- http://launchpad.net/anvil (blueprints for features, bugs, q/a...)
|
||||||
|
- http://launchpad.net/~anvil-dev (talk to the devs directly)
|
||||||
|
|
||||||
|
Help and developer work/time is always much appreciated!
|
||||||
|
|
||||||
|
.. _apache version 2.0 license: http://www.apache.org/licenses/LICENSE-2.0.html
|
||||||
|
.. _bug: http://bugs.launchpad.net/anvil
|
||||||
|
.. _contribute: http://wiki.openstack.org/wiki/How_To_Contribute
|
||||||
.. _freenode: http://freenode.net/irc_servers.shtml
|
.. _freenode: http://freenode.net/irc_servers.shtml
|
||||||
|
.. _hacking guidelines: http://github.com/stackforge/anvil/blob/master/HACKING.md
|
||||||
|
.. _havana: http://wiki.openstack.org/wiki/Releases
|
||||||
|
.. _launchpad’s issue tracking system: http://launchpad.net/anvil
|
||||||
|
.. _releases: http://wiki.openstack.org/wiki/Releases
|
||||||
|
|||||||
@@ -1,125 +0,0 @@
|
|||||||
.. _architecture:
|
|
||||||
|
|
||||||
========================
|
|
||||||
How anvil is architected
|
|
||||||
========================
|
|
||||||
|
|
||||||
This little ``HOWTO`` can be used by those who wish to
|
|
||||||
understand how anvil does things and why some of its
|
|
||||||
architectural decisions were made.
|
|
||||||
|
|
||||||
Diving in!
|
|
||||||
----------
|
|
||||||
|
|
||||||
^^^^^^^^^^^^^^^^
|
|
||||||
A little history
|
|
||||||
^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Once upon a time there was a idea of replacing the then existing `devstack <http://devstack.org/>`_
|
|
||||||
with a more robust, more error-tolerant and more user/developer friendly OpenStack
|
|
||||||
setup toolkit. Since the existing `devstack <http://devstack.org/>`_ did (and still
|
|
||||||
does not support very well) complex intercomponent (and interpackage management system) dependencies
|
|
||||||
and installing/packaging/starting/stopping/uninstalling of OpenStack components.
|
|
||||||
|
|
||||||
To solve this problem it was thought that there could be a toolkit that could handle this better.
|
|
||||||
It would also be in Python the language of choice for the rest of the OpenStack components thus making
|
|
||||||
it easier to understand for programmers who are already working in OpenStack code. Thus *devstack2* was
|
|
||||||
born which was later renamed *devstack.py* and after a little while once again got renamed to *anvil*.
|
|
||||||
|
|
||||||
^^^^^^^^^
|
|
||||||
Structure
|
|
||||||
^^^^^^^^^
|
|
||||||
|
|
||||||
Anvil is designed to have the following set of software components:
|
|
||||||
|
|
||||||
* **Actions:** an action is a sequence of function calls on a set of implementing
|
|
||||||
classes which follows a logically flow from one step to the next. At the end of
|
|
||||||
each step an action may choose to negate a step of another action.
|
|
||||||
|
|
||||||
* Preparing
|
|
||||||
|
|
||||||
* Downloading source code
|
|
||||||
* Post-download patching of the source code
|
|
||||||
* Deep dependency & requirement analysis
|
|
||||||
* Downloading and packaging of missing python dependencies
|
|
||||||
* Packaging downloaded source code
|
|
||||||
* Creation of a repository with all built packages & dependencies
|
|
||||||
|
|
||||||
* Install
|
|
||||||
|
|
||||||
* Configuring
|
|
||||||
* Pre-installing
|
|
||||||
* Installing packages from previously prepared repository
|
|
||||||
* Post-installing
|
|
||||||
|
|
||||||
* Uninstall
|
|
||||||
|
|
||||||
* Unconfiguring
|
|
||||||
* Pre-uninstalling
|
|
||||||
* Uninstalling previously installed packages
|
|
||||||
* Post-uninstalling
|
|
||||||
|
|
||||||
* Starting
|
|
||||||
|
|
||||||
* Pre-starting
|
|
||||||
* Starting
|
|
||||||
* Post-starting
|
|
||||||
|
|
||||||
* Stopping
|
|
||||||
* Testing
|
|
||||||
* Packaging
|
|
||||||
|
|
||||||
* **Phases:** a phase is a step of an action which can be tracked as an individual
|
|
||||||
unit and can be marked as being completed. In the above install action for each
|
|
||||||
component that installed when each step occurs for that component it will be recorded
|
|
||||||
into a file so that if ``ctrl-c`` aborts anvil and later the install is restarted
|
|
||||||
anvil can notice that the previous phases have already been completed and those
|
|
||||||
phases can be skipped. This is how anvil does action and step resuming.
|
|
||||||
|
|
||||||
* **Components:** a component is a class which implements the above steps (which
|
|
||||||
are literally methods on an instance) and is registered with the persona and
|
|
||||||
configuration to be activated. To aid in making it easier to add in new components
|
|
||||||
a set of *generic* base classes exist that provide common functionality that
|
|
||||||
should work in most simplistic installs. These can be found in
|
|
||||||
``anvil/components/``. All current components that exist either use
|
|
||||||
these base classes directly or inherit from them and override functions to
|
|
||||||
provide additional capabilities needed to perform the specified action.
|
|
||||||
|
|
||||||
* **Distributions:** a distribution is a yaml file that is tied to a operating
|
|
||||||
system distribution and provides references for components to use in a generic
|
|
||||||
manner. Some of these references include how to map a components ``pip-requires``
|
|
||||||
file dependencies to distribution specific dependencies (possibly using ``yum``
|
|
||||||
or ``apt``) or what non-specified dependencies are useful in getting the component
|
|
||||||
up and running (such as ``guestfish`` for image mounting and manipulation).
|
|
||||||
Other helpful references include allowing for components to specify standard
|
|
||||||
identifiers for configuration such as ``pip``. This allows the underlying yaml file to
|
|
||||||
map the ``pip`` command to a distribution-centric command (in RHEL it its really
|
|
||||||
named ``pip-python``), see the *commands* key in the yaml files for examples
|
|
||||||
of these settings. Note that each distribution yaml file that exists in ``conf/distros``
|
|
||||||
provides this set of references for each component and gets selected based on the
|
|
||||||
yaml key in that file named *platform_pattern*.
|
|
||||||
|
|
||||||
* **Configuration:** central to how anvil operates is the ability to be largely
|
|
||||||
configuration driven (code when you need it but avoid it if you can).
|
|
||||||
Distributions as seen by the ``conf/distros`` folder specify
|
|
||||||
distribution-specific *configuration* that can be referenced by standard keys by a given
|
|
||||||
component. Each component also receives additional configuration (accessible via a components
|
|
||||||
``get_option`` function) via the yaml files specified in ``conf/components`` which
|
|
||||||
provides for a way to have configuration that is not distribution specific but instead
|
|
||||||
is component specific (say for configuring *nova* to use kvm instead of qemu). This
|
|
||||||
configuration drive approach (as much as can be possible) was a key design goal that
|
|
||||||
drives how anvil was and is developed. It has even seemed to be ahead of its time due
|
|
||||||
to how anvil has a distribution yaml file that has specified component dependencies
|
|
||||||
long before the OpenStack community even recognized such a dependency list was useful.
|
|
||||||
|
|
||||||
* **Personas:** a persona is a way for anvil to know what components (and possibly
|
|
||||||
subsystems of those components) you wish to have the given action applied to. Since
|
|
||||||
not everyone can agree on what is an install of OpenStack this concept allows for
|
|
||||||
those who wish to have a different set to do so. It is as all other configuration
|
|
||||||
another yaml file and can be examined by looking into the ``conf/personas`` folders. Each yaml file
|
|
||||||
contains the list of components to be performed for the given action, a simple set of
|
|
||||||
options for those components (for options that may not be applicable to be in the
|
|
||||||
component configuration yaml) and which subsystems a given component will have enabled
|
|
||||||
(if the component supports this concept) as well as which distribution the persona supports (if
|
|
||||||
there is a desire to restrict a given persona to a given distribution this field can be
|
|
||||||
used to accomplish that goal).
|
|
||||||
@@ -18,6 +18,4 @@ For developers
|
|||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
dev_notes/architecture
|
|
||||||
dev_notes/addingowndistro
|
dev_notes/addingowndistro
|
||||||
|
|
||||||
|
|||||||
@@ -1,106 +0,0 @@
|
|||||||
.. _features:
|
|
||||||
|
|
||||||
|
|
||||||
========
|
|
||||||
Features
|
|
||||||
========
|
|
||||||
|
|
||||||
Configurations
|
|
||||||
--------------
|
|
||||||
|
|
||||||
A set of configuration files (in yaml format) that shows common/component/distribution/origins configurations.
|
|
||||||
All the yaml configuration files could be found in:
|
|
||||||
|
|
||||||
* conf/templates/keystone/
|
|
||||||
* conf/components/
|
|
||||||
* conf/distros/
|
|
||||||
* conf/origins/
|
|
||||||
* subdirectories of conf/personas/
|
|
||||||
|
|
||||||
|
|
||||||
Installing
|
|
||||||
----------
|
|
||||||
|
|
||||||
* Automatically downloading source from git and performing tag/branch checkouts.
|
|
||||||
* Automatically verifying and translating requirement files to known `pypi`_/rpm packages.
|
|
||||||
* Automatically installing and building missing dependencies (`pypi`_ and rpm) for you.
|
|
||||||
* Automatically configuring the needed files, symlinks, adjustments, and any patches.
|
|
||||||
|
|
||||||
Testing
|
|
||||||
-------
|
|
||||||
|
|
||||||
Automatically running each component unit tests.
|
|
||||||
|
|
||||||
Starting
|
|
||||||
--------
|
|
||||||
|
|
||||||
Starting of the components sub-programs with the needed configuration via the common `daemon`_ model.
|
|
||||||
|
|
||||||
* Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination.
|
|
||||||
* Trace files could be found in $HOME/openstack/<component>/traces/
|
|
||||||
|
|
||||||
Stopping
|
|
||||||
--------
|
|
||||||
|
|
||||||
Stopping of the previously started components.
|
|
||||||
|
|
||||||
Uninstalling
|
|
||||||
------------
|
|
||||||
|
|
||||||
Getting you back to an initial 'clean' state:
|
|
||||||
|
|
||||||
* Removing installed configuration.
|
|
||||||
* Undoing of installed files/directories.
|
|
||||||
* Removing of packages installed.
|
|
||||||
|
|
||||||
Packaging
|
|
||||||
---------
|
|
||||||
|
|
||||||
* Ceating a basic set of packages that matches the components selected.
|
|
||||||
* Supports automatic injection of dependencies and creation of a ``changelog`` from git history.
|
|
||||||
|
|
||||||
Status
|
|
||||||
------
|
|
||||||
|
|
||||||
* Checking the status of the running components sub-programs
|
|
||||||
|
|
||||||
Dry run
|
|
||||||
-------
|
|
||||||
|
|
||||||
``dry_run`` satisfied with any action it turns verbose and all modifying the outside world calls (running external commands, kill, mkdir ......) are not executing.
|
|
||||||
|
|
||||||
Pythonic
|
|
||||||
--------
|
|
||||||
|
|
||||||
Written in **python** so it matches the style of other `OpenStack`_ components.
|
|
||||||
|
|
||||||
Code decoupling
|
|
||||||
---------------
|
|
||||||
|
|
||||||
(thus encouraging re-use by others)
|
|
||||||
|
|
||||||
* Components & actions are isolated as individual classes.
|
|
||||||
* Supports installation personas that define what is to be installed, thus decoupling the 'what' from the 'how'.
|
|
||||||
|
|
||||||
Resumption
|
|
||||||
----------
|
|
||||||
|
|
||||||
Install/start/stop resumption so that when you install you can ``ctrl+c`` and resume later (where applicable).
|
|
||||||
|
|
||||||
Extensive logging
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
* All commands executed are logged in standard output, all configuration files read/written (and so on).
|
|
||||||
* Debug mode could be activate with ``-v`` option
|
|
||||||
|
|
||||||
Package tracking and building
|
|
||||||
-----------------------------
|
|
||||||
|
|
||||||
|
|
||||||
* Creation of a single rpm of your installation. This freezes what is needed for that release to a known set of packages and dependencies.
|
|
||||||
* Automatically building and/or including all needed dependencies.
|
|
||||||
* Includes application of your distributions native packages (when applicable).
|
|
||||||
|
|
||||||
.. _OpenStack: http://openstack.org/
|
|
||||||
.. _daemon: http://en.wikipedia.org/wiki/Daemon_(computing)
|
|
||||||
.. _pypi: http://pypi.python.org/pypi
|
|
||||||
@@ -1,14 +1,10 @@
|
|||||||
.. _getting-started:
|
.. _getting-started:
|
||||||
|
|
||||||
===============
|
===============
|
||||||
Getting Started
|
Getting started
|
||||||
===============
|
===============
|
||||||
|
|
||||||
|
Made to be as simple as possible, but not too simple...
|
||||||
Simple setup!
|
|
||||||
=============
|
|
||||||
|
|
||||||
Made to be as simple as possible, but not too simple.
|
|
||||||
|
|
||||||
Prerequisites
|
Prerequisites
|
||||||
=============
|
=============
|
||||||
@@ -21,8 +17,8 @@ Read the great documentation for developers/admins at
|
|||||||
- http://docs.openstack.org/developer/
|
- http://docs.openstack.org/developer/
|
||||||
- http://docs.openstack.org/
|
- http://docs.openstack.org/
|
||||||
|
|
||||||
This will vastly help you understand what the
|
This will vastly help you understand what the configurations and options do
|
||||||
configurations and options do when ANVIL configures them.
|
when ANVIL configures them.
|
||||||
|
|
||||||
Linux
|
Linux
|
||||||
-----
|
-----
|
||||||
@@ -48,12 +44,13 @@ http://docs.openstack.org/admin-guide-cloud/content/section_networking-nova.html
|
|||||||
Check out the root article and the sub-chapters there to understand more
|
Check out the root article and the sub-chapters there to understand more
|
||||||
of what these settings mean.
|
of what these settings mean.
|
||||||
|
|
||||||
**This is typically one of the hardest aspects of OpenStack to configure and get right!**
|
**This is typically one of the hardest aspects of OpenStack to configure
|
||||||
|
and get right!**
|
||||||
|
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
The following settings in ``conf/components/nova.yaml`` are an example of settings that will
|
The following settings in ``conf/components/nova.yaml`` are an example of
|
||||||
affect the configuration of your compute nodes network.
|
settings that will affect the configuration of your compute nodes network.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
@@ -146,18 +143,28 @@ Configuration
|
|||||||
|
|
||||||
Any configuration to be updated should now be done.
|
Any configuration to be updated should now be done.
|
||||||
|
|
||||||
Please edit the corresponding yaml files in ``conf/components/`` or ``conf/components/personas``
|
Please edit the corresponding yaml files in ``conf/components/`` or
|
||||||
to fit your desired configuration of nova/glance and the other OpenStack components.
|
``conf/components/personas`` to fit your desired configuration of nova/glance
|
||||||
You can use ``-p <conf/components/required_file.yaml>`` option with following commands
|
and the other OpenStack components.
|
||||||
to use configuration files.
|
|
||||||
|
|
||||||
To specify which versions of OpenStack components you want to install select or edit origins configuration
|
.. note::
|
||||||
file from ``<conf/origins/>`` and use it as follows ``-o <conf/origins/origins_file.yaml>``.
|
|
||||||
|
You can use ``-p <conf/components/required_file.yaml>`` to specify a
|
||||||
|
different persona.
|
||||||
|
|
||||||
|
To specify which versions of OpenStack components you want to install select
|
||||||
|
or edit an origins configuration file from ``<conf/origins/>``.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
You can use ``-o <conf/origins/origins_file.yaml>`` to specify this
|
||||||
|
different origins file.
|
||||||
|
|
||||||
Networking notes for those on RedHat/CentOS/Fedora
|
Networking notes for those on RedHat/CentOS/Fedora
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
If you are planning on using the `FlatManager`_ then you might want to read and follow:
|
If you are planning on using the `FlatManager`_ then you might want to read
|
||||||
|
and follow:
|
||||||
|
|
||||||
* http://www.techotopia.com/index.php/Creating_an_RHEL_5_KVM_Networked_Bridge_Interface
|
* http://www.techotopia.com/index.php/Creating_an_RHEL_5_KVM_Networked_Bridge_Interface
|
||||||
|
|
||||||
@@ -169,15 +176,17 @@ To enable the needed repositories for various requirements please also run::
|
|||||||
sudo subscription-manager repos --enable rhel-6-server-optional-rpms
|
sudo subscription-manager repos --enable rhel-6-server-optional-rpms
|
||||||
|
|
||||||
You can also include the `RDO`_ repositories (which has even more of the needed
|
You can also include the `RDO`_ repositories (which has even more of the needed
|
||||||
requirements). This will ensure that anvil has to build less dependencies overall.
|
requirements). This will ensure that anvil has to build less dependencies
|
||||||
|
overall.
|
||||||
|
|
||||||
* http://openstack.redhat.com/Repositories
|
* http://openstack.redhat.com/Repositories
|
||||||
|
|
||||||
Pre-installing
|
Pre-installing
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
In order to ensure that anvil will have its correct dependencies you need to first run the
|
In order to ensure that anvil will have its correct dependencies you need to
|
||||||
bootstrapping code that will setup said dependencies for your operating system.
|
first run the bootstrapping code that will setup said dependencies for your
|
||||||
|
operating system.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
@@ -194,7 +203,8 @@ Now prepare *OpenStacks* components by running the following:
|
|||||||
|
|
||||||
You should see a corresponding OpenStack repositories getting downloaded using
|
You should see a corresponding OpenStack repositories getting downloaded using
|
||||||
git, python setups occurring and configuration files being written as well as
|
git, python setups occurring and configuration files being written as well as
|
||||||
source rpm packages being built and a repository setup from those components [#verbose]_.
|
source rpm packages being built and a repository setup from those
|
||||||
|
components [#verbose]_.
|
||||||
|
|
||||||
Building
|
Building
|
||||||
--------
|
--------
|
||||||
@@ -206,9 +216,10 @@ Now build *OpenStacks* components by running the following:
|
|||||||
sudo ./smithy -a build
|
sudo ./smithy -a build
|
||||||
|
|
||||||
You should see a corresponding OpenStack components and dependencies at this
|
You should see a corresponding OpenStack components and dependencies at this
|
||||||
stage being packaged into rpm files and two repositories being setup for you [#verbose]_.
|
stage being packaged into rpm files and two repositories being setup for
|
||||||
One repository will be the dependencies that the OpenStack components need to run and the
|
you [#verbose]_. One repository will be the dependencies that the OpenStack
|
||||||
other will be the OpenStack components themselves.
|
components need to run and th other will be the OpenStack components
|
||||||
|
themselves.
|
||||||
|
|
||||||
Installing
|
Installing
|
||||||
----------
|
----------
|
||||||
@@ -227,9 +238,11 @@ step [#verbose]_.
|
|||||||
**Note:** You can specify conf file just like in the ``prepare`` action.
|
**Note:** You can specify conf file just like in the ``prepare`` action.
|
||||||
Without a specified conf file the command will execute with ``conf/personas/in-a-box/basic.yaml``
|
Without a specified conf file the command will execute with ``conf/personas/in-a-box/basic.yaml``
|
||||||
|
|
||||||
**Note:** Also to avoid qemu errors please follow the solution @ https://bugs.launchpad.net/anvil/+bug/985786
|
**Note:** Also to avoid qemu errors please follow the
|
||||||
which will ensure that the ``qemu`` user can write to your instances directory. If needed edit ``conf/components/nova.yaml``
|
solution @ https://bugs.launchpad.net/anvil/+bug/985786
|
||||||
and also adjust the ``instances_path`` option.
|
which will ensure that the ``qemu`` user can write to your instances
|
||||||
|
directory. If needed edit ``conf/components/nova.yaml`` and also adjust
|
||||||
|
the ``instances_path`` option.
|
||||||
|
|
||||||
Also as documented at http://docs.openstack.org/essex/openstack-compute/admin/content/qemu.html#fixes-rhel-qemu
|
Also as documented at http://docs.openstack.org/essex/openstack-compute/admin/content/qemu.html#fixes-rhel-qemu
|
||||||
please run the following (**after** installation).
|
please run the following (**after** installation).
|
||||||
@@ -244,13 +257,15 @@ please run the following (**after** installation).
|
|||||||
Testing
|
Testing
|
||||||
----------
|
----------
|
||||||
|
|
||||||
Now (if you choose) you can run each *OpenStack* components unit tests by running the following:
|
Now (if you choose) you can run each *OpenStack* components unit tests by
|
||||||
|
running the following:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
sudo ./smithy -a test
|
sudo ./smithy -a test
|
||||||
|
|
||||||
You should see a set of unit tests being ran (ideally with zero failures) [#verbose]_.
|
You should see a set of unit tests being ran (ideally with zero
|
||||||
|
failures) [#verbose]_.
|
||||||
|
|
||||||
Starting
|
Starting
|
||||||
--------
|
--------
|
||||||
@@ -311,16 +326,17 @@ First run the following to check the status of each component [#verbose]_.
|
|||||||
sudo ./smithy -a status
|
sudo ./smithy -a status
|
||||||
|
|
||||||
If you do not see all green status then you should run the following and see
|
If you do not see all green status then you should run the following and see
|
||||||
if any of the ``/var/log/nova,glance,keystone,cinder,...`` log files will give you more information
|
if any of the ``/var/log/nova,glance,keystone,cinder,...`` log files will give
|
||||||
about what is occuring.
|
you more information about what is occuring.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
sudo ./smithy -a status --show
|
sudo ./smithy -a status --show
|
||||||
|
|
||||||
This will dump out those files (truncated to not be to verbose) so that anything
|
This will dump out those files (truncated to not be to verbose) so that anything
|
||||||
peculaliar can be seen. If nothing can be then go to the installation directory (typically ``~/openstack``)
|
peculaliar can be seen. If nothing can be then go to the installation
|
||||||
and check the ``traces`` directory of each component and check if anything looks fishy.
|
directory (typically ``~/openstack``) and check the ``traces`` directory of
|
||||||
|
each component and check if anything looks fishy.
|
||||||
|
|
||||||
Stopping
|
Stopping
|
||||||
--------
|
--------
|
||||||
@@ -335,7 +351,8 @@ the following:
|
|||||||
You should see a set of stop actions happening [#verbose]_. This
|
You should see a set of stop actions happening [#verbose]_. This
|
||||||
ensures the above a daemon that was started is now killed.
|
ensures the above a daemon that was started is now killed.
|
||||||
|
|
||||||
**Note:** A good way to check if it killed everything correctly is to run the following.
|
**Note:** A good way to check if it killed everything correctly is to run
|
||||||
|
the following.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
@@ -345,8 +362,8 @@ ensures the above a daemon that was started is now killed.
|
|||||||
There should be no entries like ``nova``, ``glance``, ``apache``,
|
There should be no entries like ``nova``, ``glance``, ``apache``,
|
||||||
``httpd``. If there are then the stop may have not occurred correctly.
|
``httpd``. If there are then the stop may have not occurred correctly.
|
||||||
If this is the case run again with a ``-v`` or a ``-vv`` or check the
|
If this is the case run again with a ``-v`` or a ``-vv`` or check the
|
||||||
``/var/log/nova,glance,keystone,cinder,...`` files for any useful information on what
|
``/var/log/nova,glance,keystone,cinder,...`` files for any useful information
|
||||||
is happening.
|
on what is happening.
|
||||||
|
|
||||||
Uninstalling
|
Uninstalling
|
||||||
------------
|
------------
|
||||||
|
|||||||
@@ -7,30 +7,146 @@ Summary
|
|||||||
Anvil is a forging tool to help build OpenStack components and their
|
Anvil is a forging tool to help build OpenStack components and their
|
||||||
dependencies into a complete package-oriented system.
|
dependencies into a complete package-oriented system.
|
||||||
|
|
||||||
It automates the git checkouts of the OpenStack components, analyzes & builds their
|
It automates the git checkouts of the OpenStack components, analyzes & builds
|
||||||
dependencies and the components themselves into packages. It can then install
|
their dependencies and the components themselves into packages. It can then
|
||||||
from the package repositories it created, perform configuration and start, stop,
|
install from the package repositories it created, perform configuration and
|
||||||
restart and uninstall the components and their dependencies as a complete system.
|
start, stop, restart and uninstall the components and their dependencies as a
|
||||||
|
complete system.
|
||||||
|
|
||||||
It allows a developer to setup an environment using the automatically created packages
|
It allows a developer to setup an environment using the automatically created
|
||||||
(and dependencies) with the help of anvil configuring the components to work
|
packages (and dependencies, ex. ``RPMs``) with the help of anvil configuring
|
||||||
correctly for the developer's needs. After the developer has tested out their
|
the components to work correctly for the developer's needs. After the developer
|
||||||
features or changes they can stop the OpenStack components, uninstall the
|
has tested out their features or changes they can stop the OpenStack
|
||||||
packages and bring back their system to a pre-installation/pre-anvil state.
|
components, uninstall the packages and bring back their system to a
|
||||||
|
pre-installation/pre-anvil state.
|
||||||
|
|
||||||
The distinguishing part from devstack_ (besides being written in Python and not
|
The distinguishing part from devstack_ (besides being written in Python and not
|
||||||
shell), is that after building those packages (currently RPMs) the same packages
|
shell), is that after building those packages (currently ``RPMs``) the same
|
||||||
can be used later (or at the same time) to actually deploy at a larger scale using
|
packages can be used later (or at the same time) to actually deploy at a
|
||||||
tools such as chef_, salt_, or puppet_ (to name a few).
|
larger scale using tools such as `chef`_, `salt`_, or `puppet`_ (to name a few).
|
||||||
|
|
||||||
----
|
--------
|
||||||
|
Features
|
||||||
|
--------
|
||||||
|
|
||||||
.. toctree::
|
Configurations
|
||||||
|
--------------
|
||||||
|
|
||||||
features
|
A set of configuration files (in `yaml`_ format) that is used for
|
||||||
|
common, component, distribution, code origins configuration...
|
||||||
|
|
||||||
|
All the `yaml`_ configuration files could be found in:
|
||||||
|
|
||||||
|
* ``conf/templates/keystone/``
|
||||||
|
* ``conf/components/``
|
||||||
|
* ``conf/distros/``
|
||||||
|
* ``conf/origins/``
|
||||||
|
* subdirectories of ``conf/personas/``
|
||||||
|
|
||||||
|
|
||||||
.. _devstack: http://www.devstack.org/
|
Installing
|
||||||
.. _puppet: http://puppetlabs.com/
|
----------
|
||||||
|
|
||||||
|
* Automatically downloading source from git and performing tag/branch checkouts.
|
||||||
|
* Automatically verifying and translating requirement files to
|
||||||
|
known `pypi`_/`rpm`_ packages.
|
||||||
|
* Automatically installing and building missing dependencies (`pypi`_
|
||||||
|
and `rpm`_) for you.
|
||||||
|
* Automatically configuring the needed files, symlinks, adjustments, and
|
||||||
|
any patches.
|
||||||
|
|
||||||
|
Testing
|
||||||
|
-------
|
||||||
|
|
||||||
|
Automatically running each component unit tests.
|
||||||
|
|
||||||
|
Starting
|
||||||
|
--------
|
||||||
|
|
||||||
|
Starting of the components sub-programs with the needed configuration via the
|
||||||
|
common `sysvinit`_ model.
|
||||||
|
|
||||||
|
Stopping
|
||||||
|
--------
|
||||||
|
|
||||||
|
Stopping of the previously started components.
|
||||||
|
|
||||||
|
Uninstalling
|
||||||
|
------------
|
||||||
|
|
||||||
|
Getting you back to an initial 'clean' state:
|
||||||
|
|
||||||
|
* Removing installed configuration.
|
||||||
|
* Undoing of installed files/directories.
|
||||||
|
* Removing of packages installed.
|
||||||
|
|
||||||
|
Packaging
|
||||||
|
---------
|
||||||
|
|
||||||
|
* Ceating a basic set of packages that matches the components selected.
|
||||||
|
* Supports automatic injection of dependencies.
|
||||||
|
|
||||||
|
Status
|
||||||
|
------
|
||||||
|
|
||||||
|
* Checking the status of the running components sub-programs.
|
||||||
|
|
||||||
|
Pythonic
|
||||||
|
--------
|
||||||
|
|
||||||
|
Written in **python** so it matches the style of other `OpenStack`_ components.
|
||||||
|
|
||||||
|
Code decoupling
|
||||||
|
---------------
|
||||||
|
|
||||||
|
* Components & actions are isolated as individual classes.
|
||||||
|
* Supports installation personas that define what is to be installed, thus
|
||||||
|
decoupling the 'what' from the 'how'.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This encouraging re-use by others...
|
||||||
|
|
||||||
|
Resumption
|
||||||
|
----------
|
||||||
|
|
||||||
|
Install/start/stop resumption so that when you install you can ``ctrl+c`` and
|
||||||
|
resume later (where applicable).
|
||||||
|
|
||||||
|
Extensive logging
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
* All commands executed are logged in standard output, all configuration files
|
||||||
|
read/written (and so on).
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Debug mode can be activated with ``-v`` option...
|
||||||
|
|
||||||
|
Package tracking and building
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
* Creation of a single ``RPM`` set for your installation.
|
||||||
|
|
||||||
|
* This *freezes* what is needed for that release to a known set of
|
||||||
|
packages and dependencies.
|
||||||
|
|
||||||
|
* Automatically building and/or including all needed dependencies.
|
||||||
|
* Includes your distributions *existing* native/pre-built packages (when
|
||||||
|
and where applicable).
|
||||||
|
|
||||||
|
* For example uncommenting the following in the `bootstrap`_ file will allow
|
||||||
|
anvil to find dependencies in the `epel`_ repository.
|
||||||
|
|
||||||
|
.. _bootstrap: http://github.com/stackforge/anvil/blob/master/tools/bootstrap/CommonRedHat#L7
|
||||||
|
.. _OpenStack: http://openstack.org/
|
||||||
.. _chef: http://www.opscode.com/chef/
|
.. _chef: http://www.opscode.com/chef/
|
||||||
|
.. _daemon: http://en.wikipedia.org/wiki/Daemon_(computing)
|
||||||
|
.. _devstack: http://www.devstack.org/
|
||||||
|
.. _epel: http://fedoraproject.org/wiki/EPEL
|
||||||
|
.. _puppet: http://puppetlabs.com/
|
||||||
|
.. _pypi: http://pypi.python.org/pypi
|
||||||
|
.. _rpm: http://www.rpm.org/
|
||||||
.. _salt: http://saltstack.com/
|
.. _salt: http://saltstack.com/
|
||||||
|
.. _sysvinit: http://en.wikipedia.org/wiki/Init
|
||||||
|
.. _yaml: http://www.yaml.org/
|
||||||
|
|||||||
Reference in New Issue
Block a user