From 45fb0dc163de3330026054f4ebe08ff191e14420 Mon Sep 17 00:00:00 2001 From: adreznec Date: Tue, 15 Dec 2015 16:59:22 -0600 Subject: [PATCH] Overhaul the DevStack plugins README file Add a more detailed walkthrough of the devstack plugins readme file, including links to our devrefs and docs. Change-Id: I254b33607daa89c1c8f3dc33d4281cfa4fad72db --- devstack/README.rst | 104 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 83 insertions(+), 21 deletions(-) diff --git a/devstack/README.rst b/devstack/README.rst index eefb617d..a59a0d78 100644 --- a/devstack/README.rst +++ b/devstack/README.rst @@ -1,37 +1,99 @@ ======================== -Installing with Devstack +Installing with DevStack ======================== +What is DevStack? +-------------------------- + +DevStack is a script to quickly create an OpenStack development environment. + +Find out more `here `_. + + +What are DevStack plugins? +-------------------------- + +DevStack plugins act as project-specific extensions of DevStack. They allow external projects to +execute code directly in the DevStack run, supporting configuration and installation changes as +part of the normal local.conf and stack.sh execution. For NovaLink, we have DevStack plugins for +each of our three projects - nova-powervm, networking-powervm, and ceilometer-powervm. These +plugins, with the appropriate local.conf settings for your environment, will allow you to simply +clone down DevStack, configure, run stack.sh, and end up with a working OpenStack/Novalink PowerVM +environment with no other scripting required. + +More details can be `found here. `_ + + +How to use the NovaLink DevStack plugins: +----------------------------------------- + 1. Download DevStack:: $ git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack -2. Modify DevStack's local.conf to pull in this project by adding:: +2. Set up your local.conf file to pull in our projects: + 1. If you have an existing DevStack local.conf, modify it to pull in this project by adding:: - [[local|localrc]] - enable_plugin nova-powervm http://git.openstack.org/openstack/nova-powervm + [[local|localrc]] + enable_plugin nova-powervm http://git.openstack.org/openstack/nova-powervm - Example files are available in the nova-powervm project to provide - reference on using this driver with the corresponding networking-powervm - and ceilometer-powervm drivers. Following these example files will enable - the appropriate drivers and services for each node type. Example config - files for all-in-one, compute, and control nodes `can be found here. `_ + and following the instructions for networking-powervm and ceilometer-powervm + as needed for your environment. -3. See nova-powervm/doc/source/devref/usage.rst, review the configuration options, + 2. If you're setting up DevStack for the first time, example files are available + in the nova-powervm project to provide reference on using this driver with the + corresponding networking-powervm and ceilometer-powervm drivers. Following these + example files will enable the appropriate drivers and services for each node type. + Example config files for all-in-one, compute, and control nodes + `can be found here. `_ + +3. See our devrefs and plugin references for the configuration options for each driver, then configure the installation in local.conf as needed for your environment. - Besides DISK_DRIVER, the default config will be sufficient for most installs. :: - [[local|localrc]] - ... - DISK_DRIVER = - VOL_GRP_NAME = - CLUSTER_NAME = + * nova-powervm + * http://nova-powervm.readthedocs.org/en/latest/devref/index.html + * https://github.com/openstack/nova-powervm/blob/master/devstack/README.rst - [[post-config|$NOVA_CONF]] - [powervm] - ... + * networking-powervm + * http://docs.openstack.org/developer/networking-powervm/devref/index.html + * https://github.com/openstack/networking-powervm/blob/master/devstack/README.rst -4. Run ``stack.sh`` from devstack:: + * ceilometer-powervm + * http://ceilometer-powervm.readthedocs.org/en/latest/devref/index.html + * https://github.com/openstack/ceilometer-powervm/blob/master/devstack/README.rst + +4. For nova-powervm, changing the DISK_DRIVER settings for your environment will be required. + The default configuration for other settings will be sufficient for most installs. :: + + [[local|localrc]] + ... + DISK_DRIVER = + VOL_GRP_NAME = + CLUSTER_NAME = + + [[post-config|$NOVA_CONF]] + [powervm] + ... + +5. A few notes: + + * By default this will pull in the latest/trunk versions of all the projects. If you want to + run a stable version instead, you can either check out that stable branch in the DevStack + repo (git checkout stable/liberty) which is the preferred method, or you can do it on a + project by project basis in the local.conf file as needed. + + * If you need any special services enabled for your environment, you can also specify those + in your local.conf file. In our example files we demonstrate enabling and disabling services + (n-cpu, q-agt, etc) required for our drivers. + +6. Run ``stack.sh`` from DevStack:: $ cd /opt/stack/devstack - $ ./stack.sh + $ FORCE=yes ./stack.sh + + ``FORCE=yes`` is needed on Ubuntu 15.10 since only Ubuntu LTS releases are officially supported + by DevStack. If you're running a control only node on a different, supported OS version you can + skip using ``FORCE=yes``. + +7. At this point DevStack will run through stack.sh, and barring any DevStack issues, you should + end up with a standard link to your Horizon portal at the end of the stack run. Congratulations!