From 2f27addf660d768988b1d9ec199e59584f0d4022 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Tue, 2 Jun 2015 10:18:49 +1000 Subject: [PATCH] Move FAQ to a section-based format Move to a section-based format, and add a TOC so we can see an overview of the questions. Change-Id: Ie480f2ab759a5a7081d4dc7d2491b44a85b6503a --- doc/source/faq.rst | 200 +++++++++++++++++++++++++-------------------- 1 file changed, 112 insertions(+), 88 deletions(-) diff --git a/doc/source/faq.rst b/doc/source/faq.rst index 0437ec26d5..87f84693df 100644 --- a/doc/source/faq.rst +++ b/doc/source/faq.rst @@ -2,99 +2,120 @@ FAQ === -- `General Questions <#general>`__ -- `Operation and Configuration <#ops_conf>`__ -- `Miscellaneous <#misc>`__ +.. contents:: + :local: General Questions ================= -Q: Can I use DevStack for production? +Can I use DevStack for production? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - A: DevStack is targeted at developers and CI systems to use the - raw upstream code. It makes many choices that are not appropriate - for production systems. +DevStack is targeted at developers and CI systems to use the raw +upstream code. It makes many choices that are not appropriate for +production systems. - Your best choice is probably to choose a `distribution of - OpenStack - `__. +Your best choice is probably to choose a `distribution of OpenStack +`__. -Q: Why a shell script, why not chef/puppet/... - A: The script is meant to be read by humans (as well as ran by - computers); it is the primary documentation after all. Using a - recipe system requires everyone to agree and understand chef or - puppet. +Why a shell script, why not chef/puppet/... +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Q: I'd like to help! - A: That isn't a question, but please do! The source for DevStack is - at - `git.openstack.org `__ - and bug reports go to - `LaunchPad `__. Contributions - follow the usual process as described in the `developer - guide `__. This Sphinx - documentation is housed in the doc directory. +The script is meant to be read by humans (as well as ran by +computers); it is the primary documentation after all. Using a recipe +system requires everyone to agree and understand chef or puppet. -Q: Why not use packages? - A: Unlike packages, DevStack leaves your cloud ready to develop - - checkouts of the code and services running in screen. However, many - people are doing the hard work of packaging and recipes for - production deployments. +I'd like to help! +~~~~~~~~~~~~~~~~~ -Q: Why isn't $MY\_FAVORITE\_DISTRO supported? - A: DevStack is meant for developers and those who want to see how - OpenStack really works. DevStack is known to run on the - distro/release combinations listed in ``README.md``. DevStack is - only supported on releases other than those documented in - ``README.md`` on a best-effort basis. +That isn't a question, but please do! The source for DevStack is at +`git.openstack.org +`__ and bug +reports go to `LaunchPad +`__. Contributions follow the +usual process as described in the `developer guide +`__. This +Sphinx documentation is housed in the doc directory. -Q: Are there any differences between Ubuntu and Centos/Fedora support? - A: Both should work well and are tested by DevStack CI. +Why not use packages? +~~~~~~~~~~~~~~~~~~~~~ -Q: Why can't I use another shell? - A: DevStack now uses some specific bash-ism that require Bash 4, such - as associative arrays. Simple compatibility patches have been accepted - in the past when they are not complex, at this point no additional - compatibility patches will be considered except for shells matching - the array functionality as it is very ingrained in the repo and project - management. +Unlike packages, DevStack leaves your cloud ready to develop - +checkouts of the code and services running in screen. However, many +people are doing the hard work of packaging and recipes for production +deployments. -Q: Can I test on OS/X? - A: Some people have success with bash 4 installed via - homebrew to keep running tests on OS/X. +Why isn't $MY\_FAVORITE\_DISTRO supported? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +DevStack is meant for developers and those who want to see how +OpenStack really works. DevStack is known to run on the distro/release +combinations listed in ``README.md``. DevStack is only supported on +releases other than those documented in ``README.md`` on a best-effort +basis. + +Are there any differences between Ubuntu and Centos/Fedora support? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Both should work well and are tested by DevStack CI. + +Why can't I use another shell? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +DevStack now uses some specific bash-ism that require Bash 4, such as +associative arrays. Simple compatibility patches have been accepted in +the past when they are not complex, at this point no additional +compatibility patches will be considered except for shells matching +the array functionality as it is very ingrained in the repo and +project management. + +Can I test on OS/X? +~~~~~~~~~~~~~~~~~~~ + +Some people have success with bash 4 installed via homebrew to keep +running tests on OS/X. Operation and Configuration =========================== -Q: Can DevStack handle a multi-node installation? - A: Yes, see :doc:`multinode lab guide ` +Can DevStack handle a multi-node installation? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Q: How can I document the environment that DevStack is using? - A: DevStack includes a script (``tools/info.sh``) that gathers the - versions of the relevant installed apt packages, pip packages and - git repos. This is a good way to verify what Python modules are - installed. +Yes, see :doc:`multinode lab guide ` -Q: How do I turn off a service that is enabled by default? - A: Services can be turned off by adding ``disable_service xxx`` to - ``local.conf`` (using ``n-vol`` in this example): +How can I document the environment that DevStack is using? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +DevStack includes a script (``tools/info.sh``) that gathers the +versions of the relevant installed apt packages, pip packages and git +repos. This is a good way to verify what Python modules are +installed. + +How do I turn off a service that is enabled by default? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Services can be turned off by adding ``disable_service xxx`` to +``local.conf`` (using ``n-vol`` in this example): :: disable_service n-vol -Q: Is enabling a service that defaults to off done with the reverse of the above? - A: Of course! +Is enabling a service that defaults to off done with the reverse of the above? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Of course! :: enable_service qpid -Q: How do I run a specific OpenStack milestone? - A: OpenStack milestones have tags set in the git repo. Set the - appropriate tag in the ``*_BRANCH`` variables in ``local.conf``. - Swift is on its own release schedule so pick a tag in the Swift repo - that is just before the milestone release. For example: +How do I run a specific OpenStack milestone? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenStack milestones have tags set in the git repo. Set the +appropriate tag in the ``*_BRANCH`` variables in ``local.conf``. +Swift is on its own release schedule so pick a tag in the Swift repo +that is just before the milestone release. For example: :: @@ -107,16 +128,16 @@ Q: How do I run a specific OpenStack milestone? NEUTRON_BRANCH=stable/kilo SWIFT_BRANCH=2.3.0 -Q: What can I do about RabbitMQ not wanting to start on my fresh new VM? - A: This is often caused by ``erlang`` not being happy with the - hostname resolving to a reachable IP address. Make sure your - hostname resolves to a working IP address; setting it to 127.0.0.1 - in ``/etc/hosts`` is often good enough for a single-node - installation. And in an extreme case, use ``clean.sh`` to eradicate - it and try again. +What can I do about RabbitMQ not wanting to start on my fresh new VM? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Q: How can I set up Heat in stand-alone configuration? - A: Configure ``local.conf`` thusly: +This is often caused by ``erlang`` not being happy with the hostname +resolving to a reachable IP address. Make sure your hostname resolves +to a working IP address; setting it to 127.0.0.1 in ``/etc/hosts`` is +often good enough for a single-node installation. And in an extreme +case, use ``clean.sh`` to eradicate it and try again. + +Configure ``local.conf`` thusly: :: @@ -126,22 +147,25 @@ Q: How can I set up Heat in stand-alone configuration? KEYSTONE_SERVICE_HOST= KEYSTONE_AUTH_HOST= -Q: Why are my configuration changes ignored? - A: You may have run into the package prerequisite installation - timeout. ``tools/install_prereqs.sh`` has a timer that skips the - package installation checks if it was run within the last - ``PREREQ_RERUN_HOURS`` hours (default is 2). To override this, set - ``FORCE_PREREQ=1`` and the package checks will never be skipped. +Why are my configuration changes ignored? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You may have run into the package prerequisite installation +timeout. ``tools/install_prereqs.sh`` has a timer that skips the +package installation checks if it was run within the last +``PREREQ_RERUN_HOURS`` hours (default is 2). To override this, set +``FORCE_PREREQ=1`` and the package checks will never be skipped. Miscellaneous ============= -Q: ``tools/fixup_stuff.sh`` is broken and shouldn't 'fix' just one version of packages. - A: [Another not-a-question] No it isn't. Stuff in there is to - correct problems in an environment that need to be fixed elsewhere - or may/will be fixed in a future release. In the case of - ``httplib2`` and ``prettytable`` specific problems with specific - versions are being worked around. If later releases have those - problems than we'll add them to the script. Knowing about the broken - future releases is valuable rather than polling to see if it has - been fixed. +``tools/fixup_stuff.sh`` is broken and shouldn't 'fix' just one version of packages. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Stuff in there is to correct problems in an environment that need to +be fixed elsewhere or may/will be fixed in a future release. In the +case of ``httplib2`` and ``prettytable`` specific problems with +specific versions are being worked around. If later releases have +those problems than we'll add them to the script. Knowing about the +broken future releases is valuable rather than polling to see if it +has been fixed.