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
|
||||
=====================
|
||||
|
||||
.. 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
|
||||
|
||||
topics/summary
|
||||
topics/architecture
|
||||
topics/gettingstarted
|
||||
topics/docs
|
||||
topics/qanda
|
||||
topics/bugshugscode
|
||||
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
|
||||
==================
|
||||
|
||||
Community
|
||||
=========
|
||||
|
||||
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!
|
||||
ANVIL is an open-source tool released under the `apache version 2.0 license`_.
|
||||
It *depends* on its **community** to keep it alive.
|
||||
|
||||
IRC
|
||||
===
|
||||
@@ -29,30 +17,45 @@ Source code
|
||||
|
||||
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
|
||||
----
|
||||
====
|
||||
|
||||
https://bugs.launchpad.net/anvil
|
||||
http://bugs.launchpad.net/anvil
|
||||
|
||||
Branches
|
||||
--------
|
||||
========
|
||||
|
||||
Stable *branches* can also be downloaded:
|
||||
|
||||
https://github.com/stackforge/anvil/branches
|
||||
Anvil tries to work across different OpenStack releases as of the `havana`_
|
||||
release...
|
||||
|
||||
If it does not work across the *majority* of OpenStack `releases`_ please file
|
||||
a `bug`_.
|
||||
|
||||
Hacking
|
||||
=======
|
||||
|
||||
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
|
||||
.. _launchpad’s issue tracking system: http://launchpad.net/anvil
|
||||
.. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/HACKING.md
|
||||
Please visit as often as you want at the following urls:
|
||||
|
||||
- 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
|
||||
.. _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::
|
||||
:maxdepth: 1
|
||||
|
||||
dev_notes/architecture
|
||||
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
|
||||
===============
|
||||
|
||||
|
||||
Simple setup!
|
||||
=============
|
||||
|
||||
Made to be as simple as possible, but not too simple.
|
||||
Made to be as simple as possible, but not too simple...
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
@@ -21,8 +17,8 @@ Read the great documentation for developers/admins at
|
||||
- http://docs.openstack.org/developer/
|
||||
- http://docs.openstack.org/
|
||||
|
||||
This will vastly help you understand what the
|
||||
configurations and options do when ANVIL configures them.
|
||||
This will vastly help you understand what the configurations and options do
|
||||
when ANVIL configures them.
|
||||
|
||||
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
|
||||
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
|
||||
affect the configuration of your compute nodes network.
|
||||
The following settings in ``conf/components/nova.yaml`` are an example of
|
||||
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.
|
||||
|
||||
Please edit the corresponding yaml files in ``conf/components/`` or ``conf/components/personas``
|
||||
to fit your desired configuration of nova/glance and the other OpenStack components.
|
||||
You can use ``-p <conf/components/required_file.yaml>`` option with following commands
|
||||
to use configuration files.
|
||||
Please edit the corresponding yaml files in ``conf/components/`` or
|
||||
``conf/components/personas`` to fit your desired configuration of nova/glance
|
||||
and the other OpenStack components.
|
||||
|
||||
To specify which versions of OpenStack components you want to install select or edit origins configuration
|
||||
file from ``<conf/origins/>`` and use it as follows ``-o <conf/origins/origins_file.yaml>``.
|
||||
.. note::
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
|
||||
@@ -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
|
||||
|
||||
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
|
||||
|
||||
Pre-installing
|
||||
--------------
|
||||
|
||||
In order to ensure that anvil will have its correct dependencies you need to first run the
|
||||
bootstrapping code that will setup said dependencies for your operating system.
|
||||
In order to ensure that anvil will have its correct dependencies you need to
|
||||
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
|
||||
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
|
||||
--------
|
||||
@@ -206,9 +216,10 @@ Now build *OpenStacks* components by running the following:
|
||||
sudo ./smithy -a build
|
||||
|
||||
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]_.
|
||||
One repository will be the dependencies that the OpenStack components need to run and the
|
||||
other will be the OpenStack components themselves.
|
||||
stage being packaged into rpm files and two repositories being setup for
|
||||
you [#verbose]_. One repository will be the dependencies that the OpenStack
|
||||
components need to run and th other will be the OpenStack components
|
||||
themselves.
|
||||
|
||||
Installing
|
||||
----------
|
||||
@@ -227,9 +238,11 @@ step [#verbose]_.
|
||||
**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``
|
||||
|
||||
**Note:** Also to avoid qemu errors please follow the solution @ https://bugs.launchpad.net/anvil/+bug/985786
|
||||
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.
|
||||
**Note:** Also to avoid qemu errors please follow the
|
||||
solution @ https://bugs.launchpad.net/anvil/+bug/985786
|
||||
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
|
||||
please run the following (**after** installation).
|
||||
@@ -244,13 +257,15 @@ please run the following (**after** installation).
|
||||
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
|
||||
|
||||
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
|
||||
--------
|
||||
@@ -311,16 +326,17 @@ First run the following to check the status of each component [#verbose]_.
|
||||
sudo ./smithy -a status
|
||||
|
||||
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
|
||||
about what is occuring.
|
||||
if any of the ``/var/log/nova,glance,keystone,cinder,...`` log files will give
|
||||
you more information about what is occuring.
|
||||
|
||||
::
|
||||
|
||||
sudo ./smithy -a status --show
|
||||
|
||||
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``)
|
||||
and check the ``traces`` directory of each component and check if anything looks fishy.
|
||||
peculaliar can be seen. If nothing can be then go to the installation
|
||||
directory (typically ``~/openstack``) and check the ``traces`` directory of
|
||||
each component and check if anything looks fishy.
|
||||
|
||||
Stopping
|
||||
--------
|
||||
@@ -335,7 +351,8 @@ the following:
|
||||
You should see a set of stop actions happening [#verbose]_. This
|
||||
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``,
|
||||
``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
|
||||
``/var/log/nova,glance,keystone,cinder,...`` files for any useful information on what
|
||||
is happening.
|
||||
``/var/log/nova,glance,keystone,cinder,...`` files for any useful information
|
||||
on what is happening.
|
||||
|
||||
Uninstalling
|
||||
------------
|
||||
|
||||
@@ -7,30 +7,146 @@ Summary
|
||||
Anvil is a forging tool to help build OpenStack components and their
|
||||
dependencies into a complete package-oriented system.
|
||||
|
||||
It automates the git checkouts of the OpenStack components, analyzes & builds their
|
||||
dependencies and the components themselves into packages. It can then install
|
||||
from the package repositories it created, perform configuration and start, stop,
|
||||
restart and uninstall the components and their dependencies as a complete system.
|
||||
It automates the git checkouts of the OpenStack components, analyzes & builds
|
||||
their dependencies and the components themselves into packages. It can then
|
||||
install from the package repositories it created, perform configuration and
|
||||
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
|
||||
(and dependencies) with the help of anvil configuring the components to work
|
||||
correctly for the developer's needs. After the developer has tested out their
|
||||
features or changes they can stop the OpenStack components, uninstall the
|
||||
packages and bring back their system to a pre-installation/pre-anvil state.
|
||||
It allows a developer to setup an environment using the automatically created
|
||||
packages (and dependencies, ex. ``RPMs``) with the help of anvil configuring
|
||||
the components to work correctly for the developer's needs. After the developer
|
||||
has tested out their features or changes they can stop the OpenStack
|
||||
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
|
||||
shell), is that after building those packages (currently RPMs) the same packages
|
||||
can be used later (or at the same time) to actually deploy at a larger scale using
|
||||
tools such as chef_, salt_, or puppet_ (to name a few).
|
||||
shell), is that after building those packages (currently ``RPMs``) the same
|
||||
packages can be used later (or at the same time) to actually deploy at a
|
||||
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/
|
||||
.. _puppet: http://puppetlabs.com/
|
||||
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 `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/
|
||||
.. _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/
|
||||
.. _sysvinit: http://en.wikipedia.org/wiki/Init
|
||||
.. _yaml: http://www.yaml.org/
|
||||
|
||||
Reference in New Issue
Block a user