x/anvil
Code Issues Proposed changes

Docs changes

Browse Source 
Change-Id: Id18c19ed5089a306bbac263a07d7f6e162e43052
This commit is contained in:
Ilya Pekelny 2013-06-27 13:48:06 +03:00
parent 276fd091e3
commit 88e5651c2a
7 changed files with 130 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -28,7 +28,7 @@ we can add in your own distribution support.
are bootstrapping rhel (and how we are detecting rhel) for an example.
**conf/distros**
This set of yaml files contains defintions for what packages,
This set of yaml files contains definitions for what packages,
what pip to package mappings and what code entrypoints are used
when setting up a given component. The critical key here is the
``platform_pattern`` key which is used as a regular expression to

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

@ -21,7 +21,7 @@ setup toolkit. Since the existing `devstack <http://devstack.org/>`_ did (and st
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.
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*.
@ -57,13 +57,13 @@ Anvil is designed to have the following set of software components:
* Unconfiguring
* Pre-uninstalling
* Uninstalling previously installed packages
* Post-uninstalling
* Post-uninstalling
* Starting
* Pre-starting
* Starting
* Post-starting
* Post-starting
* Stopping
* Testing
@ -123,6 +123,3 @@ Anvil is designed to have the following set of software components:
(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).

8
docs/source/topics/examples.rst
View File

@ -5,6 +5,11 @@
Examples
========
Pre-installing
--------------
See [Getting started! pre-setup] [gs] section to make the right preparation.
Bootstrapping
-------------
@ -150,4 +155,5 @@ Uninstalling
:language: none
:linenos:
[gs]: /en/latest/topics/gettingstarted.html#pre-setup

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

@ -5,63 +5,97 @@
Features
========
- A set of configuration files (in yaml format) that shows common/component/distribution configurations.
- Supports the following *actions* on the various `OpenStack`_ components.
Configurations
--------------
* **Installing**:
A set of configuration files (in yaml format) that shows common/component/distribution configurations.
All the yaml configuration files could be found in:
* 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.
* conf/templates/keystone/
* conf/components/
* conf/distros/
* subdirectories of conf/personas/
* **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.
Installing
----------
* **Stopping**: stopping of the previously started components.
* **Uninstalling**: getting you back to an initial 'clean' state.
* 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.
* Removing installed configuration.
* Undoing of installed files/directories.
* Removing of packages installed.
Testing
-------
* **Testing**: automatically running each components unit tests.
* **Packaging**: creating 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
Automatically running each component unit tests.
- Supports **dry-run** mode (to see what *would* happen).
- Written in **python** so it matches the style of other `OpenStack`_ components.
- **Code decoupling** (thus encouraging re-use by others)
Starting
--------
* Components & actions are isolated as individual classes.
* Supports installation *personas* that define what is to be installed, thus
decoupling the 'what' from the 'how'.
Starting of the components sub-programs with the needed configuration via the common `daemon`_ model.
- **Install/start/stop... resumption** so that when you install you can ``ctrl+c`` and resume later (where applicable).
- Extensive **logging** (and debug mode)
* Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination.
* Trace files could be found in $HOME/openstack/<component>/traces/
* All commands executed are logged, all configuration files read/written (and so on).
Stopping
--------
- **Package tracking and building**
Stopping of the previously started components.
* Creation of a single rpm of your installation.
Uninstalling
------------
* This freezes what is needed
for that release to a known set of packages and dependencies.
Getting you back to an initial 'clean' state:
* Automatically building and/or including all needed dependencies.
* Removing installed configuration.
* Undoing of installed files/directories.
* Removing of packages installed.
* Includes application of your distributions native packages (when applicable).
Packaging
---------
.. _epel: http://fedoraproject.org/wiki/EPEL
.. _forking: http://users.telenet.be/bartl/classicperl/fork/all.html
.. _screen: http://www.manpagez.com/man/1/screen/
.. _upstart: http://upstart.ubuntu.com/
.. _OpenStack: http://openstack.org/
.. _pypi: http://pypi.python.org/pypi
.. _daemon: http://en.wikipedia.org/wiki/Daemon_(computing)
* 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).

53
docs/source/topics/gettingstarted.rst
View File

