x/anvil
Code Issues Proposed changes

Some small doc cleanups.

Browse Source 
Change-Id: Ib1071febe1c08c129b44910bb63b49f28f292b9b
This commit is contained in:
Joshua Harlow 2013-06-05 20:35:14 -07:00
parent 8360035d2d
commit 27f9e46fcf
6 changed files with 68 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/index.rst
View File

@ -4,7 +4,7 @@
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!
---- ----

11
docs/source/topics/bugshugscode.rst
View File

@ -26,7 +26,12 @@ The source code is on github located at:
https://github.com/stackforge/anvil/ https://github.com/stackforge/anvil/
Feel free to fork it and contribute to it. You can also get a tarball or zip archive of the code. Feel free to fork it and contribute to it.
Bugs
----
https://bugs.launchpad.net/anvil
Branches Branches
-------- --------
@ -39,9 +44,9 @@ https://github.com/stackforge/anvil/branches
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`_.
.. _apache version 2.0 license: https://github.com/stackforge/anvil/blob/master/LICENSE .. _apache version 2.0 license: https://github.com/stackforge/anvil/blob/master/LICENSE
.. _launchpad’s issue tracking system: http://launchpad.net/anvil .. _launchpad’s issue tracking system: http://launchpad.net/anvil
.. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/README.md .. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/HACKING.md

13
docs/source/topics/dev_notes/addingowndistro.rst
View File

@ -70,16 +70,3 @@ we can add in your own distribution support.
After adding make sure you reference them in your **conf/distros** yaml file so that the correct subclass will be used. If you are going After adding make sure you reference them in your **conf/distros** yaml file so that the correct subclass will be used. If you are going
to want to create package files from the installed code then you will need to hook-in to a file similar to want to create package files from the installed code then you will need to hook-in to a file similar
to the rpm module that exists there. to the rpm module that exists there.
Bring back the dead!
----------
If you are adding in debian/ubuntu/fedora support please check out the older code that existed that did this
which was removed due to it being unmatained. It might help ease the process if these files are just brought
back from the dead and fixed as needed...
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/anvil/packaging/apt.py
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/anvil/distros/oneiric.py
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/conf/distros/ubuntu-oneiric.yaml
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/conf/distros/fedora-16.yaml

56
docs/source/topics/dev_notes/architecture.rst
View File

@ -1,8 +1,8 @@
.. _architecture: .. _architecture:
==== ========================
How anvil is architected. How anvil is architected
==== ========================
This little ``HOWTO`` can be used by those who wish to This little ``HOWTO`` can be used by those who wish to
understand how anvil does things and why some of its understand how anvil does things and why some of its
@ -11,48 +11,52 @@ architectural decisions were made.
Diving in! Diving in!
---------- ----------
^^^^^^^^^^ ^^^^^^^^^^^^^^^^
A little history A little history
^^^^^^^^^^ ^^^^^^^^^^^^^^^^
Once upon a time there was a idea of replacing the then existing `devstack <http://devstack.org/>`_ 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 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 setup toolkit. Since the existing `devstack <http://devstack.org/>`_ did (and still
does not support very well) complex intercomponent (and interpackage management system) dependencies, does not support very well) complex intercomponent (and interpackage management system) dependencies
and installing/starting/stopping/uninstalling of OpenStack components it was thought and installing/packaging/starting/stopping/uninstalling of OpenStack components.
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.
Never fear though, it was meant to be used by those who actually wanted to understand
the setup of OpenStack by looking at similar code but this was targeted as not being
a necessity. Thus *devstack2* was born which was later renamed *devstack.py* and after a
little while once again got renamed to *anvil*.
^^^^^^^^^^ 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 Structure
^^^^^^^^^^ ^^^^^^^^^
Anvil is designed to have the following set of software components: 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 * **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 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. each step an action may choose to negate a step of another action.
*The currently implemented actions and stages are the following*:
* 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 * Install
* Downloading
* Post-download patching
* Configuring * Configuring
* Pre-installing * Pre-installing
* Installing * Installing packages from previously prepared repository
* Post-installing * Post-installing
* Uninstall * Uninstall
* Unconfiguring * Unconfiguring
* Pre-uninstalling * Pre-uninstalling
* Uninstalling * Uninstalling previously installed packages
* Post-uninstalling * Post-uninstalling
* Starting * Starting
@ -71,14 +75,16 @@ Anvil is designed to have the following set of software components:
into a file so that if ``ctrl-c`` aborts anvil and later the install is restarted 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 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. 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 * **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 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 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 a set of *generic* base classes exist that provide common functionality that
should work in most simplistic installs. These can be found in should work in most simplistic installs. These can be found in
``anvil/components/__init__.py``. All current components that exist either use ``anvil/components/``. All current components that exist either use
these base classes directly or inherit from them and override functions to these base classes directly or inherit from them and override functions to
provide additional capabilities needed to perform the specified action. provide additional capabilities needed to perform the specified action.
* **Distributions:** a distribution is a yaml file that is tied to a operating * **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 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`` manner. Some of these references include how to map a components ``pip-requires``
@ -86,12 +92,13 @@ Anvil is designed to have the following set of software components:
or ``apt``) or what non-specified dependencies are useful in getting the component or ``apt``) or what non-specified dependencies are useful in getting the component
up and running (such as ``guestfish`` for image mounting and manipulation). up and running (such as ``guestfish`` for image mounting and manipulation).
Other helpful references include allowing for components to specify standard Other helpful references include allowing for components to specify standard
identifiers for configuration such as ``pip`` but the underlying yaml file can 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 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 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`` 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 provides this set of references for each component and gets selected based on the
yaml key in that file named *platform_pattern*. yaml key in that file named *platform_pattern*.
* **Configuration:** central to how anvil operates is the ability to be largely * **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). configuration driven (code when you need it but avoid it if you can).
Distributions as seen by the ``conf/distros`` folder specify Distributions as seen by the ``conf/distros`` folder specify
@ -103,7 +110,8 @@ Anvil is designed to have the following set of software components:
configuration drive approach (as much as can be possible) was a key design goal that 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 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 to how anvil has a distribution yaml file that has specified component dependencies
long before the OpenStack community even recgonized such a dependency list was useful. 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 * **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 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 not everyone can agree on what is an install of OpenStack this concept allows for

