From 88e5651c2ab3f8fb0495e42972093fd2948977d9 Mon Sep 17 00:00:00 2001 From: Ilya Pekelny Date: Thu, 27 Jun 2013 13:48:06 +0300 Subject: [PATCH] Docs changes Change-Id: Id18c19ed5089a306bbac263a07d7f6e162e43052 --- .../topics/dev_notes/addingowndistro.rst | 2 +- docs/source/topics/dev_notes/architecture.rst | 9 +- docs/source/topics/examples.rst | 8 +- docs/source/topics/features.rst | 120 +++++++++++------- docs/source/topics/gettingstarted.rst | 53 +++++--- docs/source/topics/qanda.rst | 10 +- docs/source/topics/solvedproblems.rst | 20 --- 7 files changed, 130 insertions(+), 92 deletions(-) delete mode 100644 docs/source/topics/solvedproblems.rst diff --git a/docs/source/topics/dev_notes/addingowndistro.rst b/docs/source/topics/dev_notes/addingowndistro.rst index a9208a81..0ef65caf 100644 --- a/docs/source/topics/dev_notes/addingowndistro.rst +++ b/docs/source/topics/dev_notes/addingowndistro.rst @@ -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 diff --git a/docs/source/topics/dev_notes/architecture.rst b/docs/source/topics/dev_notes/architecture.rst index df7b526d..7cdf3617 100644 --- a/docs/source/topics/dev_notes/architecture.rst +++ b/docs/source/topics/dev_notes/architecture.rst @@ -21,7 +21,7 @@ setup toolkit. Since the existing `devstack `_ 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). - - - diff --git a/docs/source/topics/examples.rst b/docs/source/topics/examples.rst index 74694a8a..7870f103 100644 --- a/docs/source/topics/examples.rst +++ b/docs/source/topics/examples.rst @@ -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 diff --git a/docs/source/topics/features.rst b/docs/source/topics/features.rst index d5e0af3d..69ad687e 100644 --- a/docs/source/topics/features.rst +++ b/docs/source/topics/features.rst @@ -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//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). diff --git a/docs/source/topics/gettingstarted.rst b/docs/source/topics/gettingstarted.rst index af1883a4..75d1ea74 100644 --- a/docs/source/topics/gettingstarted.rst +++ b/docs/source/topics/gettingstarted.rst @@ -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 + $ sudo passwd -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 ` ALL=(ALL) ALL` + +Make all the rest of actions as user + +:: + + $ sudo su - 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 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 `` 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 ---------- diff --git a/docs/source/topics/qanda.rst b/docs/source/topics/qanda.rst index a4bf8816..7459da3a 100644 --- a/docs/source/topics/qanda.rst +++ b/docs/source/topics/qanda.rst @@ -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 \ No newline at end of file +.. _cirros: https://launchpad.net/cirros diff --git a/docs/source/topics/solvedproblems.rst b/docs/source/topics/solvedproblems.rst deleted file mode 100644 index 78f71161..00000000 --- a/docs/source/topics/solvedproblems.rst +++ /dev/null @@ -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