@ -81,9 +81,9 @@ instances won’t have a `tty`_).
::
$ sudo visudo
$ sudo visudo
Then comment out line:
Then comment out line
::
@ -95,32 +95,32 @@ Also disable selinux:
$ sudo vi /etc/sysconfig/selinux
Change *SELINUX=enforcing* to *SELINUX=disabled* then reboot.
Change `SELINUX=enforcing` to `SELINUX=disabled` then reboot.
::
$ sudo reboot
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.
This can be typically solved by running the following (and then updating the ``instances_path`` option)
Create specifc user to isolate all the Anvil processes from root user
::
$ sudo mkdir -pv /home/openstack
$ sudo chmod -R a+rwx /home/openstack
$ sudo useradd <username>
$ sudo passwd <username>
Also as documented at http://docs.openstack.org/essex/openstack-compute/admin/content/qemu.html#fixes-rhel-qemu
please run the following (**after** installation).
Set user as sudoer
::
$ setsebool -P virt_use_execmem on
$ sudo ln -s /usr/libexec/qemu-kvm /usr/bin/qemu-system-x86_64
$ sudo service libvirtd restart
$ sudo visudo
Add `<username> ALL=(ALL) ALL`
Make all the rest of actions as <username> user
::
$ sudo su - <username>
Get git!
--------
@ -138,6 +138,8 @@ We’ll grab the latest version of ANVIL via git:
::
$ git clone git://github.com/stackforge/anvil.git
$ cd anvil
$ git fetch origin <stable/version>
Configuration
@ -145,8 +147,10 @@ Configuration
Any configuration to be updated should now be done.
Please edit the corresponding files in ``conf/components/`` or ``conf/components/personas``
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.
If you are using a ``FlatManager`` and RH/Fedora then you might want to read and follow:
@ -204,6 +208,23 @@ You should see a set of distribution packages and/or pips being
installed and configuration files being written as ANVIL figures out how to
install your desired components from the prepared packages built in the last
step (if you desire more informational output add a ``-v`` to that command).
``-p`` option is actual too. You can specify conf file just like in ``prepare`` action.
Without specified conf file command will execute with conf/personas/in-a-box/basic.yaml
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).
::
$ setsebool -P virt_use_execmem on # optional
$ sudo ln -s /usr/libexec/qemu-kvm /usr/bin/qemu-system-x86_64
$ sudo service libvirtd restart
Testing
----------

10
docs/source/topics/qanda.rst
View File

@ -9,7 +9,7 @@ How do I cause the anvil dependencies to be reinstalled?
Anvil bootstraps itself via shell script (if you look at the code
in the file ``smithy`` you will see that it is actually a bash
script).
script).
This bootstrapping occurs to ensure that anvils pypi/rpm/deb
dependencies are installed before anvil can actually be used.
@ -20,7 +20,7 @@ and at ``$PWD/.anvil_bootstrapped`` to cause bootstrapping to occur again.
Another way to make this happen temporarily is to use the following:
::
sudo BOOT_FILES=/dev/null ./smithy
This will make anvil think those files are coming from ``/dev/null``
@ -49,7 +49,7 @@ An example of this, lets adjust nova to use the ``stable/essex`` branch.
# Where we download this from...
get_from: "git://github.com/openstack/nova.git?branch=stable/essex"
- The special keywords here are ``branch=``
and ``tag=`` which are ways for anvil to parse out which branch/tag
you desire.
@ -57,7 +57,7 @@ An example of this, lets adjust nova to use the ``stable/essex`` branch.
- **Note:** this is not git official syntax
- **Note:** tag overrides branch (so you can't really include both)
`OMG` the images take forever to download!
------------------------------------------
@ -85,4 +85,4 @@ This will remove the larger ubuntu image and just use the smaller `cirros`_ imag
Note that repeated downloads occur due to the fact that the files inside the image do not match the name of what is installed
into glance (this can be avoided by completely disabling the image uploading, see the persona file for the flag for this).
.. _cirros: https://launchpad.net/cirros
.. _cirros: https://launchpad.net/cirros

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

@ -1,20 +0,0 @@
.. _solved-problems:
===============
Solved Problems
===============
MySQL user denied
-----------------
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
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.
Issue @ https://github.com/pypa/pip/issues/982