38
docs/source/topics/features.rst
View File

@ -11,26 +11,26 @@ Features
* **Installing**: * **Installing**:
* Automatically downloading source from git and performing tag/branch checkouts. * Automatically downloading source from git and performing tag/branch checkouts.
* Automatically verifying and translating ``test-requires`` and ``pip-requires`` files to known `pypi`_/rpm packages. * Automatically verifying and translating requirement files to known `pypi`_/rpm packages.
* Automatically installing and building dependencies/packaging (`pypi`_ and rpm) specifics for you. * Automatically installing and building missing dependencies (`pypi`_ and rpm) for you.
* Automatically configuring the needed files, symlinks, adjustments, tweaks. * Automatically configuring the needed files, symlinks, adjustments, and any patches.
* **Starting**: starting of the components sub-programs with * **Starting**: starting of the components sub-programs with
the needed configuration via the common `daemon`_ model the needed configuration via the common `daemon`_ model.
* Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination. * Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination.
* **Stopping**: stopping of the previously started components * **Stopping**: stopping of the previously started components.
* **Uninstalling**: getting you back to an initial 'clean' state * **Uninstalling**: getting you back to an initial 'clean' state.
* Removing installed configuration. * Removing installed configuration.
* Undoing of installed files/directories. * Undoing of installed files/directories.
* Removing of packages installed. * Removing of packages installed.
* **Testing**: running each components unit tests (and in the future performing a simple set of integration tests) * **Testing**: automatically running each components unit tests.
* **Packaging**: creating a basic set of packages that matches the components selected * **Packaging**: creating a basic set of packages that matches the components selected.
- Supports automatic injection of dependencies, creation of change log from git history. - Supports automatic injection of dependencies and creation of a ``changelog`` from git history.
* **Status**: checking the status of the running components sub-programs * **Status**: checking the status of the running components sub-programs
@ -38,25 +38,25 @@ Features
- Written in **python** so it matches the style of other `OpenStack`_ components. - Written in **python** so it matches the style of other `OpenStack`_ components.
- **Code decoupling** (thus encouraging re-use by others) - **Code decoupling** (thus encouraging re-use by others)
* Components/actions are isolated as individual classes... * Components & actions are isolated as individual classes.
* Supports installation *personas* that define what is to be installed, thus * Supports installation *personas* that define what is to be installed, thus
decoupling the 'what' from the 'how'. decoupling the 'what' from the 'how'.
- **Install/start/stop... resumption** so that when you install you can ``ctrl+c`` and resume later (where applicable). - **Install/start/stop... resumption** so that when you install you can ``ctrl+c`` and resume later (where applicable).
- Extensive **logging** (and debug mode) - Extensive **logging** (and debug mode)
* All commands ran are logged, all configuration files read/write... * All commands executed are logged, all configuration files read/written (and so on).
- **Package tracking and building** - **Package tracking and building**
* Anvil can create a single rpm of your installation, as well as build or include all needed dependencies so that * Creation of a single rpm of your installation.
the software that is installed can be installed repeatedly and reliably in the future.
* This allows for installations to use the distributions native packages (when applicable) * This freezes what is needed
as well as provides a list of pips which should be packaged by that distribution before the given `OpenStack`_ release for that release to a known set of packages and dependencies.
is stabilized.
* This also allows for releases of anvil to track exactly how (and what packages and what mapping) is needed for a given * Automatically building and/or including all needed dependencies.
release tag (which maps to a given `OpenStack`_ release tag), thus freezing what is needed for that release to a
known set. * Includes application of your distributions native packages (when applicable).
.. _epel: http://fedoraproject.org/wiki/EPEL .. _epel: http://fedoraproject.org/wiki/EPEL
.. _forking: http://users.telenet.be/bartl/classicperl/fork/all.html .. _forking: http://users.telenet.be/bartl/classicperl/fork/all.html

13
docs/source/topics/solvedproblems.rst
View File

@ -4,12 +4,15 @@
Solved Problems Solved Problems
=============== ===============
MySQL user denied
Solutions
=========
Mysql user denied
----------------- -----------------
This seems common and can be fixed by running one of the steps at This seems common and can be fixed by running one of the steps at
http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html
The temporary folder for building (/tmp/XYZ) is not owned by your user!
-----------------------------------------------------------------------
This is a new feature of pip>=1.3 where it seems to incorrectly handle the SUDO
user. To get around this just remove the above directory and reactivate the
appropriate ANVIL command.