Merge "Replace deprecated datetime.utcnow()"

pre-commit has been introduced to number of projects like oslo to run
lint checks such as hacking. The pre-commit config file does not affect
functionality, so devstack job is not needed when only the file is
updated.

Change-Id: I4294fe0c4df2c36c8575613b05a1f9c2eb745d18

.gitignore

@@ -1,9 +1,13 @@
 *~
 .*.sw?
 *.log
-*.log.[1-9]
+*-log
+*.log.*
+*-log.*
 *.pem
+*.pyc
 .localrc.auto
+.localrc.password
 .prereqs
 .tox
 .stackenv
@@ -11,14 +15,28 @@ accrc
 doc/files
 doc/build
 files/*.gz
+files/*.vmdk
+files/*.rpm
+files/*.rpm.*
+files/*.deb
+files/*.deb.*
 files/*.qcow2
+files/*.img
 files/images
 files/pip-*
-files/get-pip.py
-local.conf
+files/get-pip.py*
+files/ir-deploy*
+files/ironic-inspector*
+files/etcd*
+/local.conf
 local.sh
 localrc
 proto
 shocco
 src
 stack-screenrc
+userrc_early
+AUTHORS
+ChangeLog
+tools/dbcounter/build/
+tools/dbcounter/dbcounter.egg-info/

.gitreview

@@ -1,4 +1,4 @@
 [gerrit]
-host=review.openstack.org
+host=review.opendev.org
 port=29418
-project=openstack-dev/devstack.git
+project=openstack/devstack.git

CONTRIBUTING.rst

@@ -0,0 +1,19 @@
+The source repository for this project can be found at:
+
+   https://opendev.org/openstack/devstack
+
+Pull requests submitted through GitHub are not monitored.
+
+To start contributing to OpenStack, follow the steps in the contribution guide
+to set up and use Gerrit:
+
+   https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
+
+Bugs should be filed on Launchpad:
+
+   https://bugs.launchpad.net/devstack
+
+For more specific information about contributing to this repository, see the
+Devstack contributor guide:
+
+   https://docs.openstack.org/devstack/latest/contributor/contributing.html

FUTURE.rst

@@ -0,0 +1,113 @@
+=============
+ Quo Vadimus
+=============
+
+Where are we going?
+
+This is a document in Devstack to outline where we are headed in the
+future. The future might be near or far, but this is where we'd like
+to be.
+
+This is intended to help people contribute, because it will be a
+little clearer if a contribution takes us closer to or further away to
+our end game.
+
+==================
+ Default Services
+==================
+
+Devstack is designed as a development environment first. There are a
+lot of ways to compose the OpenStack services, but we do need one
+default.
+
+That should be the Compute Layer (currently Glance + Nova + Cinder +
+Neutron Core (not advanced services) + Keystone). It should be the
+base building block going forward, and the introduction point of
+people to OpenStack via Devstack.
+
+================
+ Service Howtos
+================
+
+Starting from the base building block all services included in
+OpenStack should have an overview page in the Devstack
+documentation. That should include the following:
+
+- A helpful high level overview of that service
+- What it depends on (both other OpenStack services and other system
+  components)
+- What new daemons are needed to be started, including where they
+  should live
+
+This provides a map for people doing multinode testing to understand
+what portions are control plane, which should live on worker nodes.
+
+Service how to pages will start with an ugly "This team has provided
+no information about this service" until someone does.
+
+===================
+ Included Services
+===================
+
+Devstack doesn't need to eat the world. Given the existence of the
+external devstack plugin architecture, the future direction is to move
+the bulk of the support code out of devstack itself and into external
+plugins.
+
+This will also promote a more clean separation between services.
+
+=============================
+ Included Backends / Drivers
+=============================
+
+Upstream Devstack should only include Open Source backends / drivers,
+it's intent is for Open Source development of OpenStack. Proprietary
+drivers should be supported via external plugins.
+
+Just being Open Source doesn't mean it should be in upstream Devstack
+if it's not required for base development of OpenStack
+components. When in doubt, external plugins should be used.
+
+========================================
+ OpenStack Services vs. System Services
+========================================
+
+ENABLED_SERVICES is currently entirely too overloaded. We should have
+a separation of actual OpenStack services that you have to run (n-cpu,
+g-api) and required backends like mysql and rabbitmq.
+
+===========================
+ Splitting up of Functions
+===========================
+
+The functions-common file has grown over time, and needs to be split
+up into smaller libraries that handle specific domains.
+
+======================
+ Testing of Functions
+======================
+
+Every function in a functions file should get tests. The devstack
+testing framework is young, but we do have some unit tests for the
+tree, and those should be enhanced.
+
+==============================
+ Not Co-Gating with the World
+==============================
+
+As projects spin up functional test jobs, Devstack should not be
+co-gated with every single one of those. The Devstack team has one of
+the fastest turn arounds for blocking bugs of any Open Stack
+project.
+
+Basic service validation should be included as part of Devstack
+installation to mitigate this.
+
+============================
+ Documenting all the things
+============================
+
+Devstack started off as an explanation as much as an install
+script. We would love contributions to that further enhance the
+comments and explanations about what is happening, even if it seems a
+little pedantic at times.

HACKING.rst

@@ -6,12 +6,12 @@ General
 -------
 
 DevStack is written in UNIX shell script.  It uses a number of bash-isms
-and so is limited to Bash (version 3 and up) and compatible shells.
+and so is limited to Bash (version 4 and up) and compatible shells.
 Shell script was chosen because it best illustrates the steps used to
 set up and interact with OpenStack components.
 
-DevStack's official repository is located on git.openstack.org at
-https://git.openstack.org/openstack-dev/devstack.  Besides the master branch that
+DevStack's official repository is located on opendev.org at
+https://opendev.org/openstack/devstack.  Besides the master branch that
 tracks the OpenStack trunk branches a separate branch is maintained for all
 OpenStack releases starting with Diablo (stable/diablo).
 
@@ -20,28 +20,62 @@ in `How To Contribute`__ in the OpenStack wiki.  `DevStack's LaunchPad project`_
 contains the usual links for blueprints, bugs, etc.
 
 __ contribute_
-.. _contribute: http://docs.openstack.org/infra/manual/developers.html
+.. _contribute: https://docs.openstack.org/infra/manual/developers.html
 
 __ lp_
-.. _lp: https://launchpad.net/~devstack
+.. _lp: https://launchpad.net/devstack
+
+The `Gerrit review
+queue <https://review.opendev.org/#/q/project:openstack/devstack>`__
+is used for all commits.
 
 The primary script in DevStack is ``stack.sh``, which performs the bulk of the
 work for DevStack's use cases.  There is a subscript ``functions`` that contains
 generally useful shell functions and is used by a number of the scripts in
 DevStack.
 
-The ``lib`` directory contains sub-scripts for projects or packages that ``stack.sh``
-sources to perform much of the work related to those projects.  These sub-scripts
-contain configuration defaults and functions to configure, start and stop the project
-or package.  These variables and functions are also used by related projects,
-such as Grenade, to manage a DevStack installation.
-
 A number of additional scripts can be found in the ``tools`` directory that may
 be useful in supporting DevStack installations.  Of particular note are ``info.sh``
 to collect and report information about the installed system, and ``install_prereqs.sh``
 that handles installation of the prerequisite packages for DevStack.  It is
 suitable, for example, to pre-load a system for making a snapshot.
 
+Repo Layout
+-----------
+
+The DevStack repo generally keeps all of the primary scripts at the root
+level.
+
+``doc`` - Contains the Sphinx source for the documentation.
+A complete doc build can be run with ``tox -edocs``.
+
+``extras.d`` - Contains the dispatch scripts called by the hooks in
+``stack.sh``, ``unstack.sh`` and ``clean.sh``. See :doc:`the plugins
+docs <plugins>` for more information.
+
+``files`` - Contains a variety of otherwise lost files used in
+configuring and operating DevStack. This includes templates for
+configuration files and the system dependency information. This is also
+where image files are downloaded and expanded if necessary.
+
+``lib`` - Contains the sub-scripts specific to each project. This is
+where the work of managing a project's services is located. Each
+top-level project (Keystone, Nova, etc) has a file here. Additionally
+there are some for system services and project plugins.  These
+variables and functions are also used by related projects, such as
+Grenade, to manage a DevStack installation.
+
+``samples`` - Contains a sample of the local files not included in the
+DevStack repo.
+
+``tests`` - the DevStack test suite is rather sparse, mostly consisting
+of test of specific fragile functions in the ``functions`` and
+``functions-common`` files.
+
+``tools`` - Contains a collection of stand-alone scripts. While these
+may reference the top-level DevStack configuration they can generally be
+run alone.
+
 
 Scripts
 -------
@@ -110,8 +144,8 @@ follows:
 * Global configuration that may be referenced in ``local.conf``, i.e. ``DEST``, ``DATA_DIR``
 * Global service configuration like ``ENABLED_SERVICES``
 * Variables used by multiple services that do not have a clear owner, i.e.
-  ``VOLUME_BACKING_FILE_SIZE`` (nova-compute, nova-volumes and cinder) or
-  ``PUBLIC_NETWORK_NAME`` (nova-network and neutron)
+  ``VOLUME_BACKING_FILE_SIZE`` (nova-compute and cinder) or
+  ``PUBLIC_NETWORK_NAME`` (only neutron but formerly nova-network too)
 * Variables that can not be cleanly declared in a project file due to
   dependency ordering, i.e. the order of sourcing the project files can
   not be changed for other reasons but the earlier file needs to dereference a
@@ -128,7 +162,7 @@ Documentation
 
 The DevStack repo now contains all of the static pages of devstack.org in
 the ``doc/source`` directory. The OpenStack CI system rebuilds the docs after every
-commit and updates devstack.org (now a redirect to docs.openstack.org/developer/devstack).
+commit and updates devstack.org (now a redirect to https://docs.openstack.org/devstack/latest/).
 
 All of the scripts are processed with shocco_ to render them with the comments
 as text describing the script below.  For this reason we tend to be a little
@@ -143,89 +177,6 @@ The complete docs build is also handled with <code>tox -edocs</code> per the
 OpenStack project standard.
 
 
-Exercises
----------
-
-The scripts in the exercises directory are meant to 1) perform basic operational
-checks on certain aspects of OpenStack; and b) document the use of the
-OpenStack command-line clients.
-
-In addition to the guidelines above, exercise scripts MUST follow the structure
-outlined here.  ``swift.sh`` is perhaps the clearest example of these guidelines.
-These scripts are executed serially by ``exercise.sh`` in testing situations.
-
-* Begin and end with a banner that stands out in a sea of script logs to aid
-  in debugging failures, particularly in automated testing situations.  If the
-  end banner is not displayed, the script ended prematurely and can be assumed
-  to have failed.
-
-  ::
-
-    echo "**************************************************"
-    echo "Begin DevStack Exercise: $0"
-    echo "**************************************************"
-    ...
-    set +o xtrace
-    echo "**************************************************"
-    echo "End DevStack Exercise: $0"
-    echo "**************************************************"
-
-* The scripts will generally have the shell ``xtrace`` attribute set to display
-  the actual commands being executed, and the ``errexit`` attribute set to exit
-  the script on non-zero exit codes::
-
-    # This script exits on an error so that errors don't compound and you see
-    # only the first error that occurred.
-    set -o errexit
-
-    # Print the commands being run so that we can see the command that triggers
-    # an error.  It is also useful for following allowing as the install occurs.
-    set -o xtrace
-
-* Settings and configuration are stored in ``exerciserc``, which must be
-  sourced after ``openrc`` or ``stackrc``::
-
-    # Import exercise configuration
-    source $TOP_DIR/exerciserc
-
-* There are a couple of helper functions in the common ``functions`` sub-script
-  that will check for non-zero exit codes and unset environment variables and
-  print a message and exit the script.  These should be called after most client
-  commands that are not otherwise checked to short-circuit long timeouts
-  (instance boot failure, for example)::
-
-    swift post $CONTAINER
-    die_if_error "Failure creating container $CONTAINER"
-
-    FLOATING_IP=`euca-allocate-address | cut -f2`
-    die_if_not_set FLOATING_IP "Failure allocating floating IP"
-
-* If you want an exercise to be skipped when for example a service wasn't
-  enabled for the exercise to be run, you can exit your exercise with the
-  special exitcode 55 and it will be detected as skipped.
-
-* The exercise scripts should only use the various OpenStack client binaries to
-  interact with OpenStack.  This specifically excludes any ``*-manage`` tools
-  as those assume direct access to configuration and databases, as well as direct
-  database access from the exercise itself.
-
-* If specific configuration needs to be present for the exercise to complete,
-  it should be staged in ``stack.sh``, or called from ``stack.sh`` (see
-  ``files/keystone_data.sh`` for an example of this).
-
-* The ``OS_*`` environment variables should be the only ones used for all
-  authentication to OpenStack clients as documented in the CLIAuth_ wiki page.
-
-.. _CLIAuth: http://wiki.openstack.org/CLIAuth
-
-* The exercise MUST clean up after itself if successful.  If it is not successful,
-  it is assumed that state will be left behind; this allows a chance for developers
-  to look around and attempt to debug the problem.  The exercise SHOULD clean up
-  or graciously handle possible artifacts left over from previous runs if executed
-  again.  It is acceptable to require a reboot or even a re-install of DevStack
-  to restore a clean test environment.
-
-
 Bash Style Guidelines
 ~~~~~~~~~~~~~~~~~~~~~
 DevStack defines a bash set of best practices for maintaining large
@@ -237,7 +188,7 @@ to enforce basic guidelines, similar to pep8 and flake8 tools for Python. The
 list below is not complete for what bashate checks, nor is it all checked
 by bashate.  So many lines of code, so little time.
 
-.. _bashate: https://pypi.python.org/pypi/bashate
+.. _bashate: https://pypi.org/project/bashate/
 
 Whitespace Rules
 ----------------
@@ -249,6 +200,7 @@ Whitespace Rules
 
 Control Structure Rules
 -----------------------
+
 - then should be on the same line as the if
 - do should be on the same line as the for
 
@@ -270,6 +222,7 @@ Example::
 
 Variables and Functions
 -----------------------
+
 - functions should be used whenever possible for clarity
 - functions should use ``local`` variables as much as possible to
   ensure they are isolated from the rest of the environment
@@ -278,3 +231,68 @@ Variables and Functions
 - function names should_have_underscores, NotCamelCase.
 - functions should be declared as per the regex ^function foo {$
   with code starting on the next line
+
+
+Review Criteria
+---------------
+
+There are some broad criteria that will be followed when reviewing
+your change
+
+* **Is it passing tests** -- your change will not be reviewed
+  thoroughly unless the official CI has run successfully against it.
+
+* **Does this belong in DevStack** -- DevStack reviewers have a
+  default position of "no" but are ready to be convinced by your
+  change.
+
+  For very large changes, you should consider :doc:`the plugins system
+  <plugins>` to see if your code is better abstracted from the main
+  repository.
+
+  For smaller changes, you should always consider if the change can be
+  encapsulated by per-user settings in ``local.conf``.  A common example
+  is adding a simple config-option to an ``ini`` file.  Specific flags
+  are not usually required for this, although adding documentation
+  about how to achieve a larger goal (which might include turning on
+  various settings, etc) is always welcome.
+
+* **Work-arounds** -- often things get broken and DevStack can be in a
+  position to fix them.  Work-arounds are fine, but should be
+  presented in the context of fixing the root-cause of the problem.
+  This means it is well-commented in the code and the change-log and
+  mostly likely includes links to changes or bugs that fix the
+  underlying problem.
+
+* **Should this be upstream** -- DevStack generally does not override
+  default choices provided by projects and attempts to not
+  unexpectedly modify behavior.
+
+* **Context in commit messages** -- DevStack touches many different
+  areas and reviewers need context around changes to make good
+  decisions.  We also always want it to be clear to someone -- perhaps
+  even years from now -- why we were motivated to make a change at the
+  time.
+
+
+Making Changes, Testing, and CI
+-------------------------------
+
+Changes to Devstack are tested by automated continuous integration jobs
+that run on a variety of Linux Distros using a handful of common
+configurations. What this means is that every change to Devstack is
+self testing. One major benefit of this is that developers do not
+typically need to add new non voting test jobs to add features to
+Devstack. Instead the features can be added, then if testing passes
+with the feature enabled the change is ready to merge (pending code
+review).
+
+A concrete example of this was the switch from screen based service
+management to systemd based service management. No new jobs were
+created for this. Instead the features were added to devstack, tested
+locally and in CI using a change that enabled the feature, then once
+the enabling change was passing and the new behavior communicated and
+documented it was merged.
+
+Using this process has been proven to be effective and leads to
+quicker implementation of desired features.

MAINTAINERS.rst

@@ -1,92 +0,0 @@
-MAINTAINERS
-===========
-
-
-Overview
---------
-
-The following is a list of people known to have interests in
-particular areas or sub-systems of devstack.
-
-It is a rather general guide intended to help seed the initial
-reviewers list of a change.  A +1 on a review from someone identified
-as being a maintainer of its affected area is a very positive flag to
-the core team for the veracity of the change.
-
-The ``devstack-core`` group can still be added to all reviews.
-
-
-Format
-~~~~~~
-
-The format of the file is the name of the maintainer and their
-gerrit-registered email.
-
-
-Maintainers
------------
-
-.. contents:: :local:
-
-
-Ceph
-~~~~
-
-* Sebastien Han <sebastien.han@enovance.com>
-
-Cinder
-~~~~~~
-
-Fedora/CentOS/RHEL
-~~~~~~~~~~~~~~~~~~
-
-* Ian Wienand <iwienand@redhat.com>
-
-Neutron
-~~~~~~~
-
-OpenDaylight
-~~~~~~~~~~~~
-
-* Kyle Mestery <mestery@mestery.com>
-
-OpenFlow Agent (ofagent)
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-* YAMAMOTO Takashi <yamamoto@valinux.co.jp>
-* Fumihiko Kakuma <kakuma@valinux.co.jp>
-
-Sahara
-~~~~~~
-
-* Sergey Lukjanov <slukjanov@mirantis.com>
-
-Swift
-~~~~~
-
-* Chmouel Boudjnah <chmouel@enovance.com>
-
-SUSE
-~~~~
-
-* Ralf Haferkamp <rhafer@suse.de>
-* Vincent Untz <vuntz@suse.com>
-
-Tempest
-~~~~~~~
-
-Trove
-~~~~~
-
-* Nikhil Manchanda <SlickNik@gmail.com>
-* Michael Basnight <mbasnight@gmail.com>
-
-Xen
-~~~
-* Bob Ball <bob.ball@citrix.com>
-
-Zaqar (Marconi)
-~~~~~~~~~~~~~~~
-
-* Flavio Percoco <flaper87@gmail.com>
-* Malini Kamalambal <malini.kamalambal@rackspace.com>

Makefile

@@ -0,0 +1,100 @@
+# DevStack Makefile of Sanity
+
+# Interesting targets:
+# ds-remote - Create a Git remote for use by ds-push and ds-pull targets
+#             DS_REMOTE_URL must be set on the command line
+#
+# ds-push - Merge a list of branches taken from .ds-test and push them
+#           to the ds-remote repo in ds-test branch
+#
+# ds-pull - Pull the remote ds-test branch into a fresh local branch
+#
+# refresh - Performs a sequence of unstack, refresh and stack
+
+# Duplicated from stackrc for now
+DEST=/opt/stack
+
+all:
+	@echo "This just saved you from a terrible mistake!"
+
+# Do Some Work
+stack:
+	./stack.sh
+
+unstack:
+	./unstack.sh
+
+docs:
+	tox -edocs
+
+# Just run the shocco source formatting build
+docs-build:
+	INSTALL_SHOCCO=True tools/build_docs.sh
+
+# Just run the Sphinx docs build
+docs-rst:
+	python setup.py build_sphinx
+
+# Run the bashate test
+bashate:
+	tox -ebashate
+
+# Run the function tests
+test:
+	tests/test_ini_config.sh
+	tests/test_meta_config.sh
+	tests/test_ip.sh
+	tests/test_refs.sh
+
+# Spiff up the place a bit
+clean:
+	./clean.sh
+	rm -rf accrc doc/build test*-e *.egg-info
+
+# Clean out the cache too
+realclean: clean
+	rm -rf files/cirros*.tar.gz files/Fedora*.qcow2
+
+# Repo stuffs
+
+pull:
+	git pull
+
+
+# These repo targets are used to maintain a branch in a remote repo that
+# consists of one or more local branches merged and pushed to the remote.
+# This is most useful for iterative testing on multiple or remote servers
+# while keeping the working repo local.
+#
+# It requires:
+# * a remote pointing to a remote repo, often GitHub is used for this
+# * a branch name to be used on the remote
+# * a local file containing the list of local branches to be merged into
+#   the remote branch
+
+GIT_REMOTE_NAME=ds-test
+GIT_REMOTE_BRANCH=ds-test
+
+# Push the current branch to a remote named ds-test
+ds-push:
+	git checkout master
+	git branch -D $(GIT_REMOTE_BRANCH) || true
+	git checkout -b $(GIT_REMOTE_BRANCH)
+	for i in $(shell cat .$(GIT_REMOTE_BRANCH) | grep -v "^#" | grep "[^ ]"); do \
+	  git merge --no-edit $$i; \
+	done
+	git push -f $(GIT_REMOTE_NAME) HEAD:$(GIT_REMOTE_BRANCH)
+
+# Pull the ds-test branch
+ds-pull:
+	git checkout master
+	git branch -D $(GIT_REMOTE_BRANCH) || true
+	git pull $(GIT_REMOTE_NAME) $(GIT_REMOTE_BRANCH)
+	git checkout $(GIT_REMOTE_BRANCH)
+
+# Add the remote - set DS_REMOTE_URL=htps://example.com/ on the command line
+ds-remote:
+	git remote add $(GIT_REMOTE_NAME) $(DS_REMOTE_URL)
+
+# Refresh the current DevStack checkout nd re-initialize
+refresh: unstack ds-pull stack

README.md

@@ -1,436 +0,0 @@
-DevStack is a set of scripts and utilities to quickly deploy an OpenStack cloud.
-
-# Goals
-
-* To quickly build dev OpenStack environments in a clean Ubuntu or Fedora
-  environment
-* To describe working configurations of OpenStack (which code branches
-  work together?  what do config files look like for those branches?)
-* To make it easier for developers to dive into OpenStack so that they can
-  productively contribute without having to understand every part of the
-  system at once
-* To make it easy to prototype cross-project features
-* To provide an environment for the OpenStack CI testing on every commit
-  to the projects
-
-Read more at http://devstack.org.
-
-IMPORTANT: Be sure to carefully read `stack.sh` and any other scripts you
-execute before you run them, as they install software and will alter your
-networking configuration.  We strongly recommend that you run `stack.sh`
-in a clean and disposable vm when you are first getting started.
-
-# Versions
-
-The DevStack master branch generally points to trunk versions of OpenStack
-components.  For older, stable versions, look for branches named
-stable/[release] in the DevStack repo.  For example, you can do the
-following to create a grizzly OpenStack cloud:
-
-    git checkout stable/grizzly
-    ./stack.sh
-
-You can also pick specific OpenStack project releases by setting the appropriate
-`*_BRANCH` variables in the ``localrc`` section of `local.conf` (look in
-`stackrc` for the default set).  Usually just before a release there will be
-milestone-proposed branches that need to be tested::
-
-    GLANCE_REPO=git://git.openstack.org/openstack/glance.git
-    GLANCE_BRANCH=milestone-proposed
-
-# Start A Dev Cloud
-
-Installing in a dedicated disposable VM is safer than installing on your
-dev machine!  Plus you can pick one of the supported Linux distros for
-your VM.  To start a dev cloud run the following NOT AS ROOT (see
-**DevStack Execution Environment** below for more on user accounts):
-
-    ./stack.sh
-
-When the script finishes executing, you should be able to access OpenStack
-endpoints, like so:
-
-* Horizon: http://myhost/
-* Keystone: http://myhost:5000/v2.0/
-
-We also provide an environment file that you can use to interact with your
-cloud via CLI:
-
-    # source openrc file to load your environment with OpenStack CLI creds
-    . openrc
-    # list instances
-    nova list
-
-If the EC2 API is your cup-o-tea, you can create credentials and use euca2ools:
-
-    # source eucarc to generate EC2 credentials and set up the environment
-    . eucarc
-    # list instances using ec2 api
-    euca-describe-instances
-
-# DevStack Execution Environment
-
-DevStack runs rampant over the system it runs on, installing things and
-uninstalling other things.  Running this on a system you care about is a recipe
-for disappointment, or worse.  Alas, we're all in the virtualization business
-here, so run it in a VM.  And take advantage of the snapshot capabilities
-of your hypervisor of choice to reduce testing cycle times.  You might even save
-enough time to write one more feature before the next feature freeze...
-
-``stack.sh`` needs to have root access for a lot of tasks, but uses ``sudo``
-for all of those tasks.  However, it needs to be not-root for most of its
-work and for all of the OpenStack services.  ``stack.sh`` specifically
-does not run if started as root.
-
-This is a recent change (Oct 2013) from the previous behaviour of
-automatically creating a ``stack`` user.  Automatically creating
-user accounts is not the right response to running as root, so
-that bit is now an explicit step using ``tools/create-stack-user.sh``.
-Run that (as root!) or just check it out to see what DevStack's
-expectations are for the account it runs under.  Many people simply
-use their usual login (the default 'ubuntu' login on a UEC image
-for example).
-
-# Customizing
-
-You can override environment variables used in `stack.sh` by creating file
-name `local.conf` with a ``localrc`` section as shown below.  It is likely
-that you will need to do this to tweak your networking configuration should
-you need to access your cloud from a different host.
-
-    [[local|localrc]]
-    VARIABLE=value
-
-See the **Local Configuration** section below for more details.
-
-# Database Backend
-
-Multiple database backends are available. The available databases are defined
-in the lib/databases directory.
-`mysql` is the default database, choose a different one by putting the
-following in the `localrc` section:
-
-    disable_service mysql
-    enable_service postgresql
-
-`mysql` is the default database.
-
-# RPC Backend
-
-Multiple RPC backends are available. Currently, this
-includes RabbitMQ (default), Qpid, and ZeroMQ. Your backend of
-choice may be selected via the `localrc` section.
-
-Note that selecting more than one RPC backend will result in a failure.
-
-Example (ZeroMQ):
-
-    ENABLED_SERVICES="$ENABLED_SERVICES,-rabbit,-qpid,zeromq"
-
-Example (Qpid):
-
-    ENABLED_SERVICES="$ENABLED_SERVICES,-rabbit,-zeromq,qpid"
-
-# Apache Frontend
-
-Apache web server can be enabled for wsgi services that support being deployed
-under HTTPD + mod_wsgi. By default, services that recommend running under
-HTTPD + mod_wsgi are deployed under Apache. To use an alternative deployment
-strategy (e.g. eventlet) for services that support an alternative to HTTPD +
-mod_wsgi set ``ENABLE_HTTPD_MOD_WSGI_SERVICES`` to ``False`` in your
-``local.conf``.
-
-Each service that can be run under HTTPD + mod_wsgi also has an override
-toggle available that can be set in your ``local.conf``.
-
-Keystone is run under HTTPD + mod_wsgi by default.
-
-Example (Keystone):
-
-    KEYSTONE_USE_MOD_WSGI="True"
-
-Example (Swift):
-
-    SWIFT_USE_MOD_WSGI="True"
-
-# Swift
-
-Swift is disabled by default.  When enabled, it is configured with
-only one replica to avoid being IO/memory intensive on a small
-vm. When running with only one replica the account, container and
-object services will run directly in screen. The others services like
-replicator, updaters or auditor runs in background.
-
-If you would like to enable Swift you can add this to your `localrc` section:
-
-    enable_service s-proxy s-object s-container s-account
-
-If you want a minimal Swift install with only Swift and Keystone you
-can have this instead in your `localrc` section:
-
-    disable_all_services
-    enable_service key mysql s-proxy s-object s-container s-account
-
-If you only want to do some testing of a real normal swift cluster
-with multiple replicas you can do so by customizing the variable
-`SWIFT_REPLICAS` in your `localrc` section (usually to 3).
-
-# Swift S3
-
-If you are enabling `swift3` in `ENABLED_SERVICES` DevStack will
-install the swift3 middleware emulation. Swift will be configured to
-act as a S3 endpoint for Keystone so effectively replacing the
-`nova-objectstore`.
-
-Only Swift proxy server is launched in the screen session all other
-services are started in background and managed by `swift-init` tool.
-
-# Neutron
-
-Basic Setup
-
-In order to enable Neutron a single node setup, you'll need the
-following settings in your `local.conf`:
-
-    disable_service n-net
-    enable_service q-svc
-    enable_service q-agt
-    enable_service q-dhcp
-    enable_service q-l3
-    enable_service q-meta
-    enable_service q-metering
-    # Optional, to enable tempest configuration as part of DevStack
-    enable_service tempest
-
-Then run `stack.sh` as normal.
-
-DevStack supports setting specific Neutron configuration flags to the
-service, Open vSwitch plugin and LinuxBridge plugin configuration files.
-To make use of this feature, the settings can be added to ``local.conf``.
-The old ``Q_XXX_EXTRA_XXX_OPTS`` variables are deprecated and will be removed
-in the near future.  The ``local.conf`` headers for the replacements are:
-
-* ``Q_SRV_EXTRA_OPTS``:
-
-    [[post-config|/$Q_PLUGIN_CONF_FILE]]
-    [linuxbridge]   # or [ovs]
-
-* ``Q_AGENT_EXTRA_AGENT_OPTS``:
-
-    [[post-config|/$Q_PLUGIN_CONF_FILE]]
-    [agent]
-
-* ``Q_AGENT_EXTRA_SRV_OPTS``:
-
-    [[post-config|/$Q_PLUGIN_CONF_FILE]]
-    [linuxbridge]   # or [ovs]
-
-* ``Q_SRV_EXTRA_DEFAULT_OPTS``:
-
-    [[post-config|$NEUTRON_CONF]]
-    [DEFAULT]
-
-Example extra config in `local.conf`:
-
-    [[post-config|/$Q_PLUGIN_CONF_FILE]]
-    [agent]
-    tunnel_type=vxlan
-    vxlan_udp_port=8472
-
-    [[post-config|$NEUTRON_CONF]]
-    [DEFAULT]
-    tenant_network_type=vxlan
-
-DevStack also supports configuring the Neutron ML2 plugin. The ML2 plugin
-can run with the OVS, LinuxBridge, or Hyper-V agents on compute hosts. This
-is a simple way to configure the ml2 plugin:
-
-    # VLAN configuration
-    Q_PLUGIN=ml2
-    ENABLE_TENANT_VLANS=True
-
-    # GRE tunnel configuration
-    Q_PLUGIN=ml2
-    ENABLE_TENANT_TUNNELS=True
-
-    # VXLAN tunnel configuration
-    Q_PLUGIN=ml2
-    Q_ML2_TENANT_NETWORK_TYPE=vxlan
-
-The above will default in DevStack to using the OVS on each compute host.
-To change this, set the `Q_AGENT` variable to the agent you want to run
-(e.g. linuxbridge).
-
-    Variable Name                    Notes
-    ----------------------------------------------------------------------------
-    Q_AGENT                          This specifies which agent to run with the
-                                     ML2 Plugin (either `openvswitch` or `linuxbridge`).
-    Q_ML2_PLUGIN_MECHANISM_DRIVERS   The ML2 MechanismDrivers to load. The default
-                                     is none. Note, ML2 will work with the OVS
-                                     and LinuxBridge agents by default.
-    Q_ML2_PLUGIN_TYPE_DRIVERS        The ML2 TypeDrivers to load. Defaults to
-                                     all available TypeDrivers.
-    Q_ML2_PLUGIN_GRE_TYPE_OPTIONS    GRE TypeDriver options. Defaults to none.
-    Q_ML2_PLUGIN_VXLAN_TYPE_OPTIONS  VXLAN TypeDriver options. Defaults to none.
-    Q_ML2_PLUGIN_VLAN_TYPE_OPTIONS   VLAN TypeDriver options. Defaults to none.
-
-# Heat
-
-Heat is enabled by default (see `stackrc` file). To disable it explicitly
-you'll need the following settings in your `localrc` section:
-
-    disable_service heat h-api h-api-cfn h-api-cw h-eng
-
-Heat can also run in standalone mode, and be configured to orchestrate
-on an external OpenStack cloud. To launch only Heat in standalone mode
-you'll need the following settings in your `localrc` section:
-
-    disable_all_services
-    enable_service rabbit mysql heat h-api h-api-cfn h-api-cw h-eng
-    HEAT_STANDALONE=True
-    KEYSTONE_SERVICE_HOST=...
-    KEYSTONE_AUTH_HOST=...
-
-# Tempest
-
-If tempest has been successfully configured, a basic set of smoke
-tests can be run as follows:
-
-    $ cd /opt/stack/tempest
-    $ nosetests tempest/scenario/test_network_basic_ops.py
-
-# DevStack on Xenserver
-
-If you would like to use Xenserver as the hypervisor, please refer
-to the instructions in `./tools/xen/README.md`.
-
-# Additional Projects
-
-DevStack has a hook mechanism to call out to a dispatch script at specific
-points in the execution of `stack.sh`, `unstack.sh` and `clean.sh`.  This
-allows upper-layer projects, especially those that the lower layer projects
-have no dependency on, to be added to DevStack without modifying the core
-scripts.  Tempest is built this way as an example of how to structure the
-dispatch script, see `extras.d/80-tempest.sh`.  See `extras.d/README.md`
-for more information.
-
-# Multi-Node Setup
-
-A more interesting setup involves running multiple compute nodes, with Neutron
-networks connecting VMs on different compute nodes.
-You should run at least one "controller node", which should have a `stackrc`
-that includes at least:
-
-    disable_service n-net
-    enable_service q-svc
-    enable_service q-agt
-    enable_service q-dhcp
-    enable_service q-l3
-    enable_service q-meta
-    enable_service neutron
-
-You likely want to change your `localrc` section to run a scheduler that
-will balance VMs across hosts:
-
-    SCHEDULER=nova.scheduler.simple.SimpleScheduler
-
-You can then run many compute nodes, each of which should have a `stackrc`
-which includes the following, with the IP address of the above controller node:
-
-    ENABLED_SERVICES=n-cpu,rabbit,g-api,neutron,q-agt
-    SERVICE_HOST=[IP of controller node]
-    MYSQL_HOST=$SERVICE_HOST
-    RABBIT_HOST=$SERVICE_HOST
-    Q_HOST=$SERVICE_HOST
-    MATCHMAKER_REDIS_HOST=$SERVICE_HOST
-
-# Multi-Region Setup
-
-We want to setup two devstack (RegionOne and RegionTwo) with shared keystone
-(same users and services) and horizon.
-Keystone and Horizon will be located in RegionOne.
-Full spec is available at:
-https://wiki.openstack.org/wiki/Heat/Blueprints/Multi_Region_Support_for_Heat.
-
-In RegionOne:
-
-    REGION_NAME=RegionOne
-
-In RegionTwo:
-
-    disable_service horizon
-    KEYSTONE_SERVICE_HOST=<KEYSTONE_IP_ADDRESS_FROM_REGION_ONE>
-    KEYSTONE_AUTH_HOST=<KEYSTONE_IP_ADDRESS_FROM_REGION_ONE>
-    REGION_NAME=RegionTwo
-
-# Cells
-
-Cells is a new scaling option with a full spec at:
-http://wiki.openstack.org/blueprint-nova-compute-cells.
-
-To setup a cells environment add the following to your `localrc` section:
-
-    enable_service n-cell
-
-Be aware that there are some features currently missing in cells, one notable
-one being security groups.  The exercises have been patched to disable
-functionality not supported by cells.
-
-
-# Local Configuration
-
-Historically DevStack has used ``localrc`` to contain all local configuration
-and customizations. More and more of the configuration variables available for
-DevStack are passed-through to the individual project configuration files.
-The old mechanism for this required specific code for each file and did not
-scale well.  This is handled now by a master local configuration file.
-
-# local.conf
-
-The new config file ``local.conf`` is an extended-INI format that introduces
-a new meta-section header that provides some additional information such
-as a phase name and destination config filename:
-
-    [[ <phase> | <config-file-name> ]]
-
-where ``<phase>`` is one of a set of phase names defined by ``stack.sh``
-and ``<config-file-name>`` is the configuration filename.  The filename is
-eval'ed in the ``stack.sh`` context so all environment variables are
-available and may be used.  Using the project config file variables in
-the header is strongly suggested (see the ``NOVA_CONF`` example below).
-If the path of the config file does not exist it is skipped.
-
-The defined phases are:
-
-* **local** - extracts ``localrc`` from ``local.conf`` before ``stackrc`` is sourced
-* **post-config** - runs after the layer 2 services are configured
-                    and before they are started
-* **extra** - runs after services are started and before any files
-              in ``extra.d`` are executed
-* **post-extra** - runs after files in ``extra.d`` are executed
-
-The file is processed strictly in sequence; meta-sections may be specified more
-than once but if any settings are duplicated the last to appear in the file
-will be used.
-
-    [[post-config|$NOVA_CONF]]
-    [DEFAULT]
-    use_syslog = True
-
-    [osapi_v3]
-    enabled = False
-
-A specific meta-section ``local|localrc`` is used to provide a default
-``localrc`` file (actually ``.localrc.auto``).  This allows all custom
-settings for DevStack to be contained in a single file.  If ``localrc``
-exists it will be used instead to preserve backward-compatibility.
-
-    [[local|localrc]]
-    FIXED_RANGE=10.254.1.0/24
-    ADMIN_PASSWORD=speciale
-    LOGFILE=$DEST/logs/stack.sh.log
-
-Note that ``Q_PLUGIN_CONF_FILE`` is unique in that it is assumed to *NOT*
-start with a ``/`` (slash) character.  A slash will need to be added:
-
-    [[post-config|/$Q_PLUGIN_CONF_FILE]]

README.rst

@@ -0,0 +1,97 @@
+DevStack is a set of scripts and utilities to quickly deploy an OpenStack cloud
+from git source trees.
+
+Goals
+=====
+
+* To quickly build dev OpenStack environments in a clean Ubuntu or RockyLinux
+  environment
+* To describe working configurations of OpenStack (which code branches
+  work together?  what do config files look like for those branches?)
+* To make it easier for developers to dive into OpenStack so that they can
+  productively contribute without having to understand every part of the
+  system at once
+* To make it easy to prototype cross-project features
+* To provide an environment for the OpenStack CI testing on every commit
+  to the projects
+
+Read more at https://docs.openstack.org/devstack/latest
+
+IMPORTANT: Be sure to carefully read `stack.sh` and any other scripts you
+execute before you run them, as they install software and will alter your
+networking configuration.  We strongly recommend that you run `stack.sh`
+in a clean and disposable vm when you are first getting started.
+
+Versions
+========
+
+The DevStack master branch generally points to trunk versions of OpenStack
+components.  For older, stable versions, look for branches named
+stable/[release] in the DevStack repo.  For example, you can do the
+following to create a Zed OpenStack cloud::
+
+    git checkout stable/zed
+    ./stack.sh
+
+You can also pick specific OpenStack project releases by setting the appropriate
+`*_BRANCH` variables in the ``localrc`` section of `local.conf` (look in
+`stackrc` for the default set).  Usually just before a release there will be
+milestone-proposed branches that need to be tested::
+
+    GLANCE_REPO=https://opendev.org/openstack/glance.git
+    GLANCE_BRANCH=milestone-proposed
+
+Start A Dev Cloud
+=================
+
+Installing in a dedicated disposable VM is safer than installing on your
+dev machine!  Plus you can pick one of the supported Linux distros for
+your VM.  To start a dev cloud run the following NOT AS ROOT (see
+**DevStack Execution Environment** below for more on user accounts):
+
+    ./stack.sh
+
+When the script finishes executing, you should be able to access OpenStack
+endpoints, like so:
+
+* Horizon: http://myhost/
+* Keystone: http://myhost/identity/v3/
+
+We also provide an environment file that you can use to interact with your
+cloud via CLI::
+
+    # source openrc file to load your environment with OpenStack CLI creds
+    . openrc
+    # list instances
+    openstack server list
+
+DevStack Execution Environment
+==============================
+
+DevStack runs rampant over the system it runs on, installing things and
+uninstalling other things.  Running this on a system you care about is a recipe
+for disappointment, or worse.  Alas, we're all in the virtualization business
+here, so run it in a VM.  And take advantage of the snapshot capabilities
+of your hypervisor of choice to reduce testing cycle times.  You might even save
+enough time to write one more feature before the next feature freeze...
+
+``stack.sh`` needs to have root access for a lot of tasks, but uses
+``sudo`` for all of those tasks.  However, it needs to be not-root for
+most of its work and for all of the OpenStack services.  ``stack.sh``
+specifically does not run if started as root.
+
+DevStack will not automatically create the user, but provides a helper
+script in ``tools/create-stack-user.sh``.  Run that (as root!) or just
+check it out to see what DevStack's expectations are for the account
+it runs under.  Many people simply use their usual login (the default
+'ubuntu' login on a UEC image for example).
+
+Customizing
+===========
+
+DevStack can be extensively configured via the configuration file
+`local.conf`.  It is likely that you will need to provide and modify
+this file if you want anything other than the most basic setup.  Start
+by reading the `configuration guide
+<https://docs.openstack.org/devstack/latest/configuration.html>`_
+for details of the configuration file and the many available options.

clean.sh

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+#!/bin/bash
 
 # **clean.sh**
 
@@ -26,7 +26,7 @@ if [[ -r $TOP_DIR/.stackenv ]]; then
 fi
 
 # Determine what system we are running on.  This provides ``os_VENDOR``,
-# ``os_RELEASE``, ``os_UPDATE``, ``os_PACKAGE``, ``os_CODENAME``
+# ``os_RELEASE``, ``os_PACKAGE``, ``os_CODENAME``
 # and ``DISTRO``
 GetDistro
 
@@ -41,18 +41,17 @@ source $TOP_DIR/lib/rpc_backend
 source $TOP_DIR/lib/tls
 
 source $TOP_DIR/lib/oslo
+source $TOP_DIR/lib/lvm
 source $TOP_DIR/lib/horizon
 source $TOP_DIR/lib/keystone
 source $TOP_DIR/lib/glance
 source $TOP_DIR/lib/nova
+source $TOP_DIR/lib/placement
 source $TOP_DIR/lib/cinder
 source $TOP_DIR/lib/swift
-source $TOP_DIR/lib/ceilometer
-source $TOP_DIR/lib/heat
 source $TOP_DIR/lib/neutron
-source $TOP_DIR/lib/ironic
-source $TOP_DIR/lib/trove
 
+set -o xtrace
 
 # Extras Source
 # --------------
@@ -64,18 +63,16 @@ if [[ -d $TOP_DIR/extras.d ]]; then
     done
 fi
 
-# See if there is anything running...
-# need to adapt when run_service is merged
-SESSION=$(screen -ls | awk '/[0-9].stack/ { print $1 }')
-if [[ -n "$SESSION" ]]; then
-    # Let unstack.sh do its thing first
-    $TOP_DIR/unstack.sh --all
-fi
+# Let unstack.sh do its thing first
+$TOP_DIR/unstack.sh --all
 
 # Run extras
 # ==========
 
 # Phase: clean
+load_plugin_settings
+run_phase clean
+
 if [[ -d $TOP_DIR/extras.d ]]; then
     for i in $TOP_DIR/extras.d/*.sh; do
         [[ -r $i ]] && source $i clean
@@ -83,12 +80,17 @@ if [[ -d $TOP_DIR/extras.d ]]; then
 fi
 
 # Clean projects
-cleanup_cinder
+
+# BUG: cinder tgt doesn't exit cleanly if it's not running.
+cleanup_cinder || /bin/true
+
 cleanup_glance
 cleanup_keystone
 cleanup_nova
+cleanup_placement
 cleanup_neutron
 cleanup_swift
+cleanup_horizon
 
 if is_service_enabled ldap; then
     cleanup_ldap
@@ -100,7 +102,7 @@ if is_service_enabled nova && [[ -r $NOVA_PLUGINS/hypervisor-$VIRT_DRIVER ]]; th
 fi
 
 # Clean out /etc
-sudo rm -rf /etc/keystone /etc/glance /etc/nova /etc/cinder /etc/swift /etc/heat /etc/neutron
+sudo rm -rf /etc/keystone /etc/glance /etc/nova /etc/cinder /etc/swift /etc/neutron /etc/openstack/
 
 # Clean out tgt
 sudo rm -f /etc/tgt/conf.d/*
@@ -109,18 +111,38 @@ sudo rm -f /etc/tgt/conf.d/*
 cleanup_rpc_backend
 cleanup_database
 
-# Clean out data, logs and status
-LOGDIR=$(dirname "$LOGFILE")
-sudo rm -rf $DATA_DIR $LOGDIR $DEST/status
-if [[ -n "$SCREEN_LOGDIR" ]] && [[ -d "$SCREEN_LOGDIR" ]]; then
-    sudo rm -rf $SCREEN_LOGDIR
+# Clean out data and status
+sudo rm -rf $DATA_DIR $DEST/status $DEST/async
+
+# Clean out the log file and log directories
+if [[ -n "$LOGFILE" ]] && [[ -f "$LOGFILE" ]]; then
+    sudo rm -f $LOGFILE
 fi
+if [[ -n "$LOGDIR" ]] && [[ -d "$LOGDIR" ]]; then
+    sudo rm -rf $LOGDIR
+fi
+
+# Clean out the systemd unit files.
+sudo find $SYSTEMD_DIR -type f -name '*devstack@*service' -delete
+# Make systemd aware of the deletion.
+$SYSTEMCTL daemon-reload
+
+# Clean up venvs
+DIRS_TO_CLEAN="$WHEELHOUSE ${PROJECT_VENV[@]} .config/openstack"
+rm -rf $DIRS_TO_CLEAN
 
 # Clean up files
 
-FILES_TO_CLEAN=".localrc.auto docs/files docs/html shocco/ stack-screenrc test*.conf* test.ini*"
+FILES_TO_CLEAN=".localrc.auto .localrc.password "
+FILES_TO_CLEAN+="docs/files docs/html shocco/ "
+FILES_TO_CLEAN+="stack-screenrc test*.conf* test.ini* "
 FILES_TO_CLEAN+=".stackenv .prereqs"
 
 for file in $FILES_TO_CLEAN; do
     rm -rf $TOP_DIR/$file
 done
+
+rm -rf ~/.config/openstack
+
+# Clear any fstab entries made
+sudo sed -i '/.*comment=devstack-.*/ d' /etc/fstab

data/devstack-plugins-registry.header

@@ -0,0 +1,21 @@
+.. Note to patch submitters:
+
+   # ============================= #
+   # THIS FILE IS AUTOGENERATED !  #
+   # ============================= #
+
+   ** Plugins are found automatically and added to this list **
+
+   This file is created by a periodic proposal job.  You should not
+   edit this file.
+
+   You should edit the files data/devstack-plugins-registry.footer
+   data/devstack-plugins-registry.header to modify this text.
+
+==========================
+ DevStack Plugin Registry
+==========================
+
+The following list is an automatically-generated collection of
+available DevStack plugins.  This includes, but is not limited to,
+official OpenStack projects.

doc/requirements.txt

@@ -0,0 +1,7 @@
+pbr>=2.0.0,!=2.1.0
+
+Pygments
+docutils
+sphinx>=2.0.0,!=2.1.0 # BSD
+openstackdocstheme>=2.2.1 # Apache-2.0
+zuul-sphinx>=0.2.0

doc/source/assets/local.conf

@@ -0,0 +1 @@
+../../../samples/local.conf

doc/source/changes.rst

@@ -1,12 +0,0 @@
-=======
-Changes
-=======
-
-Recent Changes What's been happening?
-=====================================
-
-These are the commits to DevStack for the last six months. For the
-complete list see `the DevStack project in
-Gerrit <https://review.openstack.org/#/q/status:merged+project:openstack-dev/devstack,n,z>`__.
-
-%GIT_LOG%

doc/source/conf.py

@@ -11,9 +11,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
-import os
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -26,7 +23,22 @@ import os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [ 'oslosphinx' ]
+extensions = [
+    'sphinx.ext.autodoc',
+    'zuul_sphinx',
+    'openstackdocstheme',
+]
+
+# openstackdocstheme options
+openstackdocs_repo_name = 'openstack/devstack'
+openstackdocs_pdf_link = True
+openstackdocs_bug_project = 'devstack'
+openstackdocs_bug_tag = ''
+openstackdocs_auto_name = False
+# This repo is not tagged, so don't set versions
+openstackdocs_auto_version = False
+version = ''
+release = ''
 
 todo_include_todos = True
 
@@ -75,7 +87,7 @@ add_module_names = False
 show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'native'
 
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['DevStack-doc.']
@@ -87,7 +99,7 @@ man_pages = []
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'nature'
+html_theme = 'openstackdocs'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -113,11 +125,6 @@ html_theme = 'nature'
 # pixels large.
 #html_favicon = None
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
-html_last_updated_fmt = os.popen(git_cmd).read()
-
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
@@ -161,21 +168,10 @@ htmlhelp_basename = 'DevStack-doc'
 
 # -- Options for LaTeX output --------------------------------------------------
 
-latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-}
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'DevStack-doc.tex', u'DevStack Docs',
+  ('index', 'doc-devstack.tex', u'DevStack Docs',
    u'OpenStack DevStack Team', 'manual'),
 ]
 

doc/source/contributing.rst

@@ -1,94 +0,0 @@
-============
-Contributing
-============
-
-DevStack uses the standard OpenStack contribution process as outlined in
-`the OpenStack developer
-guide <http://docs.openstack.org/infra/manual/developers.html>`__. This
-means that you will need to meet the requirements of the Contribututors
-License Agreement (CLA). If you have already done that for another
-OpenStack project you are good to go.
-
-Things To Know
-==============
-
-|
-| **Where Things Are**
-
-The official DevStack repository is located at
-``git://git.openstack.org/openstack-dev/devstack.git``, replicated from
-the repo maintained by Gerrit. GitHub also has a mirror at
-``git://github.com/openstack-dev/devstack.git``.
-
-The `blueprint <https://blueprints.launchpad.net/devstack>`__ and `bug
-trackers <https://bugs.launchpad.net/devstack>`__ are on Launchpad. It
-should be noted that DevStack generally does not use these as strongly
-as other projects, but we're trying to change that.
-
-The `Gerrit review
-queue <https://review.openstack.org/#/q/project:openstack-dev/devstack,n,z>`__
-is, however, used for all commits except for the text of this website.
-That should also change in the near future.
-
-|
-| **HACKING.rst**
-
-Like most OpenStack projects, DevStack includes a ``HACKING.rst`` file
-that describes the layout, style and conventions of the project. Because
-``HACKING.rst`` is in the main DevStack repo it is considered
-authoritative. Much of the content on this page is taken from there.
-
-|
-| **bashate Formatting**
-
-Around the time of the OpenStack Havana release we added a tool to do
-style checking in DevStack similar to what pep8/flake8 do for Python
-projects. It is still \_very\_ simplistic, focusing mostly on stray
-whitespace to help prevent -1 on reviews that are otherwise acceptable.
-Oddly enough it is called ``bashate``. It will be expanded to enforce
-some of the documentation rules in comments that are used in formatting
-the script pages for devstack.org and possibly even simple code
-formatting. Run it on the entire project with ``./run_tests.sh``.
-
-Code
-====
-
-|
-| **Repo Layout**
-
-The DevStack repo generally keeps all of the primary scripts at the root
-level.
-
-``doc`` - Contains the Sphinx source for the documentation.
-``tools/build_docs.sh`` is used to generate the HTML versions of the
-DevStack scripts.  A complete doc build can be run with ``tox -edocs``.
-
-``exercises`` - Contains the test scripts used to sanity-check and
-demonstrate some OpenStack functions. These scripts know how to exit
-early or skip services that are not enabled.
-
-``extras.d`` - Contains the dispatch scripts called by the hooks in
-``stack.sh``, ``unstack.sh`` and ``clean.sh``. See :doc:`the plugins
-docs <plugins>` for more information.
-
-``files`` - Contains a variety of otherwise lost files used in
-configuring and operating DevStack. This includes templates for
-configuration files and the system dependency information. This is also
-where image files are downloaded and expanded if necessary.
-
-``lib`` - Contains the sub-scripts specific to each project. This is
-where the work of managing a project's services is located. Each
-top-level project (Keystone, Nova, etc) has a file here. Additionally
-there are some for system services and project plugins.
-
-``samples`` - Contains a sample of the local files not included in the
-DevStack repo.
-
-``tests`` - the DevStack test suite is rather sparse, mostly consisting
-of test of specific fragile functions in the ``functions`` and
-``functions-common`` files.
-
-``tools`` - Contains a collection of stand-alone scripts. While these
-may reference the top-level DevStack configuration they can generally be
-run alone. There are also some sub-directories to support specific
-environments such as XenServer.

doc/source/contributor/contributing.rst

@@ -0,0 +1,57 @@
+============================
+So You Want to Contribute...
+============================
+
+For general information on contributing to OpenStack, please check out the
+`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
+It covers all the basics that are common to all OpenStack projects: the accounts
+you need, the basics of interacting with our Gerrit review system, how we
+communicate as a community, etc.
+
+Below will cover the more project specific information you need to get started
+with Devstack.
+
+Communication
+~~~~~~~~~~~~~
+* IRC channel ``#openstack-qa`` at OFTC.
+* Mailing list (prefix subjects with ``[qa][devstack]`` for faster responses)
+  http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
+
+Contacting the Core Team
+~~~~~~~~~~~~~~~~~~~~~~~~
+Please refer to the `Devstack Core Team
+<https://review.opendev.org/#/admin/groups/50,members>`_ contacts.
+
+New Feature Planning
+~~~~~~~~~~~~~~~~~~~~
+If you want to propose a new feature please read `Feature Proposal Process`_
+Devstack features are tracked on `Launchpad BP <https://blueprints.launchpad.net/devstack>`_.
+
+Task Tracking
+~~~~~~~~~~~~~
+We track our tasks in `Launchpad <https://bugs.launchpad.net/devstack>`_.
+
+Reporting a Bug
+~~~~~~~~~~~~~~~
+You found an issue and want to make sure we are aware of it? You can do so on
+`Launchpad <https://bugs.launchpad.net/devstack/+filebug>`__.
+More info about Launchpad usage can be found on `OpenStack docs page
+<https://docs.openstack.org/contributors/common/task-tracking.html#launchpad>`_
+
+Getting Your Patch Merged
+~~~~~~~~~~~~~~~~~~~~~~~~~
+All changes proposed to the Devstack require two ``Code-Review +2`` votes from
+Devstack core reviewers before one of the core reviewers can approve the patch
+by giving ``Workflow +1`` vote. There are 2 exceptions, approving patches to
+unblock the gate and patches that do not relate to the Devstack's core logic,
+like for example old job cleanups, can be approved by single core reviewers.
+
+Project Team Lead Duties
+~~~~~~~~~~~~~~~~~~~~~~~~
+All common PTL duties are enumerated in the `PTL guide
+<https://docs.openstack.org/project-team-guide/ptl.html>`_.
+
+The Release Process for QA is documented in `QA Release Process
+<https://wiki.openstack.org/wiki/QA/releases>`_.
+
+.. _Feature Proposal Process: https://wiki.openstack.org/wiki/QA#Feature_Proposal_.26_Design_discussions

doc/source/debugging.rst

@@ -0,0 +1,52 @@
+=====================
+System-wide debugging
+=====================
+
+A lot can go wrong during a devstack run, and there are a few inbuilt
+tools to help you.
+
+dstat
+-----
+
+Enable the ``dstat`` service to produce performance logs during the
+devstack run.  These will be logged to the journal and also as a CSV
+file.
+
+memory_tracker
+--------------
+
+The ``memory_tracker`` service periodically monitors RAM usage and
+provides consumption output when available memory is seen to be
+falling (i.e. processes are consuming memory).  It also provides
+output showing locked (unswappable) memory.
+
+file_tracker
+------------
+
+The ``file_tracker`` service periodically monitors the number of
+open files in the system.
+
+tcpdump
+-------
+
+Enable the ``tcpdump`` service to run a background tcpdump.  You must
+set the ``TCPDUMP_ARGS`` variable to something suitable (there is no
+default).  For example, to trace iSCSI communication during a job in
+the OpenStack gate and copy the result into the log output, you might
+use:
+
+.. code-block:: yaml
+
+   job:
+     name: devstack-job
+     parent: devstack
+     vars:
+       devstack_services:
+         tcpdump: true
+       devstack_localrc:
+         TCPDUMP_ARGS: "-i any tcp port 3260"
+       zuul_copy_output:
+         '{{ devstack_log_dir }}/tcpdump.pcap': logs
+
+
+

doc/source/development.rst

@@ -0,0 +1,117 @@
+==========================
+ Developing with Devstack
+==========================
+
+Now that you have your nifty DevStack up and running, what can you do
+with it?
+
+Inspecting Services
+===================
+
+By default most services in DevStack are running as `systemd` units
+named `devstack@$servicename.service`. You can see running services
+with.
+
+.. code-block:: bash
+
+   sudo systemctl status "devstack@*"
+
+To learn more about the basics of systemd, see :doc:`/systemd`
+
+Patching a Service
+==================
+
+If you want to make a quick change to a running service the easiest
+way to do that is to change the code directly in /opt/stack/$service
+and then restart the affected daemons.
+
+.. code-block:: bash
+
+   sudo systemctl restart devstack@n-cpu.service
+
+If your change impacts more than one daemon you can restart by
+wildcard as well.
+
+.. code-block:: bash
+
+   sudo systemctl restart "devstack@n-*"
+
+.. warning::
+
+   All changes you are making are in checked out git trees that
+   DevStack thinks it has full control over. Uncommitted work, or
+   work committed to the master branch, may be overwritten during
+   subsequent DevStack runs.
+
+Testing a Patch Series
+======================
+
+When testing a larger set of patches, or patches that will impact more
+than one service within a project, it is often less confusing to use
+custom git locations, and make all your changes in a dedicated git
+tree.
+
+In your ``local.conf`` you can add ``**_REPO``, ``**_BRANCH`` for most projects
+to use a custom git tree instead of the default upstream ones.
+
+For instance:
+
+.. code-block:: bash
+
+   [[local|localrc]]
+   NOVA_REPO=/home/sdague/nova
+   NOVA_BRANCH=fold_disk_config
+
+Will use a custom git tree and branch when doing any devstack
+operations, such as ``stack.sh``.
+
+When testing complicated changes committing to these trees, then doing
+``./unstack.sh && ./stack.sh`` is often a valuable way to
+iterate. This does take longer per iteration than direct patching, as
+the whole devstack needs to rebuild.
+
+You can use this same approach to test patches that are up for review
+in gerrit by using the ref name that gerrit assigns to each change.
+
+.. code-block:: bash
+
+   [[local|localrc]]
+   NOVA_BRANCH=refs/changes/10/353710/1
+
+
+Testing Changes to Libraries
+============================
+
+When testing changes to libraries consumed by OpenStack services (such
+as oslo or any of the python-fooclient libraries) things are a little
+more complicated. By default we only test with released versions of
+these libraries that are on pypi.
+
+You must first override this with the setting ``LIBS_FROM_GIT``. This
+will enable your DevStack with the git version of that library instead
+of the released version.
+
+After that point you can also specify ``**_REPO``, ``**_BRANCH`` to use
+your changes instead of just upstream master.
+
+.. code-block:: bash
+
+   [[local|localrc]]
+   LIBS_FROM_GIT=oslo.policy
+   OSLOPOLICY_REPO=/home/sdague/oslo.policy
+   OSLOPOLICY_BRANCH=better_exception
+
+As libraries are not installed `editable` by pip, after you make any
+local changes you will need to:
+
+* cd to top of library path
+* sudo pip install -U .
+* restart all services you want to use the new library
+
+You can do that with wildcards such as
+
+.. code-block:: bash
+
+   sudo systemctl restart "devstack@n-*"
+
+which will restart all nova services.

doc/source/eucarc.rst

@@ -1,45 +0,0 @@
-=====================
-eucarc - EC2 Settings
-=====================
-
-``eucarc`` creates EC2 credentials for the current user as defined by
-``OS_TENANT_NAME:OS_USERNAME``. ``eucarc`` sources ``openrc`` at the
-beginning (which in turn sources ``stackrc`` and ``localrc``) in order
-to set credentials to create EC2 credentials in Keystone.
-
-EC2\_URL
-    Set the EC2 url for euca2ools. The endpoint is extracted from the
-    service catalog for ``OS_TENANT_NAME:OS_USERNAME``.
-
-    ::
-
-        EC2_URL=$(keystone catalog --service ec2 | awk '/ publicURL / { print $4 }')
-
-S3\_URL
-    Set the S3 endpoint for euca2ools. The endpoint is extracted from
-    the service catalog for ``OS_TENANT_NAME:OS_USERNAME``.
-
-    ::
-
-        export S3_URL=$(keystone catalog --service s3 | awk '/ publicURL / { print $4 }')
-
-EC2\_ACCESS\_KEY, EC2\_SECRET\_KEY
-    Create EC2 credentials for the current tenant:user in Keystone.
-
-    ::
-
-        CREDS=$(keystone ec2-credentials-create)
-        export EC2_ACCESS_KEY=$(echo "$CREDS" | awk '/ access / { print $4 }')
-        export EC2_SECRET_KEY=$(echo "$CREDS" | awk '/ secret / { print $4 }')
-
-Certificates for Bundling
-    Euca2ools requires certificate files to enable bundle uploading. The
-    exercise script ``exercises/bundle.sh`` demonstrated retrieving
-    certificates using the Nova CLI.
-
-    ::
-
-        EC2_PRIVATE_KEY=pk.pem
-        EC2_CERT=cert.pem
-        NOVA_CERT=cacert.pem
-        EUCALYPTUS_CERT=${NOVA_CERT}

doc/source/exerciserc.rst

@@ -1,42 +0,0 @@
-==============================
-exerciserc - Exercise Settings
-==============================
-
-``exerciserc`` is used to configure settings for the exercise scripts.
-The values shown below are the default values. These can all be
-overridden by setting them in the ``localrc`` section.
-
-ACTIVE\_TIMEOUT
-    Max time to wait while vm goes from build to active state
-
-    ::
-
-        ACTIVE_TIMEOUT==30
-
-ASSOCIATE\_TIMEOUT
-    Max time to wait for proper IP association and dis-association.
-
-    ::
-
-        ASSOCIATE_TIMEOUT=15
-
-BOOT\_TIMEOUT
-    Max time till the vm is bootable
-
-    ::
-
-        BOOT_TIMEOUT=30
-
-RUNNING\_TIMEOUT
-    Max time from run instance command until it is running
-
-    ::
-
-        RUNNING_TIMEOUT=$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT))
-
-TERMINATE\_TIMEOUT
-    Max time to wait for a vm to terminate
-
-    ::
-
-        TERMINATE_TIMEOUT=30

doc/source/faq.rst

@@ -2,164 +2,232 @@
 FAQ
 ===
 
--  `General Questions <#general>`__
--  `Operation and Configuration <#ops_conf>`__
--  `Miscellaneous <#misc>`__
+.. contents::
+   :local:
 
 General Questions
 =================
 
-Q: Can I use DevStack for production?
-    A: No. We mean it. Really. DevStack makes some implementation
-    choices that are not appropriate for production deployments. We
-    warned you!
-Q: Then why selinux in enforcing mode?
-    A: That is the default on current Fedora and RHEL releases. DevStack
-    has (rightly so) a bad reputation for its security practices; it has
-    always been meant as a development tool first and system integration
-    later. This is changing as the security issues around OpenStack's
-    use of root (for example) have been tightened and developers need to
-    be better equipped to work in these environments. ``stack.sh``'s use
-    of root is primarily to support the activities that would be handled
-    by packaging in "real" deployments. To remove additional protections
-    that will be desired/required in production would be a step
-    backward.
-Q: But selinux is disabled in RHEL!
-    A: Today it is, yes. That is a specific exception that certain
-    DevStack contributors fought strongly against. The primary reason it
-    was allowed was to support using RHEL6 as the Python 2.6 test
-    platform and that took priority time-wise. This will not be the case
-    with RHEL 7.
-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.
-Q: Why not use Crowbar?
-    A: DevStack is optimized for documentation & developers. As some of
-    us use `Crowbar <https://github.com/dellcloudedge/crowbar>`__ for
-    production deployments, we hope developers documenting how they
-    setup systems for new features supports projects like Crowbar.
-Q: I'd like to help!
-    A: That isn't a question, but please do! The source for DevStack is
-    at
-    `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
-    and bug reports go to
-    `LaunchPad <http://bugs.launchpad.net/devstack/>`__. Contributions
-    follow the usual process as described in the `developer
-    guide <http://docs.openstack.org/infra/manual/developers.html>`__. This Sphinx
-    documentation is housed in the doc directory.
-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. We hope this script serves as a way to
-    communicate configuration changes between developers and packagers.
-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.
-Q: What about Fedora/RHEL/CentOS?
-    A: Fedora and CentOS/RHEL are supported via rpm dependency files and
-    specific checks in ``stack.sh``. Support will follow the pattern set
-    with the Ubuntu testing, i.e. only a single release of the distro
-    will receive regular testing, others will be handled on a
-    best-effort basis.
-Q: Are there any differences between Ubuntu and Fedora support?
-    A: Neutron is not fully supported prior to Fedora 18 due lack of
-    OpenVSwitch packages.
+Can I use DevStack for production?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+<https://www.openstack.org/marketplace/distros/>`__.
+
+Can I use DevStack as a development environment?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sure, you can. That said, there are a couple of things you should note before
+doing so:
+
+- DevStack makes a lot of configuration changes to your system and should not
+  be run in your main development environment.
+
+- All the repositories that DevStack clones when deploying are considered
+  volatile by default and thus are subject to hard resets. This is necessary to
+  keep you in sync with the latest upstream, which is what you want in a CI
+  situation, but it can result in branches being overwritten and files being
+  removed.
+
+  The corollary of this is that if you are working on a specific project, using
+  the DevStack project repository (defaulted to ``/opt/stack/<project>``) as
+  the single master repository for storing all your work is not recommended.
+  This behavior can be overridden by setting the ``RECLONE`` config option to
+  ``no``.  Alternatively, you can avoid running ``stack.sh`` to redeploy by
+  restarting services manually. In any case, you should generally ensure work
+  in progress is pushed to Gerrit or otherwise backed up before running
+  ``stack.sh``.
+
+- If you use DevStack within a VM, you may wish to mount a local OpenStack
+  directory, such as ``~/src/openstack``, inside the VM and configure DevStack
+  to use this as the clone location using the ``{PROJECT}_REPO`` config
+  variables. For example, assuming you're using Vagrant and sharing your home
+  directory, you should place the following in ``local.conf``:
+
+  .. code-block:: shell
+
+     NEUTRON_REPO=/home/vagrant/src/neutron
+     NOVA_REPO=/home/vagrant/src/nova
+     KEYSTONE_REPO=/home/vagrant/src/keystone
+     GLANCE_REPO=/home/vagrant/src/glance
+     SWIFT_REPO=/home/vagrant/src/swift
+     HORIZON_REPO=/home/vagrant/src/horizon
+     CINDER_REPO=/home/vagrant/src/cinder
+     HEAT_REPO=/home/vagrant/src/heat
+     TEMPEST_REPO=/home/vagrant/src/tempest
+     HEATCLIENT_REPO=/home/vagrant/src/python-heatclient
+     GLANCECLIENT_REPO=/home/vagrant/src/python-glanceclient
+     NOVACLIENT_REPO=/home/vagrant/src/python-novaclient
+     NEUTRONCLIENT_REPO=/home/vagrant/src/python-neutronclient
+     OPENSTACKCLIENT_REPO=/home/vagrant/src/python-openstackclient
+     HEAT_CFNTOOLS_REPO=/home/vagrant/src/heat-cfntools
+     HEAT_TEMPLATES_REPO=/home/vagrant/src/heat-templates
+     NEUTRON_FWAAS_REPO=/home/vagrant/src/neutron-fwaas
+     # ...
+
+Why a shell script, why not chef/puppet/...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+I'd like to help!
+~~~~~~~~~~~~~~~~~
+
+That isn't a question, but please do! The source for DevStack is at
+`opendev.org <https://opendev.org/openstack/devstack>`__ and bug
+reports go to `LaunchPad
+<https://bugs.launchpad.net/devstack/>`__. Contributions follow the
+usual process as described in the `developer guide
+<https://docs.openstack.org/infra/manual/developers.html>`__. This
+Sphinx documentation is housed in the doc directory.
+
+Why not use packages?
+~~~~~~~~~~~~~~~~~~~~~
+
+Unlike packages, DevStack leaves your cloud ready to develop -
+checkouts of the code and services running locally under systemd,
+making it easy to hack on and test new patches. However, many people
+are doing the hard work of packaging and recipes for production
+deployments.
+
+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.
+
+Can I at least source ``openrc`` with ``zsh``?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+People have reported success with a special function to run ``openrc``
+through bash for this
+
+.. code-block:: bash
+
+   function sourceopenrc {
+       pushd ~/devstack >/dev/null
+       eval $(bash -c ". openrc $1 $2 >/dev/null;env|sed -n '/OS_/ { s/^/export /;p}'")
+       popd >/dev/null
+   }
+
 
 Operation and Configuration
 ===========================
 
-Q: Can DevStack handle a multi-node installation?
-    A: Indirectly, yes. You run DevStack on each node with the
-    appropriate configuration in ``local.conf``. The primary
-    considerations are turning off the services not required on the
-    secondary nodes, making sure the passwords match and setting the
-    various API URLs to the right place.
-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.
-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):
+Can DevStack handle a multi-node installation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yes, see :doc:`multinode lab guide <guides/multinode-lab>`
+
+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 ``c-vol`` in this example):
 
     ::
 
-        disable_service n-vol
+        disable_service c-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
+        enable_service q-svc
 
-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 release?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    ::
+DevStack master tracks the upstream master of all the projects. If you
+would like to run a stable branch of OpenStack, you should use the
+corresponding stable branch of DevStack as well. For instance the
+``stable/ocata`` version of DevStack will already default to all the
+projects running at ``stable/ocata`` levels.
+
+Note: it's also possible to manually adjust the ``*_BRANCH`` variables
+further if you would like to test specific milestones, or even custom
+out of tree branches. This is done with entries like the following in
+your ``local.conf``
+
+::
 
         [[local|localrc]]
-        GLANCE_BRANCH=stable/grizzly
-        HORIZON_BRANCH=stable/grizzly
-        KEYSTONE_BRANCH=stable/grizzly
-        NOVA_BRANCH=stable/grizzly
-        GLANCE_BRANCH=stable/grizzly
-        NEUTRON_BRANCH=stable/grizzly
-        SWIFT_BRANCH=1.10.0
+        GLANCE_BRANCH=11.0.0.0rc1
+        NOVA_BRANCH=12.0.0.0.rc1
 
-Q: Why not use [STRIKEOUT:``tools/pip-requires``]\ ``requirements.txt`` to grab project dependencies?
-    [STRIKEOUT:The majority of deployments will use packages to install
-    OpenStack that will have distro-based packages as dependencies.
-    DevStack installs as many of these Python packages as possible to
-    mimic the expected production environment.] Certain Linux
-    distributions have a 'lack of workaround' in their Python
-    configurations that installs vendor packaged Python modules and
-    pip-installed modules to the SAME DIRECTORY TREE. This is causing
-    heartache and moving us in the direction of installing more modules
-    from PyPI than vendor packages. However, that is only being done as
-    necessary as the packaging needs to catch up to the development
-    cycle anyway so this is kept to a minimum.
-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.
-Q: How can I set up Heat in stand-alone configuration?
-    A: Configure ``local.conf`` thusly:
 
-    ::
+Upstream DevStack is only tested with master and stable
+branches. Setting custom BRANCH definitions is not guaranteed to
+produce working results.
 
-        [[local|localrc]]
-        HEAT_STANDALONE=True
-        ENABLED_SERVICES=rabbit,mysql,heat,h-api,h-api-cfn,h-api-cw,h-eng
-        KEYSTONE_SERVICE_HOST=<keystone-host>
-        KEYSTONE_AUTH_HOST=<keystone-host>
+What can I do about RabbitMQ not wanting to start on my fresh new VM?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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.
+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.
+
+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.

doc/source/guides.rst

@@ -0,0 +1,80 @@
+Guides
+======
+
+.. warning::
+
+   The guides are point in time contributions, and may not always be
+   up to date with the latest work in devstack.
+
+Walk through various setups used by stackers
+
+.. toctree::
+   :glob:
+   :hidden:
+   :maxdepth: 1
+
+   guides/single-vm
+   guides/single-machine
+   guides/lxc
+   guides/multinode-lab
+   guides/neutron
+   guides/devstack-with-nested-kvm
+   guides/nova
+   guides/devstack-with-octavia
+   guides/devstack-with-ldap
+
+All-In-One Single VM
+--------------------
+
+Run :doc:`OpenStack in a VM <guides/single-vm>`. The VMs launched in your cloud will be slow as
+they are running in QEMU (emulation), but it is useful if you don't have
+spare hardware laying around. :doc:`[Read] <guides/single-vm>`
+
+All-In-One Single Machine
+-------------------------
+
+Run :doc:`OpenStack on dedicated hardware <guides/single-machine>`  This can include a
+server-class machine or a laptop at home.
+:doc:`[Read] <guides/single-machine>`
+
+All-In-One LXC Container
+-------------------------
+
+Run :doc:`OpenStack in a LXC container <guides/lxc>`. Beneficial for intermediate
+and advanced users. The VMs launched in this cloud will be fully accelerated but
+not all OpenStack features are supported. :doc:`[Read] <guides/lxc>`
+
+Multi-Node Lab
+--------------
+
+Setup a :doc:`multi-node cluster <guides/multinode-lab>` with dedicated VLANs for VMs & Management.
+:doc:`[Read] <guides/multinode-lab>`
+
+DevStack with Neutron Networking
+--------------------------------
+
+Building a DevStack cluster with :doc:`Neutron Networking <guides/neutron>`.
+This guide is meant for building lab environments with a dedicated
+control node and multiple compute nodes.
+
+DevStack with KVM-based Nested Virtualization
+---------------------------------------------
+
+Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization
+<guides/devstack-with-nested-kvm>`. With this setup, Nova instances
+will be more performant than with plain QEMU emulation.
+
+Nova and devstack
+--------------------------------
+
+Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
+
+Configure Octavia
+-----------------
+
+Guide on :doc:`Configure Octavia <guides/devstack-with-octavia>`.
+
+Deploying DevStack with LDAP
+----------------------------
+
+Guide to setting up :doc:`DevStack with LDAP <guides/devstack-with-ldap>`.

doc/source/guides/devstack-with-ldap.rst

@@ -0,0 +1,174 @@
+============================
+Deploying DevStack with LDAP
+============================
+
+The OpenStack Identity service has the ability to integrate with LDAP. The goal
+of this guide is to walk you through setting up an LDAP-backed OpenStack
+development environment.
+
+Introduction
+============
+
+LDAP support in keystone is read-only. You can use it to back an entire
+OpenStack deployment to a single LDAP server, or you can use it to back
+separate LDAP servers to specific keystone domains. Users within those domains
+can authenticate against keystone, assume role assignments, and interact with
+other OpenStack services.
+
+Configuration
+=============
+
+To deploy an OpenLDAP server, make sure ``ldap`` is added to the list of
+``ENABLED_SERVICES`` in the ``local.conf`` file::
+
+    enable_service ldap
+
+Devstack will require a password to set up an LDAP administrator. This
+administrative user is also the bind user specified in keystone's configuration
+files, similar to a ``keystone`` user for MySQL databases.
+
+Devstack will prompt you for a password when running ``stack.sh`` if
+``LDAP_PASSWORD`` is not set. You can add the following to your
+``local.conf``::
+
+    LDAP_PASSWORD=super_secret_password
+
+At this point, devstack should have everything it needs to deploy OpenLDAP,
+bootstrap it with a minimal set of users, and configure it to back to a domain
+in keystone. You can do this by running the ``stack.sh`` script::
+
+    $ ./stack.sh
+
+Once ``stack.sh`` completes, you should have a running keystone deployment with
+a basic set of users. It is important to note that not all users will live
+within LDAP. Instead, keystone will back different domains to different
+identity sources. For example, the ``default`` domain will be backed by MySQL.
+This is usually where you'll find your administrative and services users. If
+you query keystone for a list of domains, you should see a domain called
+``Users``. This domain is set up by devstack and points to OpenLDAP.
+
+User Management
+===============
+
+Initially, there will only be two users in the LDAP server. The ``Manager``
+user is used by keystone to talk to OpenLDAP. The ``demo`` user is a generic
+user that you should be able to see if you query keystone for users within the
+``Users`` domain. Both of these users were added to LDAP using basic LDAP
+utilities installed by devstack (e.g. ``ldap-utils``) and LDIFs. The LDIFs used
+to create these users can be found in ``devstack/files/ldap/``.
+
+Listing Users
+-------------
+
+To list all users in LDAP directly, you can use ``ldapsearch`` with the LDAP
+user bootstrapped by devstack::
+
+    $ ldapsearch -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
+        -H ldap://localhost -b dc=openstack,dc=org
+
+As you can see, devstack creates an OpenStack domain called ``openstack.org``
+as a container for the ``Manager`` and ``demo`` users.
+
+Creating Users
+--------------
+
+Since keystone's LDAP integration is read-only, users must be added directly to
+LDAP. Users added directly to OpenLDAP will automatically be placed into the
+``Users`` domain.
+
+LDIFs can be used to add users via the command line. The following is an
+example LDIF that can be used to create a new LDAP user, let's call it
+``peter.ldif.in``::
+
+    dn: cn=peter,ou=Users,dc=openstack,dc=org
+    cn: peter
+    displayName: Peter Quill
+    givenName: Peter Quill
+    mail: starlord@openstack.org
+    objectClass: inetOrgPerson
+    objectClass: top
+    sn: peter
+    uid: peter
+    userPassword: im-a-better-pilot-than-rocket
+
+Now, we use the ``Manager`` user to create a user for Peter in LDAP::
+
+    $ ldapadd -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
+        -H ldap://localhost -c -f peter.ldif.in
+
+We should be able to assign Peter roles on projects. After Peter has some level
+of authorization, he should be able to login to Horizon by specifying the
+``Users`` domain and using his ``peter`` username and password. Authorization
+can be given to Peter by creating a project within the ``Users`` domain and
+giving him a role assignment on that project::
+
+    $ openstack project create --domain Users awesome-mix-vol-1
+    +-------------+----------------------------------+
+    | Field       | Value                            |
+    +-------------+----------------------------------+
+    | description |                                  |
+    | domain_id   | 61a2de23107c46bea2d758167af707b9 |
+    | enabled     | True                             |
+    | id          | 7d422396d54945cdac8fe1e8e32baec4 |
+    | is_domain   | False                            |
+    | name        | awesome-mix-vol-1                |
+    | parent_id   | 61a2de23107c46bea2d758167af707b9 |
+    | tags        | []                               |
+    +-------------+----------------------------------+
+    $ openstack role add --user peter --user-domain Users \
+          --project awesome-mix-vol-1 --project-domain Users admin
+
+
+Deleting Users
+--------------
+
+We can use the same basic steps to remove users from LDAP, but instead of using
+LDIFs, we can just pass the ``dn`` of the user we want to delete::
+
+    $ ldapdelete -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
+        -H ldap://localhost cn=peter,ou=Users,dc=openstack,dc=org
+
+Group Management
+================
+
+Like users, groups are considered specific identities. This means that groups
+also fall under the same read-only constraints as users and they can be managed
+directly with LDAP in the same way users are with LDIFs.
+
+Adding Groups
+-------------
+
+Let's define a specific group with the following LDIF::
+
+    dn: cn=guardians,ou=UserGroups,dc=openstack,dc=org
+    objectClass: groupOfNames
+    cn: guardians
+    description: Guardians of the Galaxy
+    member: cn=peter,dc=openstack,dc=org
+    member: cn=gamora,dc=openstack,dc=org
+    member: cn=drax,dc=openstack,dc=org
+    member: cn=rocket,dc=openstack,dc=org
+    member: cn=groot,dc=openstack,dc=org
+
+We can create the group using the same ``ldapadd`` command as we did with
+users::
+
+    $ ldapadd -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
+        -H ldap://localhost -c -f guardian-group.ldif.in
+
+If we check the group membership in Horizon, we'll see that only Peter is a
+member of the ``guardians`` group, despite the whole crew being specified in
+the LDIF. Once those accounts are created in LDAP, they will automatically be
+added to the ``guardians`` group. They will also assume any role assignments
+given to the ``guardians`` group.
+
+Deleting Groups
+---------------
+
+Just like users, groups can be deleted using the ``dn``::
+
+    $ ldapdelete -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
+        -H ldap://localhost cn=guardians,ou=UserGroups,dc=openstack,dc=org
+
+Note that this operation will not remove users within that group. It will only
+remove the group itself and the memberships any users had with that group.

doc/source/guides/devstack-with-nested-kvm.rst

@@ -0,0 +1,141 @@
+.. _kvm_nested_virt:
+
+=======================================================
+Configure DevStack with KVM-based Nested Virtualization
+=======================================================
+
+When using virtualization technologies like KVM, one can take advantage
+of "Nested VMX" (i.e. the ability to run KVM on KVM) so that the VMs in
+cloud (Nova guests) can run relatively faster than with plain QEMU
+emulation.
+
+Kernels shipped with Linux distributions doesn't have this enabled by
+default. This guide outlines the configuration details to enable nested
+virtualization in KVM-based environments. And how to setup DevStack
+(that'll run in a VM) to take advantage of this.
+
+
+Nested Virtualization Configuration
+===================================
+
+Configure Nested KVM for Intel-based Machines
+---------------------------------------------
+
+Procedure to enable nested KVM virtualization on Intel-based machines.
+
+Check if the nested KVM Kernel parameter is enabled:
+
+::
+
+    cat /sys/module/kvm_intel/parameters/nested
+    N
+
+Temporarily remove the KVM intel Kernel module, enable nested
+virtualization to be persistent across reboots and add the Kernel
+module back:
+
+::
+
+    sudo rmmod kvm-intel
+    sudo sh -c "echo 'options kvm-intel nested=y' >> /etc/modprobe.d/dist.conf"
+    sudo modprobe kvm-intel
+
+Ensure the Nested KVM Kernel module parameter for Intel is enabled on
+the host:
+
+::
+
+    cat /sys/module/kvm_intel/parameters/nested
+    Y
+
+    modinfo kvm_intel | grep nested
+    parm:           nested:bool
+
+Start your VM, now it should have KVM capabilities -- you can verify
+that by ensuring ``/dev/kvm`` character device is present.
+
+
+Configure Nested KVM for AMD-based Machines
+-------------------------------------------
+
+Procedure to enable nested KVM virtualization on AMD-based machines.
+
+Check if the nested KVM Kernel parameter is enabled:
+
+::
+
+    cat /sys/module/kvm_amd/parameters/nested
+    0
+
+
+Temporarily remove the KVM AMD Kernel module, enable nested
+virtualization to be persistent across reboots and add the Kernel module
+back:
+
+::
+
+    sudo rmmod kvm-amd
+    sudo sh -c "echo 'options kvm-amd nested=1' >> /etc/modprobe.d/dist.conf"
+    sudo modprobe kvm-amd
+
+Ensure the Nested KVM Kernel module parameter for AMD is enabled on the
+host:
+
+::
+
+    cat /sys/module/kvm_amd/parameters/nested
+    1
+
+    modinfo kvm_amd | grep -i nested
+    parm:           nested:int
+
+To make the above value persistent across reboots, add an entry in
+/etc/modprobe.d/dist.conf so it looks as below::
+
+    cat /etc/modprobe.d/dist.conf
+    options kvm-amd nested=y
+
+
+Expose Virtualization Extensions to DevStack VM
+-----------------------------------------------
+
+Edit the VM's libvirt XML configuration via ``virsh`` utility:
+
+::
+
+    sudo virsh edit devstack-vm
+
+Add the below snippet to expose the host CPU features to the VM:
+
+::
+
+    <cpu mode='host-passthrough'>
+    </cpu>
+
+
+Ensure DevStack VM is Using KVM
+-------------------------------
+
+Before invoking ``stack.sh`` in the VM, ensure that KVM is enabled. This
+can be verified by checking for the presence of the file ``/dev/kvm`` in
+your VM. If it is present, DevStack will default to using the config
+attribute ``virt_type = kvm`` in ``/etc/nova.conf``; otherwise, it'll fall
+back to ``virt_type=qemu``, i.e. plain QEMU emulation.
+
+Optionally, to explicitly set the type of virtualization, to KVM, by the
+libvirt driver in nova, the below config attribute can be used in
+DevStack's ``local.conf``:
+
+::
+
+    LIBVIRT_TYPE=kvm
+
+
+Once DevStack is configured successfully, verify if the Nova instances
+are using KVM by noticing the QEMU CLI invoked by Nova is using the
+parameter ``accel=kvm``, e.g.:
+
+::
+
+    ps -ef | grep -i qemu
+    root     29773     1  0 11:24 ?        00:00:00 /usr/bin/qemu-system-x86_64 -machine accel=kvm [. . .]

doc/source/guides/devstack-with-octavia.rst

@@ -0,0 +1,144 @@
+Devstack with Octavia Load Balancing
+====================================
+
+Starting with the OpenStack Pike release, Octavia is now a standalone service
+providing load balancing services for OpenStack.
+
+This guide will show you how to create a devstack with `Octavia API`_ enabled.
+
+.. _Octavia API: https://docs.openstack.org/api-ref/load-balancer/v2/index.html
+
+Phase 1: Create DevStack + 2 nova instances
+--------------------------------------------
+
+First, set up a VM of your choice with at least 8 GB RAM and 16 GB disk space,
+make sure it is updated. Install git and any other developer tools you find
+useful.
+
+Install devstack::
+
+    git clone https://opendev.org/openstack/devstack
+    cd devstack/tools
+    sudo ./create-stack-user.sh
+    cd ../..
+    sudo mv devstack /opt/stack
+    sudo chown -R stack.stack /opt/stack/devstack
+
+This will clone the current devstack code locally, then setup the "stack"
+account that devstack services will run under. Finally, it will move devstack
+into its default location in /opt/stack/devstack.
+
+Edit your ``/opt/stack/devstack/local.conf`` to look like::
+
+    [[local|localrc]]
+    # ===== BEGIN localrc =====
+    DATABASE_PASSWORD=password
+    ADMIN_PASSWORD=password
+    SERVICE_PASSWORD=password
+    SERVICE_TOKEN=password
+    RABBIT_PASSWORD=password
+    GIT_BASE=https://opendev.org
+    # Optional settings:
+    # OCTAVIA_AMP_BASE_OS=centos
+    # OCTAVIA_AMP_DISTRIBUTION_RELEASE_ID=9-stream
+    # OCTAVIA_AMP_IMAGE_SIZE=3
+    # OCTAVIA_LB_TOPOLOGY=ACTIVE_STANDBY
+    # OCTAVIA_ENABLE_AMPHORAV2_JOBBOARD=True
+    # LIBS_FROM_GIT+=octavia-lib,
+    # Enable Logging
+    LOGFILE=$DEST/logs/stack.sh.log
+    VERBOSE=True
+    LOG_COLOR=True
+    enable_service rabbit
+    enable_plugin neutron $GIT_BASE/openstack/neutron
+    # Octavia supports using QoS policies on the VIP port:
+    enable_service q-qos
+    enable_service placement-api placement-client
+    # Octavia services
+    enable_plugin octavia $GIT_BASE/openstack/octavia master
+    enable_plugin octavia-dashboard $GIT_BASE/openstack/octavia-dashboard
+    enable_plugin ovn-octavia-provider $GIT_BASE/openstack/ovn-octavia-provider
+    enable_plugin octavia-tempest-plugin $GIT_BASE/openstack/octavia-tempest-plugin
+    enable_service octavia o-api o-cw o-hm o-hk o-da
+    # If you are enabling barbican for TLS offload in Octavia, include it here.
+    # enable_plugin barbican $GIT_BASE/openstack/barbican
+    # enable_service barbican
+    # Cinder (optional)
+    disable_service c-api c-vol c-sch
+    # Tempest
+    enable_service tempest
+    # ===== END localrc =====
+
+.. note::
+    For best performance it is highly recommended to use KVM
+    virtualization instead of QEMU.
+    Also make sure nested virtualization is enabled as documented in
+    :ref:`the respective guide <kvm_nested_virt>`.
+    By adding ``LIBVIRT_CPU_MODE="host-passthrough"`` to your
+    ``local.conf`` you enable the guest VMs to make use of all features your
+    host's CPU provides.
+
+Run stack.sh and do some sanity checks::
+
+    sudo su - stack
+    cd /opt/stack/devstack
+    ./stack.sh
+    . ./openrc
+
+    openstack network list  # should show public and private networks
+
+Create two nova instances that we can use as test http servers::
+
+    # create nova instances on private network
+    openstack server create --image $(openstack image list | awk '/ cirros-.*-x86_64-.* / {print $2}') --flavor 1 --nic net-id=$(openstack network list | awk '/ private / {print $2}') node1
+    openstack server create --image $(openstack image list | awk '/ cirros-.*-x86_64-.* / {print $2}') --flavor 1 --nic net-id=$(openstack network list | awk '/ private / {print $2}') node2
+    openstack server list # should show the nova instances just created
+
+    # add secgroup rules to allow ssh etc..
+    openstack security group rule create default --protocol icmp
+    openstack security group rule create default --protocol tcp --dst-port 22:22
+    openstack security group rule create default --protocol tcp --dst-port 80:80
+
+Set up a simple web server on each of these instances. One possibility is to use
+the `Golang test server`_ that is used by the Octavia project for CI testing
+as well.
+Copy the binary to your instances and start it as shown below
+(username 'cirros', password 'gocubsgo')::
+
+    INST_IP=<instance IP>
+    scp -O test_server.bin cirros@${INST_IP}:
+    ssh -f cirros@${INST_IP} ./test_server.bin -id ${INST_IP}
+
+When started this way the test server will respond to HTTP requests with
+its own IP.
+
+Phase 2: Create your load balancer
+----------------------------------
+
+Create your load balancer::
+
+    openstack loadbalancer create --wait --name lb1 --vip-subnet-id private-subnet
+    openstack loadbalancer listener create --wait --protocol HTTP --protocol-port 80 --name listener1 lb1
+    openstack loadbalancer pool create --wait --lb-algorithm ROUND_ROBIN --listener listener1 --protocol HTTP --name pool1
+    openstack loadbalancer healthmonitor create --wait --delay 5 --timeout 2 --max-retries 1 --type HTTP pool1
+    openstack loadbalancer member create --wait --subnet-id private-subnet --address <web server 1 address> --protocol-port 80 pool1
+    openstack loadbalancer member create --wait --subnet-id private-subnet --address <web server 2 address> --protocol-port 80 pool1
+
+Please note: The <web server # address> fields are the IP addresses of the nova
+servers created in Phase 1.
+Also note, using the API directly you can do all of the above commands in one
+API call.
+
+Phase 3: Test your load balancer
+--------------------------------
+
+::
+
+    openstack loadbalancer show lb1 # Note the vip_address
+    curl http://<vip_address>
+    curl http://<vip_address>
+
+This should show the "Welcome to <IP>" message from each member server.
+
+
+.. _Golang test server: https://opendev.org/openstack/octavia-tempest-plugin/src/branch/master/octavia_tempest_plugin/contrib/test_server

doc/source/guides/lxc.rst

@@ -0,0 +1,164 @@
+================================
+All-In-One Single LXC Container
+================================
+
+This guide walks you through the process of deploying OpenStack using devstack
+in an LXC container instead of a VM.
+
+The primary benefits to running devstack inside a container instead of a VM is
+faster performance and lower memory overhead while still providing a suitable
+level of isolation. This can be particularly useful when you want to simulate
+running OpenStack on multiple nodes.
+
+.. Warning:: Containers do not provide the same level of isolation as a virtual
+   machine.
+
+.. Note:: Not all OpenStack features support running inside of a container. See
+   `Limitations`_ section below for details. :doc:`OpenStack in a VM <single-vm>`
+   is recommended for beginners.
+
+Prerequisites
+==============
+
+This guide is written for Ubuntu 14.04 but should be adaptable for any modern
+Linux distribution.
+
+Install the LXC package::
+
+   sudo apt-get install lxc
+
+You can verify support for containerization features in your currently running
+kernel using the ``lxc-checkconfig`` command.
+
+Container Setup
+===============
+
+Configuration
+---------------
+
+For a successful run of ``stack.sh`` and to permit use of KVM to run the VMs you
+launch inside your container, we need to use the following additional
+configuration options. Place the following in a file called
+``devstack-lxc.conf``::
+
+  # Permit access to /dev/loop*
+  lxc.cgroup.devices.allow = b 7:* rwm
+  
+  # Setup access to /dev/net/tun and /dev/kvm
+  lxc.mount.entry = /dev/net/tun dev/net/tun none bind,create=file 0 0
+  lxc.mount.entry = /dev/kvm dev/kvm none bind,create=file 0 0
+  
+  # Networking
+  lxc.network.type = veth
+  lxc.network.flags = up
+  lxc.network.link = lxcbr0
+
+
+Create Container
+-------------------
+
+The configuration and rootfs for LXC containers are created using the
+``lxc-create`` command.
+
+We will name our container ``devstack`` and use the ``ubuntu`` template which
+will use ``debootstrap`` to build a Ubuntu rootfs. It will default to the same
+release and architecture as the host system. We also install the additional
+packages ``bsdmainutils`` and ``git`` as we'll need them to run devstack::
+
+  sudo lxc-create -n devstack -t ubuntu -f devstack-lxc.conf -- --packages=bsdmainutils,git
+
+The first time it builds the rootfs will take a few minutes to download, unpack,
+and configure all the necessary packages for a minimal installation of Ubuntu.
+LXC will cache this and subsequent containers will only take seconds to create.
+
+.. Note:: To speed up the initial rootfs creation, you can specify a mirror to
+   download the Ubuntu packages from by appending ``--mirror=`` and then the URL
+   of a Ubuntu mirror. To see other other template options, you can run
+   ``lxc-create -t ubuntu -h``.
+
+Start Container
+----------------
+
+To start the container, run::
+
+  sudo lxc-start -n devstack
+
+A moment later you should be presented with the login prompt for your container.
+You can login using the username ``ubuntu`` and password ``ubuntu``.
+
+You can also ssh into your container. On your host, run
+``sudo lxc-info -n devstack`` to get the IP address (e.g. 
+``ssh ubuntu@$(sudo lxc-info -n devstack | awk '/IP/ { print $2 }')``).
+
+Run Devstack
+-------------
+
+You should now be logged into your container and almost ready to run devstack.
+The commands in this section should all be run inside your container.
+
+.. Tip:: You can greatly reduce the runtime of your initial devstack setup by
+   ensuring you have your apt sources.list configured to use a fast mirror.
+   Check and update ``/etc/apt/sources.list`` if necessary and then run 
+   ``apt-get update``.
+
+#. Download DevStack
+
+   ::
+
+       git clone https://opendev.org/openstack/devstack
+
+#. Configure
+
+   Refer to :ref:`minimal-configuration` if you wish to configure the behaviour
+   of devstack.
+
+#. Start the install
+
+   ::
+
+       cd devstack
+       ./stack.sh
+
+Cleanup
+-------
+
+To stop the container::
+
+  lxc-stop -n devstack
+
+To delete the container::
+
+  lxc-destroy -n devstack
+
+Limitations
+============
+
+Not all OpenStack features may function correctly or at all when ran from within
+a container.
+
+Cinder
+-------
+
+Unable to create LVM backed volume
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  In our configuration, we have not whitelisted access to device-mapper or LVM
+  devices. Doing so will permit your container to have access and control of LVM
+  on the host system. To enable, add the following to your
+  ``devstack-lxc.conf`` before running ``lxc-create``::
+
+    lxc.cgroup.devices.allow = c 10:236 rwm
+    lxc.cgroup.devices.allow = b 252:* rwm
+
+  Additionally you'll need to set ``udev_rules = 0`` in the ``activation``
+  section of ``/etc/lvm/lvm.conf`` unless you mount devtmpfs in your container.
+
+Unable to attach volume to instance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  It is not possible to attach cinder volumes to nova instances due to parts of
+  the Linux iSCSI implementation not being network namespace aware. This can be
+  worked around by using network pass-through instead of a separate network
+  namespace but such a setup significantly reduces the isolation of the
+  container (e.g. a ``halt`` command issued in the container will cause the host
+  system to shutdown).

doc/source/guides/multinode-lab.rst

@@ -73,8 +73,15 @@ Otherwise create the stack user:
 
 ::
 
-    groupadd stack
-    useradd -g stack -s /bin/bash -d /opt/stack -m stack
+    useradd -s /bin/bash -d /opt/stack -m stack
+
+Ensure home directory for the ``stack`` user has executable permission for all,
+as RHEL based distros create it with ``700`` and Ubuntu 21.04+ with ``750``
+which can cause issues during deployment.
+
+::
+
+    chmod +x /opt/stack
 
 This user will be making many changes to your system during installation
 and operation so it needs to have sudo privileges to root without a
@@ -82,7 +89,7 @@ password:
 
 ::
 
-    echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+    echo "stack ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/stack
 
 From here on use the ``stack`` user. **Logout** and **login** as the
 ``stack`` user.
@@ -104,7 +111,7 @@ Grab the latest version of DevStack:
 
 ::
 
-    git clone https://git.openstack.org/openstack-dev/devstack
+    git clone https://opendev.org/openstack/devstack
     cd devstack
 
 Up to this point all of the steps apply to each node in the cluster.
@@ -121,17 +128,13 @@ cluster controller's DevStack in ``local.conf``:
 
     [[local|localrc]]
     HOST_IP=192.168.42.11
-    FLAT_INTERFACE=eth0
     FIXED_RANGE=10.4.128.0/20
-    FIXED_NETWORK_SIZE=4096
     FLOATING_RANGE=192.168.42.128/25
-    MULTI_HOST=1
     LOGFILE=/opt/stack/logs/stack.sh.log
     ADMIN_PASSWORD=labstack
-    MYSQL_PASSWORD=supersecret
-    RABBIT_PASSWORD=supersecrete
-    SERVICE_PASSWORD=supersecrete
-    SERVICE_TOKEN=xyzpdqlazydog
+    DATABASE_PASSWORD=supersecret
+    RABBIT_PASSWORD=supersecret
+    SERVICE_PASSWORD=supersecret
 
 In the multi-node configuration the first 10 or so IPs in the private
 subnet are usually reserved. Add this to ``local.sh`` to have it run
@@ -162,25 +165,21 @@ machines, create a ``local.conf`` with:
 
     [[local|localrc]]
     HOST_IP=192.168.42.12 # change this per compute node
-    FLAT_INTERFACE=eth0
     FIXED_RANGE=10.4.128.0/20
-    FIXED_NETWORK_SIZE=4096
     FLOATING_RANGE=192.168.42.128/25
-    MULTI_HOST=1
     LOGFILE=/opt/stack/logs/stack.sh.log
     ADMIN_PASSWORD=labstack
-    MYSQL_PASSWORD=supersecret
-    RABBIT_PASSWORD=supersecrete
-    SERVICE_PASSWORD=supersecrete
-    SERVICE_TOKEN=xyzpdqlazydog
+    DATABASE_PASSWORD=supersecret
+    RABBIT_PASSWORD=supersecret
+    SERVICE_PASSWORD=supersecret
     DATABASE_TYPE=mysql
     SERVICE_HOST=192.168.42.11
-    MYSQL_HOST=192.168.42.11
-    RABBIT_HOST=192.168.42.11
-    GLANCE_HOSTPORT=192.168.42.11:9292
-    ENABLED_SERVICES=n-cpu,n-net,n-api,c-sch,c-api,c-vol
+    MYSQL_HOST=$SERVICE_HOST
+    RABBIT_HOST=$SERVICE_HOST
+    GLANCE_HOSTPORT=$SERVICE_HOST:9292
+    ENABLED_SERVICES=n-cpu,c-vol,placement-client,ovn-controller,ovs-vswitchd,ovsdb-server,q-ovn-metadata-agent
     NOVA_VNC_ENABLED=True
-    NOVNCPROXY_URL="http://192.168.42.11:6080/vnc_auto.html"
+    NOVNCPROXY_URL="http://$SERVICE_HOST:6080/vnc_lite.html"
     VNCSERVER_LISTEN=$HOST_IP
     VNCSERVER_PROXYCLIENT_ADDRESS=$VNCSERVER_LISTEN
 
@@ -195,6 +194,22 @@ A stream of activity ensues. When complete you will see a summary of
 to poke at your shiny new OpenStack. The most recent log file is
 available in ``stack.sh.log``.
 
+Starting in the Ocata release, Nova requires a `Cells v2`_ deployment. Compute
+node services must be mapped to a cell before they can be used.
+
+After each compute node is stacked, verify it shows up in the
+``nova service-list --binary nova-compute`` output. The compute service is
+registered in the cell database asynchronously so this may require polling.
+
+Once the compute node services shows up, run the ``./tools/discover_hosts.sh``
+script from the control node to map compute hosts to the single cell.
+
+The compute service running on the primary control node will be
+discovered automatically when the control node is stacked so this really
+only needs to be performed for subnodes.
+
+.. _Cells v2: https://docs.openstack.org/nova/latest/user/cells.html
+
 Cleaning Up After DevStack
 --------------------------
 
@@ -222,17 +237,17 @@ this when it runs but there are times it needs to still be done by hand:
     sudo rm -rf /etc/libvirt/qemu/inst*
     sudo virsh list | grep inst | awk '{print $1}' | xargs -n1 virsh destroy
 
-Options pimp your stack
-=======================
+Going further
+=============
 
 Additional Users
 ----------------
 
 DevStack creates two OpenStack users (``admin`` and ``demo``) and two
-tenants (also ``admin`` and ``demo``). ``admin`` is exactly what it
+projects (also ``admin`` and ``demo``). ``admin`` is exactly what it
 sounds like, a privileged administrative account that is a member of
-both the ``admin`` and ``demo`` tenants. ``demo`` is a normal user
-account that is only a member of the ``demo`` tenant. Creating
+both the ``admin`` and ``demo`` projects. ``demo`` is a normal user
+account that is only a member of the ``demo`` project. Creating
 additional OpenStack users can be done through the dashboard, sometimes
 it is easier to do them in bulk from a script, especially since they get
 blown away every time ``stack.sh`` runs. The following steps are ripe
@@ -243,36 +258,36 @@ for scripting:
     # Get admin creds
     . openrc admin admin
 
-    # List existing tenants
-    keystone tenant-list
+    # List existing projects
+    openstack project list
 
     # List existing users
-    keystone user-list
+    openstack user list
 
-    # Add a user and tenant
+    # Add a user and project
     NAME=bob
-    PASSWORD=BigSecrete
-    TENANT=$NAME
-    keystone tenant-create --name=$NAME
-    keystone user-create --name=$NAME --pass=$PASSWORD
-    keystone user-role-add --user-id=<bob-user-id> --tenant-id=<bob-tenant-id> --role-id=<member-role-id>
-    # member-role-id comes from the existing member role created by stack.sh
-    # keystone role-list
+    PASSWORD=BigSecret
+    PROJECT=$NAME
+    openstack project create $PROJECT
+    openstack user create $NAME --password=$PASSWORD --project $PROJECT
+    openstack role add Member --user $NAME --project $PROJECT
+    # The Member role is created by stack.sh
+    # openstack role assignment list
 
 Swift
 -----
 
-Swift requires a significant amount of resources and is disabled by
-default in DevStack. The support in DevStack is geared toward a minimal
-installation but can be used for testing. To implement a true multi-node
-test of Swift required more than DevStack provides. Enabling it is as
+Swift, OpenStack Object Storage, requires a significant amount of resources
+and is disabled by default in DevStack. The support in DevStack is geared
+toward a minimal installation but can be used for testing. To implement a
+true multi-node test of swift, additional steps will be required. Enabling it is as
 simple as enabling the ``swift`` service in ``local.conf``:
 
 ::
 
     enable_service s-proxy s-object s-container s-account
 
-Swift will put its data files in ``SWIFT_DATA_DIR`` (default
+Swift, OpenStack Object Storage, will put its data files in ``SWIFT_DATA_DIR`` (default
 ``/opt/stack/data/swift``). The size of the data 'partition' created
 (really a loop-mounted file) is set by ``SWIFT_LOOPBACK_DISK_SIZE``. The
 Swift config files are located in ``SWIFT_CONF_DIR`` (default
@@ -284,17 +299,17 @@ Volumes
 
 DevStack will automatically use an existing LVM volume group named
 ``stack-volumes`` to store cloud-created volumes. If ``stack-volumes``
-doesn't exist, DevStack will set up a 10Gb loop-mounted file to contain
-it. This obviously limits the number and size of volumes that can be
-created inside OpenStack. The size can be overridden by setting
-``VOLUME_BACKING_FILE_SIZE`` in ``local.conf``.
+doesn't exist, DevStack will set up a loop-mounted file to contain
+it.  If the default size is insufficient for the number and size of volumes
+required, it can be overridden by setting ``VOLUME_BACKING_FILE_SIZE`` in
+``local.conf`` (sizes given in ``truncate`` compatible format, e.g. ``24G``).
 
 ``stack-volumes`` can be pre-created on any physical volume supported by
 Linux's LVM. The name of the volume group can be changed by setting
-``VOLUME_GROUP`` in ``localrc``. ``stack.sh`` deletes all logical
-volumes in ``VOLUME_GROUP`` that begin with ``VOLUME_NAME_PREFIX`` as
+``VOLUME_GROUP_NAME`` in ``localrc``. ``stack.sh`` deletes all logical
+volumes in ``VOLUME_GROUP_NAME`` that begin with ``VOLUME_NAME_PREFIX`` as
 part of cleaning up from previous runs. It is recommended to not use the
-root volume group as ``VOLUME_GROUP``.
+root volume group as ``VOLUME_GROUP_NAME``.
 
 The details of creating the volume group depends on the server hardware
 involved but looks something like this:
@@ -334,14 +349,14 @@ After making changes to the repository or branch, if ``RECLONE`` is not
 set in ``localrc`` it may be necessary to remove the corresponding
 directory from ``/opt/stack`` to force git to re-clone the repository.
 
-For example, to pull Nova from a proposed release candidate in the
-primary Nova repository:
+For example, to pull nova, OpenStack Compute, from a proposed release candidate
+in the primary nova repository:
 
 ::
 
     NOVA_BRANCH=rc-proposed
 
-To pull Glance from an experimental fork:
+To pull glance, OpenStack Image service, from an experimental fork:
 
 ::
 
@@ -351,17 +366,6 @@ To pull Glance from an experimental fork:
 Notes stuff you might need to know
 ==================================
 
-Reset the Bridge
-----------------
-
-How to reset the bridge configuration:
-
-::
-
-    sudo brctl delif br100 eth0.926
-    sudo ip link set dev br100 down
-    sudo brctl delbr br100
-
 Set MySQL Password
 ------------------
 
@@ -370,3 +374,47 @@ If you forgot to set the root password you can do this:
 ::
 
     mysqladmin -u root -pnova password 'supersecret'
+
+Live Migration
+--------------
+
+In order for live migration to work with the default live migration URI::
+
+    [libvirt]
+    live_migration_uri = qemu+ssh://stack@%s/system
+
+SSH keys need to be exchanged between each compute node:
+
+1. The SOURCE root user's public RSA key (likely in /root/.ssh/id_rsa.pub)
+   needs to be in the DESTINATION stack user's authorized_keys file
+   (~stack/.ssh/authorized_keys).  This can be accomplished by manually
+   copying the contents from the file on the SOURCE to the DESTINATION.  If
+   you have a password configured for the stack user, then you can use the
+   following command to accomplish the same thing::
+
+        ssh-copy-id -i /root/.ssh/id_rsa.pub stack@DESTINATION
+
+2. The DESTINATION host's public ECDSA key (/etc/ssh/ssh_host_ecdsa_key.pub)
+   needs to be in the SOURCE root user's known_hosts file
+   (/root/.ssh/known_hosts).  This can be accomplished by running the
+   following on the SOURCE machine (hostname must be used)::
+
+        ssh-keyscan -H DEST_HOSTNAME | sudo tee -a /root/.ssh/known_hosts
+
+3. Verify that login via ssh works without a password::
+
+        ssh -i /root/.ssh/id_rsa stack@DESTINATION
+
+In essence, this means that every compute node's root user's public RSA key
+must exist in every other compute node's stack user's authorized_keys file and
+every compute node's public ECDSA key needs to be in every other compute
+node's root user's known_hosts file.  Please note that if the root or stack
+user does not have a SSH key, one can be generated using::
+
+    ssh-keygen -t rsa
+
+The above steps are necessary because libvirtd runs as root when the
+live_migration_uri uses the "qemu:///system" family of URIs.  For more
+information, see the `libvirt documentation`_.
+
+.. _libvirt documentation: https://libvirt.org/drvqemu.html#securitydriver

doc/source/guides/neutron.rst

@@ -1,25 +1,259 @@
 ======================================
-Using DevStack with Neutron Networking
+Using DevStack with neutron Networking
 ======================================
 
-This guide will walk you through using OpenStack Neutron with the ML2
+This guide will walk you through using OpenStack neutron with the ML2
 plugin and the Open vSwitch mechanism driver.
 
-Network Interface Configuration
-===============================
 
-To use Neutron, it is suggested that two network interfaces be present
-in the host operating system.
+.. _single-interface-ovs:
 
-The first interface, eth0 is used for the OpenStack management (API,
-message bus, etc) as well as for ssh for an administrator to access
-the machine.
+Using Neutron with a Single Interface
+=====================================
+
+In some instances, like on a developer laptop, there is only one
+network interface that is available. In this scenario, the physical
+interface is added to the Open vSwitch bridge, and the IP address of
+the laptop is migrated onto the bridge interface. That way, the
+physical interface can be used to transmit self service project
+network traffic, the OpenStack API traffic, and management traffic.
+
+
+.. warning::
+
+    When using a single interface networking setup, there will be a
+    temporary network outage as your IP address is moved from the
+    physical NIC of your machine, to the OVS bridge. If you are SSH'd
+    into the machine from another computer, there is a risk of being
+    disconnected from your ssh session (due to arp cache
+    invalidation), which would stop the stack.sh or leave it in an
+    unfinished state. In these cases, start stack.sh inside its own
+    screen session so it can continue to run.
+
+
+Physical Network Setup
+----------------------
+
+In most cases where DevStack is being deployed with a single
+interface, there is a hardware router that is being used for external
+connectivity and DHCP. The developer machine is connected to this
+network and is on a shared subnet with other machines.  The
+`local.conf` exhibited here assumes that 1500 is a reasonable MTU to
+use on that network.
+
+.. image:: /assets/images/neutron-network-1.png
+   :alt: Network configuration for a single DevStack node
+
+
+DevStack Configuration
+----------------------
+
+The following is a complete `local.conf` for the host named
+`devstack-1`. It will run all the API and services, as well as
+serving as a hypervisor for guest instances.
+
+::
+
+        [[local|localrc]]
+        HOST_IP=172.18.161.6
+        SERVICE_HOST=172.18.161.6
+        MYSQL_HOST=172.18.161.6
+        RABBIT_HOST=172.18.161.6
+        GLANCE_HOSTPORT=172.18.161.6:9292
+        ADMIN_PASSWORD=secret
+        DATABASE_PASSWORD=secret
+        RABBIT_PASSWORD=secret
+        SERVICE_PASSWORD=secret
+
+        ## Neutron options
+        Q_USE_SECGROUP=True
+        FLOATING_RANGE="172.18.161.0/24"
+        IPV4_ADDRS_SAFE_TO_USE="10.0.0.0/22"
+        Q_FLOATING_ALLOCATION_POOL=start=172.18.161.250,end=172.18.161.254
+        PUBLIC_NETWORK_GATEWAY="172.18.161.1"
+        PUBLIC_INTERFACE=eth0
+
+        # Open vSwitch provider networking configuration
+        Q_USE_PROVIDERNET_FOR_PUBLIC=True
+        OVS_PHYSICAL_BRIDGE=br-ex
+        PUBLIC_BRIDGE=br-ex
+        OVS_BRIDGE_MAPPINGS=public:br-ex
+
+
+Adding Additional Compute Nodes
+-------------------------------
+
+Let's suppose that after installing DevStack on the first host, you
+also want to do multinode testing and networking.
+
+Physical Network Setup
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /assets/images/neutron-network-2.png
+   :alt: Network configuration for multiple DevStack nodes
+
+After DevStack installs and configures Neutron, traffic from guest VMs
+flows out of `devstack-2` (the compute node) and is encapsulated in a
+VXLAN tunnel back to `devstack-1` (the control node) where the L3
+agent is running.
+
+::
+
+    stack@devstack-2:~/devstack$ sudo ovs-vsctl show
+    8992d965-0ba0-42fd-90e9-20ecc528bc29
+        Bridge br-int
+            fail_mode: secure
+            Port br-int
+                Interface br-int
+                    type: internal
+            Port patch-tun
+                Interface patch-tun
+                    type: patch
+                    options: {peer=patch-int}
+        Bridge br-tun
+            fail_mode: secure
+            Port "vxlan-c0a801f6"
+                Interface "vxlan-c0a801f6"
+                    type: vxlan
+                    options: {df_default="true", in_key=flow, local_ip="172.18.161.7", out_key=flow, remote_ip="172.18.161.6"}
+            Port patch-int
+                Interface patch-int
+                    type: patch
+                    options: {peer=patch-tun}
+            Port br-tun
+                Interface br-tun
+                    type: internal
+        ovs_version: "2.0.2"
+
+Open vSwitch on the control node, where the L3 agent runs, is
+configured to de-encapsulate traffic from compute nodes, then forward
+it over the `br-ex` bridge, where `eth0` is attached.
+
+::
+
+    stack@devstack-1:~/devstack$ sudo ovs-vsctl show
+    422adeea-48d1-4a1f-98b1-8e7239077964
+        Bridge br-tun
+            fail_mode: secure
+            Port br-tun
+                Interface br-tun
+                    type: internal
+            Port patch-int
+                Interface patch-int
+                    type: patch
+                    options: {peer=patch-tun}
+            Port "vxlan-c0a801d8"
+                Interface "vxlan-c0a801d8"
+                    type: vxlan
+                    options: {df_default="true", in_key=flow, local_ip="172.18.161.6", out_key=flow, remote_ip="172.18.161.7"}
+        Bridge br-ex
+            Port phy-br-ex
+                Interface phy-br-ex
+                    type: patch
+                    options: {peer=int-br-ex}
+            Port "eth0"
+                Interface "eth0"
+            Port br-ex
+                Interface br-ex
+                    type: internal
+        Bridge br-int
+            fail_mode: secure
+            Port "tapce66332d-ea"
+                tag: 1
+                Interface "tapce66332d-ea"
+                    type: internal
+            Port "qg-65e5a4b9-15"
+                tag: 2
+                Interface "qg-65e5a4b9-15"
+                    type: internal
+            Port "qr-33e5e471-88"
+                tag: 1
+                Interface "qr-33e5e471-88"
+                    type: internal
+            Port "qr-acbe9951-70"
+                tag: 1
+                Interface "qr-acbe9951-70"
+                    type: internal
+            Port br-int
+                Interface br-int
+                    type: internal
+            Port patch-tun
+                Interface patch-tun
+                    type: patch
+                    options: {peer=patch-int}
+            Port int-br-ex
+                Interface int-br-ex
+                    type: patch
+                    options: {peer=phy-br-ex}
+        ovs_version: "2.0.2"
+
+`br-int` is a bridge that the Open vSwitch mechanism driver creates,
+which is used as the "integration bridge" where ports are created, and
+plugged into the virtual switching fabric. `br-ex` is an OVS bridge
+that is used to connect physical ports (like `eth0`), so that floating
+IP traffic for project networks can be received from the physical
+network infrastructure (and the internet), and routed to self service
+project network ports.  `br-tun` is a tunnel bridge that is used to
+connect OpenStack nodes (like `devstack-2`) together. This bridge is
+used so that project network traffic, using the VXLAN tunneling
+protocol, flows between each compute node where project instances run.
+
+DevStack Compute Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The host `devstack-2` has a very minimal `local.conf`.
+
+::
+
+    [[local|localrc]]
+    HOST_IP=172.18.161.7
+    SERVICE_HOST=172.18.161.6
+    MYSQL_HOST=172.18.161.6
+    RABBIT_HOST=172.18.161.6
+    GLANCE_HOSTPORT=172.18.161.6:9292
+    ADMIN_PASSWORD=secret
+    MYSQL_PASSWORD=secret
+    RABBIT_PASSWORD=secret
+    SERVICE_PASSWORD=secret
+
+    ## Neutron options
+    PUBLIC_INTERFACE=eth0
+    ENABLED_SERVICES=n-cpu,rabbit,q-agt,placement-client
+
+Network traffic from `eth0` on the compute nodes is then NAT'd by the
+controller node that runs Neutron's `neutron-l3-agent` and provides L3
+connectivity.
+
+
+Neutron Networking with Open vSwitch and Provider Networks
+==========================================================
+
+In some instances, it is desirable to use neutron's provider
+networking extension, so that networks that are configured on an
+external router can be utilized by neutron, and instances created via
+Nova can attach to the network managed by the external router.
+
+For example, in some lab environments, a hardware router has been
+pre-configured by another party, and an OpenStack developer has been
+given a VLAN tag and IP address range, so that instances created via
+DevStack will use the external router for L3 connectivity, as opposed
+to the neutron L3 service.
+
+Physical Network Setup
+----------------------
+
+.. image:: /assets/images/neutron-network-3.png
+   :alt: Network configuration for provider networks
+
+On a compute node, the first interface, eth0 is used for the OpenStack
+management (API, message bus, etc) as well as for ssh for an
+administrator to access the machine.
 
 ::
 
         stack@compute:~$ ifconfig eth0
         eth0      Link encap:Ethernet  HWaddr bc:16:65:20:af:fc
-                  inet addr:192.168.1.18
+                  inet addr:10.0.0.3
 
 eth1 is manually configured at boot to not have an IP address.
 Consult your operating system documentation for the appropriate
@@ -35,9 +269,6 @@ contains:
 
 The second physical interface, eth1 is added to a bridge (in this case
 named br-ex), which is used to forward network traffic from guest VMs.
-Network traffic from eth1 on the compute nodes is then NAT'd by the
-controller node that runs Neutron's `neutron-l3-agent` and provides L3
-connectivity.
 
 ::
 
@@ -57,12 +288,133 @@ connectivity.
                     Interface "eth1"
 
 
+Service Configuration
+---------------------
+
+**Control Node**
+
+In this example, the control node will run the majority of the
+OpenStack API and management services (keystone, glance,
+nova, neutron)
+
+
+**Compute Nodes**
+
+In this example, the nodes that will host guest instances will run
+the ``neutron-openvswitch-agent`` for network connectivity, as well as
+the compute service ``nova-compute``.
+
+DevStack Configuration
+----------------------
+
+.. _ovs-provider-network-controller:
+
+The following is a snippet of the DevStack configuration on the
+controller node.
+
+::
+
+        HOST_IP=10.0.0.2
+        SERVICE_HOST=10.0.0.2
+        MYSQL_HOST=10.0.0.2
+        RABBIT_HOST=10.0.0.2
+        GLANCE_HOSTPORT=10.0.0.2:9292
+        PUBLIC_INTERFACE=eth1
+
+        ADMIN_PASSWORD=secret
+        MYSQL_PASSWORD=secret
+        RABBIT_PASSWORD=secret
+        SERVICE_PASSWORD=secret
+
+        ## Neutron options
+        Q_USE_SECGROUP=True
+        ENABLE_TENANT_VLANS=True
+        TENANT_VLAN_RANGE=3001:4000
+        PHYSICAL_NETWORK=default
+        OVS_PHYSICAL_BRIDGE=br-ex
+
+        Q_USE_PROVIDER_NETWORKING=True
+
+        disable_service q-l3
+
+        ## Neutron Networking options used to create Neutron Subnets
+
+        IPV4_ADDRS_SAFE_TO_USE="203.0.113.0/24"
+        NETWORK_GATEWAY=203.0.113.1
+        PROVIDER_SUBNET_NAME="provider_net"
+        PROVIDER_NETWORK_TYPE="vlan"
+        SEGMENTATION_ID=2010
+        USE_SUBNETPOOL=False
+
+In this configuration we are defining IPV4_ADDRS_SAFE_TO_USE to be a
+publicly routed IPv4 subnet. In this specific instance we are using
+the special TEST-NET-3 subnet defined in `RFC 5737 <https://tools.ietf.org/html/rfc5737>`_,
+which is used for documentation.  In your DevStack setup, IPV4_ADDRS_SAFE_TO_USE
+would be a public IP address range that you or your organization has
+allocated to you, so that you could access your instances from the
+public internet.
+
+The following is the DevStack configuration on
+compute node 1.
+
+::
+
+        HOST_IP=10.0.0.3
+        SERVICE_HOST=10.0.0.2
+        MYSQL_HOST=10.0.0.2
+        RABBIT_HOST=10.0.0.2
+        GLANCE_HOSTPORT=10.0.0.2:9292
+        ADMIN_PASSWORD=secret
+        MYSQL_PASSWORD=secret
+        RABBIT_PASSWORD=secret
+        SERVICE_PASSWORD=secret
+
+        # Services that a compute node runs
+        ENABLED_SERVICES=n-cpu,rabbit,q-agt
+
+        ## Open vSwitch provider networking options
+        PHYSICAL_NETWORK=default
+        OVS_PHYSICAL_BRIDGE=br-ex
+        PUBLIC_INTERFACE=eth1
+        Q_USE_PROVIDER_NETWORKING=True
+
+Compute node 2's configuration will be exactly the same, except
+``HOST_IP`` will be ``10.0.0.4``
+
+When DevStack is configured to use provider networking (via
+``Q_USE_PROVIDER_NETWORKING`` is True) -
+DevStack will automatically add the network interface defined in
+``PUBLIC_INTERFACE`` to the ``OVS_PHYSICAL_BRIDGE``
+
+For example, with the above  configuration, a bridge is
+created, named ``br-ex`` which is managed by Open vSwitch, and the
+second interface on the compute node, ``eth1`` is attached to the
+bridge, to forward traffic sent by guest VMs.
+
+Miscellaneous Tips
+==================
+
+Non-Standard MTU on the Physical Network
+----------------------------------------
+
+Neutron by default uses a MTU of 1500 bytes, which is
+the standard MTU for Ethernet.
+
+A different MTU can be specified by adding the following to
+the Neutron section of `local.conf`. For example,
+if you have network equipment that supports jumbo frames, you could
+set the MTU to 9000 bytes by adding the following
+
+::
+
+    [[post-config|/$Q_PLUGIN_CONF_FILE]]
+    global_physnet_mtu = 9000
 
 
 Disabling Next Generation Firewall Tools
-========================================
+----------------------------------------
 
-Devstack does not properly operate with modern firewall tools.  Specifically
+DevStack does not properly operate with modern firewall tools.  Specifically
 it will appear as if the guest VM can access the external network via ICMP,
 but UDP and TCP packets will not be delivered to the guest VM.  The root cause
 of the issue is that both ufw (Uncomplicated Firewall) and firewalld (Fedora's
@@ -90,140 +442,145 @@ disable ufw if it was enabled, do the following:
         sudo service iptables save
         sudo ufw disable
 
+Configuring Extension Drivers for the ML2 Plugin
+------------------------------------------------
+
+Extension drivers for the ML2 plugin are set with the variable
+``Q_ML2_PLUGIN_EXT_DRIVERS``, and includes the 'port_security' extension
+by default. If you want to remove all the extension drivers (even
+'port_security'), set ``Q_ML2_PLUGIN_EXT_DRIVERS`` to blank.
 
 
+Using Linux Bridge instead of Open vSwitch
+------------------------------------------
 
-Neutron Networking with Open vSwitch
-====================================
+The configuration for using the Linux Bridge ML2 driver is fairly
+straight forward. The Linux Bridge configuration for DevStack is similar
+to the :ref:`Open vSwitch based single interface <single-interface-ovs>`
+setup, with small modifications for the interface mappings.
 
-Configuring Neutron networking in DevStack is very similar to
-configuring `nova-network` - many of the same configuration variables
-(like `FIXED_RANGE` and `FLOATING_RANGE`) used by `nova-network` are
-used by Neutron, which is intentional.
-
-The only difference is the disabling of `nova-network` in your
-local.conf, and the enabling of the Neutron components.
-
-
-Configuration
--------------
 
 ::
 
-        FIXED_RANGE=10.0.0.0/24
-        FLOATING_RANGE=192.168.27.0/24
-        PUBLIC_NETWORK_GATEWAY=192.168.27.2
+    [[local|localrc]]
+    HOST_IP=172.18.161.6
+    SERVICE_HOST=172.18.161.6
+    MYSQL_HOST=172.18.161.6
+    RABBIT_HOST=172.18.161.6
+    GLANCE_HOSTPORT=172.18.161.6:9292
+    ADMIN_PASSWORD=secret
+    DATABASE_PASSWORD=secret
+    RABBIT_PASSWORD=secret
+    SERVICE_PASSWORD=secret
 
-        disable_service n-net
-        enable_service q-svc
-        enable_service q-agt
-        enable_service q-dhcp
-        enable_service q-meta
-        enable_service q-l3
+    ## Neutron options
+    Q_USE_SECGROUP=True
+    FLOATING_RANGE="172.18.161.0/24"
+    IPV4_ADDRS_SAFE_TO_USE="10.0.0.0/24"
+    Q_FLOATING_ALLOCATION_POOL=start=172.18.161.250,end=172.18.161.254
+    PUBLIC_NETWORK_GATEWAY="172.18.161.1"
+    PUBLIC_INTERFACE=eth0
 
-        Q_USE_SECGROUP=True
-        ENABLE_TENANT_VLANS=True
-        TENANT_VLAN_RANGE=1000:1999
-        PHYSICAL_NETWORK=default
-        OVS_PHYSICAL_BRIDGE=br-ex
+    Q_USE_PROVIDERNET_FOR_PUBLIC=True
 
-In this configuration we are defining FLOATING_RANGE to be a
-subnet that exists in the private RFC1918 address space - however in
-in a real setup FLOATING_RANGE would be a public IP address range.
+    # Linuxbridge Settings
+    Q_AGENT=linuxbridge
+    LB_PHYSICAL_INTERFACE=eth0
+    PUBLIC_PHYSICAL_NETWORK=default
+    LB_INTERFACE_MAPPINGS=default:eth0
 
-Neutron Networking with Open vSwitch and Provider Networks
-==========================================================
+Using MacVTap instead of Open vSwitch
+------------------------------------------
 
-In some instances, it is desirable to use Neutron's provider
-networking extension, so that networks that are configured on an
-external router can be utilized by Neutron, and instances created via
-Nova can attach to the network managed by the external router.
+Security groups are not supported by the MacVTap agent. Due to that, devstack
+configures the NoopFirewall driver on the compute node.
 
-For example, in some lab environments, a hardware router has been
-pre-configured by another party, and an OpenStack developer has been
-given a VLAN tag and IP address range, so that instances created via
-DevStack will use the external router for L3 connectivity, as opposed
-to the Neutron L3 service.
+MacVTap agent does not support l3, dhcp and metadata agent. Due to that you can
+chose between the following deployment scenarios:
 
+Single node with provider networks using config drive and external l3, dhcp
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This scenario applies, if l3 and dhcp services are provided externally, or if
+you do not require them.
 
-Service Configuration
----------------------
-
-**Control Node**
-
-In this example, the control node will run the majority of the
-OpenStack API and management services (Keystone, Glance,
-Nova, Neutron, etc..)
-
-
-**Compute Nodes**
-
-In this example, the nodes that will host guest instances will run
-the `neutron-openvswitch-agent` for network connectivity, as well as
-the compute service `nova-compute`.
-
-DevStack Configuration
-----------------------
-
-The following is a snippet of the DevStack configuration on the
-controller node.
 
 ::
 
-        PUBLIC_INTERFACE=eth1
+    [[local|localrc]]
+    HOST_IP=10.0.0.2
+    SERVICE_HOST=10.0.0.2
+    MYSQL_HOST=10.0.0.2
+    RABBIT_HOST=10.0.0.2
+    ADMIN_PASSWORD=secret
+    MYSQL_PASSWORD=secret
+    RABBIT_PASSWORD=secret
+    SERVICE_PASSWORD=secret
 
-        ## Neutron options
-        Q_USE_SECGROUP=True
-        ENABLE_TENANT_VLANS=True
-        TENANT_VLAN_RANGE=3001:4000
-        PHYSICAL_NETWORK=default
-        OVS_PHYSICAL_BRIDGE=br-ex
+    Q_ML2_PLUGIN_MECHANISM_DRIVERS=macvtap
+    Q_USE_PROVIDER_NETWORKING=True
 
-        Q_USE_PROVIDER_NETWORKING=True
-        Q_L3_ENABLED=False
+    enable_plugin neutron https://opendev.org/openstack/neutron
 
-        # Do not use Nova-Network
-        disable_service n-net
+    ## MacVTap agent options
+    Q_AGENT=macvtap
+    PHYSICAL_NETWORK=default
 
-        # Neutron
-        ENABLED_SERVICES+=,q-svc,q-dhcp,q-meta,q-agt
+    IPV4_ADDRS_SAFE_TO_USE="203.0.113.0/24"
+    NETWORK_GATEWAY=203.0.113.1
+    PROVIDER_SUBNET_NAME="provider_net"
+    PROVIDER_NETWORK_TYPE="vlan"
+    SEGMENTATION_ID=2010
+    USE_SUBNETPOOL=False
 
-        ## Neutron Networking options used to create Neutron Subnets
+    [[post-config|/$Q_PLUGIN_CONF_FILE]]
+    [macvtap]
+    physical_interface_mappings = $PHYSICAL_NETWORK:eth1
 
-        FIXED_RANGE="10.1.1.0/24"
-        PROVIDER_SUBNET_NAME="provider_net"
-        PROVIDER_NETWORK_TYPE="vlan"
-        SEGMENTATION_ID=2010
+    [[post-config|$NOVA_CONF]]
+    force_config_drive = True
 
-In this configuration we are defining FIXED_RANGE to be a
-subnet that exists in the private RFC1918 address space - however
-in a real setup FIXED_RANGE would be a public IP address range, so
-that you could access your instances from the public internet.
 
-The following is a snippet of the DevStack configuration on the
-compute node.
+Multi node with MacVTap compute node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This scenario applies, if you require OpenStack provided l3, dhcp or metadata
+services. Those are hosted on a separate controller and network node, running
+some other l2 agent technology (in this example Open vSwitch). This node needs
+to be configured for VLAN tenant networks.
+
+For OVS, a similar configuration like described in the
+:ref:`OVS Provider Network <ovs-provider-network-controller>` section can be
+used. Just add the following line to this local.conf, which also loads
+the MacVTap mechanism driver:
 
 ::
 
-        # Services that a compute node runs
-        ENABLED_SERVICES=n-cpu,rabbit,q-agt
+    [[local|localrc]]
+    ...
+    Q_ML2_PLUGIN_MECHANISM_DRIVERS=openvswitch,linuxbridge,macvtap
+    ...
 
-        ## Neutron options
-        Q_USE_SECGROUP=True
-        ENABLE_TENANT_VLANS=True
-        TENANT_VLAN_RANGE=3001:4000
-        PHYSICAL_NETWORK=default
-        OVS_PHYSICAL_BRIDGE=br-ex
-        PUBLIC_INTERFACE=eth1
-        Q_USE_PROVIDER_NETWORKING=True
-        Q_L3_ENABLED=False
+For the MacVTap compute node, use this local.conf:
 
-When DevStack is configured to use provider networking (via
-`Q_USE_PROVIDER_NETWORKING` is True and `Q_L3_ENABLED` is False) -
-DevStack will automatically add the network interface defined in
-`PUBLIC_INTERFACE` to the `OVS_PHYSICAL_BRIDGE`
+::
 
-For example, with the above  configuration, a bridge is
-created, named `br-ex` which is managed by Open vSwitch, and the
-second interface on the compute node, `eth1` is attached to the
-bridge, to forward traffic sent by guest vms.
+    HOST_IP=10.0.0.3
+    SERVICE_HOST=10.0.0.2
+    MYSQL_HOST=10.0.0.2
+    RABBIT_HOST=10.0.0.2
+    ADMIN_PASSWORD=secret
+    MYSQL_PASSWORD=secret
+    RABBIT_PASSWORD=secret
+    SERVICE_PASSWORD=secret
+
+    # Services that a compute node runs
+    disable_all_services
+    enable_plugin neutron https://opendev.org/openstack/neutron
+    ENABLED_SERVICES+=n-cpu,q-agt
+
+    ## MacVTap agent options
+    Q_AGENT=macvtap
+    PHYSICAL_NETWORK=default
+
+    [[post-config|/$Q_PLUGIN_CONF_FILE]]
+    [macvtap]
+    physical_interface_mappings = $PHYSICAL_NETWORK:eth1

doc/source/guides/nova.rst

@@ -0,0 +1,136 @@
+=================
+Nova and DevStack
+=================
+
+This is a rough guide to various configuration parameters for nova
+running with DevStack.
+
+
+nova-serialproxy
+================
+
+In Juno, nova implemented a `spec
+<https://specs.openstack.org/openstack/nova-specs/specs/juno/implemented/serial-ports.html>`_
+to allow read/write access to the serial console of an instance via
+`nova-serialproxy
+<https://docs.openstack.org/nova/latest/cli/nova-serialproxy.html>`_.
+
+The service can be enabled by adding ``n-sproxy`` to
+``ENABLED_SERVICES``.  Further options can be enabled via
+``local.conf``, e.g.
+
+::
+
+    [[post-config|$NOVA_CONF]]
+    [serial_console]
+    #
+    # Options defined in nova.cmd.serialproxy
+    #
+
+    # Host on which to listen for incoming requests (string value)
+    #serialproxy_host=0.0.0.0
+
+    # Port on which to listen for incoming requests (integer
+    # value)
+    #serialproxy_port=6083
+
+
+    #
+    # Options defined in nova.console.serial
+    #
+
+    # Enable serial console related features (boolean value)
+    #enabled=false
+    # Do not set this manually.  Instead enable the service as
+    # outlined above.
+
+    # Range of TCP ports to use for serial ports on compute hosts
+    # (string value)
+    #port_range=10000:20000
+
+    # Location of serial console proxy. (string value)
+    #base_url=ws://127.0.0.1:6083/
+
+    # IP address on which instance serial console should listen
+    # (string value)
+    #listen=127.0.0.1
+
+    # The address to which proxy clients (like nova-serialproxy)
+    # should connect (string value)
+    #proxyclient_address=127.0.0.1
+
+
+Enabling the service is enough to be functional for a single machine DevStack.
+
+These config options are defined in `nova.conf.serial_console
+<https://opendev.org/openstack/nova/src/master/nova/conf/serial_console.py>`_.
+
+For more information on OpenStack configuration see the `OpenStack
+Compute Service Configuration Reference
+<https://docs.openstack.org/nova/latest/admin/configuration/index.html>`_
+
+
+Fake virt driver
+================
+
+Nova has a `fake virt driver`_ which can be used for scale testing the control
+plane services or testing "move" operations between fake compute nodes, for
+example cold/live migration, evacuate and unshelve.
+
+The fake virt driver does not communicate with any hypervisor, it just reports
+some fake resource inventory values and keeps track of the state of the
+"guests" created, moved and deleted. It is not feature-complete with the
+compute API but is good enough for most API testing, and is also used within
+the nova functional tests themselves so is fairly robust.
+
+.. _fake virt driver: https://opendev.org/openstack/nova/src/branch/master/nova/virt/fake.py
+
+Configuration
+-------------
+
+Set the following in your devstack ``local.conf``:
+
+.. code-block:: ini
+
+  [[local|localrc]]
+  VIRT_DRIVER=fake
+  NUMBER_FAKE_NOVA_COMPUTE=<number>
+
+The ``NUMBER_FAKE_NOVA_COMPUTE`` variable controls the number of fake
+``nova-compute`` services to run and defaults to 1.
+
+When ``VIRT_DRIVER=fake`` is used, devstack will disable quota checking in
+nova and neutron automatically. However, other services, like cinder, will
+still enforce quota limits by default.
+
+Scaling
+-------
+
+The actual value to use for ``NUMBER_FAKE_NOVA_COMPUTE`` depends on factors
+such as:
+
+* The size of the host (physical or virtualized) on which devstack is running.
+* The number of API workers. By default, devstack will run ``max($nproc/2, 2)``
+  workers per API service. If you are running several fake compute services on
+  a single host, then consider setting ``API_WORKERS=1`` in ``local.conf``.
+
+In addition, while quota will be disabled in neutron, there is no fake ML2
+backend for neutron so creating fake VMs will still result in real ports being
+created. To create servers without networking, you can specify ``--nic=none``
+when creating the server, for example:
+
+.. code-block:: shell
+
+  $ openstack --os-compute-api-version 2.37 server create --flavor cirros256 \
+      --image cirros-0.6.3-x86_64-disk --nic none --wait test-server
+
+.. note:: ``--os-compute-api-version`` greater than or equal to 2.37 is
+          required to use ``--nic=none``.
+
+To avoid overhead from other services which you may not need, disable them in
+your ``local.conf``, for example:
+
+.. code-block:: ini
+
+  disable_service horizon
+  disable_service tempest

doc/source/guides/single-machine.rst

@@ -45,31 +45,45 @@ We need to add a user to install DevStack. (if you created a user during
 install you can skip this step and just give the user sudo privileges
 below)
 
-::
+.. code-block:: console
 
-    adduser stack
+    $ sudo useradd -s /bin/bash -d /opt/stack -m stack
+
+Ensure home directory for the ``stack`` user has executable permission for all,
+as RHEL based distros create it with ``700`` and Ubuntu 21.04+ with ``750``
+which can cause issues during deployment.
+
+.. code-block:: console
+
+    $ sudo chmod +x /opt/stack
 
 Since this user will be making many changes to your system, it will need
 to have sudo privileges:
 
-::
+.. code-block:: console
 
-    apt-get install sudo -y || yum install -y sudo
-    echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+    $ apt-get install sudo -y || yum install -y sudo
+    $ echo "stack ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/stack
+
+.. note:: On some systems you may need to use ``sudo visudo``.
 
 From here on you should use the user you created. **Logout** and
-**login** as that user.
+**login** as that user:
+
+.. code-block:: console
+
+    $ sudo su stack && cd ~
 
 Download DevStack
 -----------------
 
 We'll grab the latest version of DevStack via https:
 
-::
+.. code-block:: console
 
-    sudo apt-get install git -y || yum install -y git
-    git clone https://git.openstack.org/openstack-dev/devstack
-    cd devstack
+    $ sudo apt-get install git -y || sudo yum install -y git
+    $ git clone https://opendev.org/openstack/devstack
+    $ cd devstack
 
 Run DevStack
 ------------
@@ -81,11 +95,8 @@ do the following:
 -  Set ``FLOATING_RANGE`` to a range not used on the local network, i.e.
    192.168.1.224/27. This configures IP addresses ending in 225-254 to
    be used as floating IPs.
--  Set ``FIXED_RANGE`` and ``FIXED_NETWORK_SIZE`` to configure the
-   internal address space used by the instances.
--  Set ``FLAT_INTERFACE`` to the Ethernet interface that connects the
-   host to your local network. This is the interface that should be
-   configured with the static IP address mentioned above.
+-  Set ``FIXED_RANGE`` to configure the internal address space used by the
+   instances.
 -  Set the administrative password. This password is used for the
    **admin** and **demo** accounts set up as OpenStack users.
 -  Set the MySQL administrative password. The default here is a random
@@ -95,25 +106,29 @@ do the following:
 -  Set the service password. This is used by the OpenStack services
    (Nova, Glance, etc) to authenticate with Keystone.
 
+.. warning:: Only use alphanumeric characters in your passwords, as some
+   services fail to work when using special characters.
+
 ``local.conf`` should look something like this:
 
-::
+.. code-block:: ini
 
     [[local|localrc]]
     FLOATING_RANGE=192.168.1.224/27
     FIXED_RANGE=10.11.12.0/24
-    FIXED_NETWORK_SIZE=256
-    FLAT_INTERFACE=eth0
     ADMIN_PASSWORD=supersecret
-    MYSQL_PASSWORD=iheartdatabases
+    DATABASE_PASSWORD=iheartdatabases
     RABBIT_PASSWORD=flopsymopsy
     SERVICE_PASSWORD=iheartksl
 
+.. note:: There is a sample :download:`local.conf </assets/local.conf>` file
+    under the *samples* directory in the devstack repository.
+
 Run DevStack:
 
-::
+.. code-block:: console
 
-    ./stack.sh
+    $ ./stack.sh
 
 A seemingly endless stream of activity ensues. When complete you will
 see a summary of ``stack.sh``'s work, including the relevant URLs,
@@ -127,7 +142,3 @@ computers on the local network. In this example that would be
 http://192.168.1.201/ for the dashboard (aka Horizon). Launch VMs and if
 you give them floating IPs and security group access those VMs will be
 accessible from other machines on your network.
-
-Some examples of using the OpenStack command-line clients ``nova`` and
-``glance`` are in the shakedown scripts in ``devstack/exercises``.
-``exercise.sh`` will run all of those scripts and report on the results.

doc/source/guides/single-vm.rst

@@ -3,10 +3,10 @@ All-In-One Single VM
 ====================
 
 Use the cloud to build the cloud! Use your cloud to launch new versions
-of OpenStack in about 5 minutes. When you break it, start over! The VMs
+of OpenStack in about 5 minutes. If you break it, start over! The VMs
 launched in the cloud will be slow as they are running in QEMU
 (emulation), but their primary use is testing OpenStack development and
-operation. Speed not required.
+operation.
 
 Prerequisites Cloud & Image
 ===========================
@@ -15,7 +15,7 @@ Virtual Machine
 ---------------
 
 DevStack should run in any virtual machine running a supported Linux
-release. It will perform best with 4Gb or more of RAM.
+release. It will perform best with 4GB or more of RAM.
 
 OpenStack Deployment & cloud-init
 ---------------------------------
@@ -60,14 +60,13 @@ passed as the user-data file when booting the VM.
             DEBIAN_FRONTEND=noninteractive sudo apt-get install -qqy git || sudo yum install -qy git
             sudo chown stack:stack /home/stack
             cd /home/stack
-            git clone https://git.openstack.org/openstack-dev/devstack
+            git clone https://opendev.org/openstack/devstack
             cd devstack
             echo '[[local|localrc]]' > local.conf
             echo ADMIN_PASSWORD=password >> local.conf
-            echo MYSQL_PASSWORD=password >> local.conf
+            echo DATABASE_PASSWORD=password >> local.conf
             echo RABBIT_PASSWORD=password >> local.conf
             echo SERVICE_PASSWORD=password >> local.conf
-            echo SERVICE_TOKEN=tokentoken >> local.conf
             ./stack.sh
         path: /home/stack/start.sh
         permissions: 0755
@@ -78,6 +77,11 @@ passed as the user-data file when booting the VM.
 As DevStack will refuse to run as root, this configures ``cloud-init``
 to create a non-root user and run the ``start.sh`` script as that user.
 
+If you are using cloud-init and you have not
+:ref:`enabled custom logging <enable_logging>` of the stack
+output, then the stack output can be found in
+``/var/log/cloud-init-output.log`` by default.
+
 Launching By Hand
 -----------------
 
@@ -88,7 +92,7 @@ Using OpenStack
 ---------------
 
 At this point you should be able to access the dashboard. Launch VMs and
-if you give them floating IPs access those VMs from other machines on
+if you give them floating IPs, access those VMs from other machines on
 your network.
 
 One interesting use case is for developers working on a VM on their

doc/source/hacking.rst

@@ -0,0 +1 @@
+.. include:: ../../HACKING.rst

doc/source/index.rst

@@ -1,231 +1,180 @@
-DevStack - an OpenStack Community Production
-============================================
+.. Documentation Architecture for the devstack docs.
+
+   It is really easy for online docs to meander over time as people
+   attempt to add the small bit of additional information they think
+   people need, into an existing information architecture. In order to
+   prevent that we need to be a bit strict as to what's on this front
+   page.
+
+   This should *only* be the quick start narrative. Which should end
+   with 2 sections: what you can do with devstack once it's set up,
+   and how to go beyond this setup. Both should be a set of quick
+   links to other documents to let people explore from there.
+
+DevStack
+========
 
 .. image:: assets/images/logo-blue.png
 
-.. toctree::
-   :glob:
-   :maxdepth: 1
+DevStack is a series of extensible scripts used to quickly bring up a
+complete OpenStack environment based on the latest versions of
+everything from git master.  It is used interactively as a development
+environment and as the basis for much of the OpenStack project's
+functional testing.
 
-   overview
-   configuration
-   plugins
-   faq
-   changes
-   contributing
+The source is available at `<https://opendev.org/openstack/devstack>`__.
+
+.. warning::
+
+   DevStack will make substantial changes to your system during
+   installation. Only run DevStack on servers or virtual machines that
+   are dedicated to this purpose.
 
 Quick Start
------------
++++++++++++
 
-#. Select a Linux Distribution
+Install Linux
+-------------
 
-   Only Ubuntu 14.04 (Trusty), Fedora 20 and CentOS/RHEL 7 are
-   documented here. OpenStack also runs and is packaged on other flavors
-   of Linux such as OpenSUSE and Debian.
+Start with a clean and minimal install of a Linux system. DevStack
+attempts to support the two latest LTS releases of Ubuntu,
+Rocky Linux 9 and openEuler.
 
-#. Install Selected OS
+If you do not have a preference, Ubuntu 22.04 (Jammy) is the
+most tested, and will probably go the smoothest.
 
-   In order to correctly install all the dependencies, we assume a
-   specific minimal version of the supported distributions to make it as
-   easy as possible. We recommend using a minimal install of Ubuntu or
-   Fedora server in a VM if this is your first time.
-
-#. Download DevStack
-
-   ::
-
-       git clone https://git.openstack.org/openstack-dev/devstack
-
-   The ``devstack`` repo contains a script that installs OpenStack and
-   templates for configuration files
-
-#. Configure
-
-   We recommend at least a :doc:`minimal
-   configuration <configuration>` be set up.
-
-#. Start the install
-
-   ::
-
-       cd devstack; ./stack.sh
-
-   It takes a few minutes, we recommend `reading the
-   script <stack.sh.html>`__ while it is building.
-
-Guides
-======
-
-Walk through various setups used by stackers
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   guides/single-vm
-   guides/single-machine
-   guides/multinode-lab
-   guides/neutron
-
-All-In-One Single VM
---------------------
-
-Run :doc:`OpenStack in a VM <guides/single-vm>`. The VMs launched in your cloud will be slow as
-they are running in QEMU (emulation), but it is useful if you don't have
-spare hardware laying around. :doc:`[Read] <guides/single-vm>`
-
-All-In-One Single Machine
+Add Stack User (optional)
 -------------------------
 
-Run :doc:`OpenStack on dedicated hardware <guides/single-machine>`  This can include a
-server-class machine or a laptop at home.
-:doc:`[Read] <guides/single-machine>`
+DevStack should be run as a non-root user with sudo enabled
+(standard logins to cloud images such as "ubuntu" or "cloud-user"
+are usually fine).
 
-Multi-Node Lab
---------------
+If you are not using a cloud image, you can create a separate `stack` user
+to run DevStack with
 
-Setup a :doc:`multi-node cluster <guides/multinode-lab>` with dedicated VLANs for VMs & Management.
-:doc:`[Read] <guides/multinode-lab>`
+.. code-block:: console
 
-DevStack with Neutron Networking
---------------------------------
+   $ sudo useradd -s /bin/bash -d /opt/stack -m stack
 
-Building a DevStack cluster with :doc:`Neutron Networking <guides/neutron>`.
-This guide is meant for building lab environments with a dedicated
-control node and multiple compute nodes.
+Ensure home directory for the ``stack`` user has executable permission for all,
+as RHEL based distros create it with ``700`` and Ubuntu 21.04+ with ``750``
+which can cause issues during deployment.
 
-DevStack Documentation
-======================
+.. code-block:: console
 
-Overview
---------
+    $ sudo chmod +x /opt/stack
 
-:doc:`An overview of DevStack goals and priorities <overview>`
+Since this user will be making many changes to your system, it should
+have sudo privileges:
 
-Configuration
--------------
+.. code-block:: console
 
-:doc:`Configuring and customizing the stack <configuration>`
+    $ echo "stack ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/stack
+    $ sudo -u stack -i
 
-Plugins
+Download DevStack
+-----------------
+
+.. code-block:: console
+
+   $ git clone https://opendev.org/openstack/devstack
+   $ cd devstack
+
+The ``devstack`` repo contains a script that installs OpenStack and
+templates for configuration files.
+
+Create a local.conf
+-------------------
+
+Create a ``local.conf`` file with four passwords preset at the root of the
+devstack git repo.
+
+.. code-block:: ini
+
+   [[local|localrc]]
+   ADMIN_PASSWORD=secret
+   DATABASE_PASSWORD=$ADMIN_PASSWORD
+   RABBIT_PASSWORD=$ADMIN_PASSWORD
+   SERVICE_PASSWORD=$ADMIN_PASSWORD
+
+This is the minimum required config to get started with DevStack.
+
+.. note:: There is a sample :download:`local.conf </assets/local.conf>` file
+   under the *samples* directory in the devstack repository.
+
+.. warning:: Only use alphanumeric characters in your passwords, as some
+   services fail to work when using special characters.
+
+Start the install
+-----------------
+
+.. code-block:: console
+
+   $ ./stack.sh
+
+This will take 15 - 30 minutes, largely depending on the speed of
+your internet connection. Many git trees and packages will be
+installed during this process.
+
+Profit!
 -------
 
-:doc:`Extending DevStack with new features <plugins>`
+You now have a working DevStack! Congrats!
 
-Recent Changes
---------------
+Your devstack will have installed ``keystone``, ``glance``, ``nova``,
+``placement``, ``cinder``, ``neutron``, and ``horizon``. Floating IPs
+will be available, guests have access to the external world.
 
-:doc:`An incomplete summary of recent changes <changes>`
+You can access horizon to experience the web interface to
+OpenStack, and manage vms, networks, volumes, and images from
+there.
 
-FAQ
----
+You can ``source openrc`` in your shell, and then use the
+``openstack`` command line tool to manage your devstack.
 
-:doc:`The DevStack FAQ <faq>`
+You can :ref:`create a VM and SSH into it <ssh>`.
 
-Contributing
-------------
+You can ``cd /opt/stack/tempest`` and run tempest tests that have
+been configured to work with your devstack.
 
-:doc:`Pitching in to make DevStack a better place <contributing>`
+You can :doc:`make code changes to OpenStack and validate them
+<development>`.
 
-Code
-====
-
-*A look at the bits that make it all go*
-
-Scripts
--------
-
-* `stack.sh <stack.sh.html>`__ - The main script
-* `functions <functions.html>`__ - DevStack-specific functions
-* `functions-common <functions-common.html>`__ - Functions shared with other projects
-* `lib/apache <lib/apache.html>`__
-* `lib/ceilometer <lib/ceilometer.html>`__
-* `lib/ceph <lib/ceph.html>`__
-* `lib/cinder <lib/cinder.html>`__
-* `lib/config <lib/config.html>`__
-* `lib/database <lib/database.html>`__
-* `lib/dib <lib/dib.html>`__
-* `lib/dstat <lib/dstat.html>`__
-* `lib/glance <lib/glance.html>`__
-* `lib/heat <lib/heat.html>`__
-* `lib/horizon <lib/horizon.html>`__
-* `lib/infra <lib/infra.html>`__
-* `lib/ironic <lib/ironic.html>`__
-* `lib/keystone <lib/keystone.html>`__
-* `lib/ldap <lib/ldap.html>`__
-* `lib/neutron <lib/neutron.html>`__
-* `lib/nova <lib/nova.html>`__
-* `lib/opendaylight <lib/opendaylight.html>`__
-* `lib/oslo <lib/oslo.html>`__
-* `lib/rpc\_backend <lib/rpc_backend.html>`__
-* `lib/sahara <lib/sahara.html>`__
-* `lib/stackforge <lib/stackforge.html>`__
-* `lib/swift <lib/swift.html>`__
-* `lib/tempest <lib/tempest.html>`__
-* `lib/tls <lib/tls.html>`__
-* `lib/trove <lib/trove.html>`__
-* `lib/zaqar <lib/zaqar.html>`__
-* `unstack.sh <unstack.sh.html>`__
-* `clean.sh <clean.sh.html>`__
-* `run\_tests.sh <run_tests.sh.html>`__
-
-* `extras.d/40-dib.sh <extras.d/40-dib.sh.html>`__
-* `extras.d/50-ironic.sh <extras.d/50-ironic.sh.html>`__
-* `extras.d/60-ceph.sh <extras.d/60-ceph.sh.html>`__
-* `extras.d/70-sahara.sh <extras.d/70-sahara.sh.html>`__
-* `extras.d/70-trove.sh <extras.d/70-trove.sh.html>`__
-* `extras.d/70-tuskar.sh <extras.d/70-tuskar.sh.html>`__
-* `extras.d/70-zaqar.sh <extras.d/70-zaqar.sh.html>`__
-* `extras.d/80-opendaylight.sh <extras.d/80-opendaylight.sh.html>`__
-* `extras.d/80-tempest.sh <extras.d/80-tempest.sh.html>`__
-
-Configuration
+Going further
 -------------
 
+Learn more about our :doc:`configuration system <configuration>` to
+customize devstack for your needs. Including making adjustments to the
+default :doc:`networking <networking>`.
+
+Read :doc:`guides <guides>` for specific setups people have (note:
+guides are point in time contributions, and may not always be kept
+up to date to the latest devstack).
+
+Enable :doc:`devstack plugins <plugins>` to support additional
+services, features, and configuration not present in base devstack.
+
+Use devstack in your CI with :doc:`Ansible roles <zuul_roles>` and
+:doc:`Jobs <zuul_jobs>` for Zuul V3. Migrate your devstack Zuul V2 jobs to Zuul
+V3 with this full migration :doc:`how-to <zuul_ci_jobs_migration>`.
+
+Get :doc:`the big picture <overview>` of what we are trying to do
+with devstack, and help us by :doc:`contributing to the project
+<hacking>`.
+
+If you are a new contributor to devstack please refer: :doc:`contributor/contributing`
+
+.. toctree::
+   :hidden:
+
+   contributor/contributing
+
+Contents
+++++++++
+
 .. toctree::
    :glob:
-   :maxdepth: 1
+   :maxdepth: 2
 
-   local.conf
-   stackrc
-   openrc
-   exerciserc
-   eucarc
-
-Tools
------
-
-* `tools/build\_docs.sh <tools/build_docs.sh.html>`__
-* `tools/create-stack-user.sh <tools/create-stack-user.sh.html>`__
-* `tools/create\_userrc.sh <tools/create_userrc.sh.html>`__
-* `tools/fixup\_stuff.sh <tools/fixup_stuff.sh.html>`__
-* `tools/info.sh <tools/info.sh.html>`__
-* `tools/install\_pip.sh <tools/install_pip.sh.html>`__
-* `tools/install\_prereqs.sh <tools/install_prereqs.sh.html>`__
-* `tools/make\_cert.sh <tools/make_cert.sh.html>`__
-* `tools/upload\_image.sh <tools/upload_image.sh.html>`__
-
-Samples
--------
-
-* `local.sh <samples/local.sh.html>`__
-
-Exercises
----------
-
-* `exercise.sh <exercise.sh.html>`__
-* `exercises/aggregates.sh <exercises/aggregates.sh.html>`__
-* `exercises/boot\_from\_volume.sh <exercises/boot_from_volume.sh.html>`__
-* `exercises/bundle.sh <exercises/bundle.sh.html>`__
-* `exercises/client-args.sh <exercises/client-args.sh.html>`__
-* `exercises/client-env.sh <exercises/client-env.sh.html>`__
-* `exercises/euca.sh <exercises/euca.sh.html>`__
-* `exercises/floating\_ips.sh <exercises/floating_ips.sh.html>`__
-* `exercises/horizon.sh <exercises/horizon.sh.html>`__
-* `exercises/neutron-adv-test.sh <exercises/neutron-adv-test.sh.html>`__
-* `exercises/sahara.sh <exercises/sahara.sh.html>`__
-* `exercises/sec\_groups.sh <exercises/sec_groups.sh.html>`__
-* `exercises/swift.sh <exercises/swift.sh.html>`__
-* `exercises/trove.sh <exercises/trove.sh.html>`__
-* `exercises/volumes.sh <exercises/volumes.sh.html>`__
-* `exercises/zaqar.sh <exercises/zaqar.sh.html>`__
+   *

doc/source/local.conf.rst

@@ -1,9 +0,0 @@
-==========================
-local.conf - User Settings
-==========================
-
-``local.conf`` is a user-maintained settings file that is sourced in
-``stackrc``. It contains a section that replaces the historical
-``localrc`` file. See the description of
-:doc:`local.conf <configuration>` for more details about the mechanics
-of the file.

doc/source/networking.rst

@@ -0,0 +1,238 @@
+=====================
+ DevStack Networking
+=====================
+
+An important part of the DevStack experience is networking that works
+by default for created guests. This might not be optimal for your
+particular testing environment, so this document tries its best to
+explain what's going on.
+
+Defaults
+========
+
+If you don't specify any configuration you will get the following:
+
+* neutron (including l3 with openvswitch)
+* private project networks for each openstack project
+* a floating ip range of 172.24.4.0/24 with the gateway of 172.24.4.1
+* the demo project configured with fixed ips on a subnet allocated from
+  the 10.0.0.0/22 range
+* a ``br-ex`` interface controlled by neutron for all its networking
+  (this is not connected to any physical interfaces).
+* DNS resolution for guests based on the resolv.conf for your host
+* an ip masq rule that allows created guests to route out
+
+This creates an environment which is isolated to the single
+host. Guests can get to the external network for package
+updates. Tempest tests will work in this environment.
+
+.. note::
+
+   By default all OpenStack environments have security group rules
+   which block all inbound packets to guests. If you want to be able
+   to ssh / ping your created guests you should run the following.
+
+   .. code-block:: bash
+
+      openstack security group rule create --proto icmp --dst-port 0 default
+      openstack security group rule create --proto tcp --dst-port 22 default
+
+Locally Accessible Guests
+=========================
+
+If you want to make your guests accessible from other machines on your
+network, we have to connect ``br-ex`` to a physical interface.
+
+Dedicated Guest Interface
+-------------------------
+
+If you have 2 or more interfaces on your devstack server, you can
+allocate an interface to neutron to fully manage. This **should not**
+be the same interface you use to ssh into the devstack server itself.
+
+This is done by setting with the ``PUBLIC_INTERFACE`` attribute.
+
+.. code-block:: bash
+
+   [[local|localrc]]
+   PUBLIC_INTERFACE=eth1
+
+That will put all layer 2 traffic from your guests onto the main
+network. When running in this mode the ip masq rule is **not** added
+in your devstack, you are responsible for making routing work on your
+local network.
+
+Shared Guest Interface
+----------------------
+
+.. warning::
+
+   This is not a recommended configuration. Because of interactions
+   between OVS and bridging, if you reboot your box with active
+   networking you may lose network connectivity to your system.
+
+If you need your guests accessible on the network, but only have 1
+interface (using something like a NUC), you can share your one
+network. But in order for this to work you need to manually set a lot
+of addresses, and have them all exactly correct.
+
+.. code-block:: bash
+
+   [[local|localrc]]
+   PUBLIC_INTERFACE=eth0
+   HOST_IP=10.42.0.52
+   FLOATING_RANGE=10.42.0.0/24
+   PUBLIC_NETWORK_GATEWAY=10.42.0.1
+   Q_FLOATING_ALLOCATION_POOL=start=10.42.0.250,end=10.42.0.254
+
+In order for this scenario to work the floating ip network must match
+the default networking on your server. This breaks HOST_IP detection,
+as we exclude the floating range by default, so you have to specify
+that manually.
+
+The ``PUBLIC_NETWORK_GATEWAY`` is the gateway that server would normally
+use to get off the network. ``Q_FLOATING_ALLOCATION_POOL`` controls
+the range of floating ips that will be handed out. As we are sharing
+your existing network, you'll want to give it a slice that your local
+dhcp server is not allocating. Otherwise you could easily have
+conflicting ip addresses, and cause havoc with your local network.
+
+
+Private Network Addressing
+==========================
+
+The private networks addresses are controlled by the ``IPV4_ADDRS_SAFE_TO_USE``
+and the ``IPV6_ADDRS_SAFE_TO_USE`` variables. This allows users to specify one
+single variable of safe internal IPs to use that will be referenced whether or
+not subnetpools are in use.
+
+For IPv4, ``FIXED_RANGE`` and ``SUBNETPOOL_PREFIX_V4`` will just default to
+the value of ``IPV4_ADDRS_SAFE_TO_USE`` directly.
+
+For IPv6, ``FIXED_RANGE_V6`` will default to the first /64 of the value of
+``IPV6_ADDRS_SAFE_TO_USE``. If ``IPV6_ADDRS_SAFE_TO_USE`` is /64 or smaller,
+``FIXED_RANGE_V6`` will just use the value of that directly.
+``SUBNETPOOL_PREFIX_V6`` will just default to the value of
+``IPV6_ADDRS_SAFE_TO_USE`` directly.
+
+.. _ssh:
+
+SSH access to instances
+=======================
+
+To validate connectivity, you can create an instance using the
+``$PRIVATE_NETWORK_NAME`` network (default: ``private``), create a floating IP
+using the ``$PUBLIC_NETWORK_NAME`` network (default: ``public``), and attach
+this floating IP to the instance:
+
+.. code-block:: shell
+
+    openstack keypair create --public-key ~/.ssh/id_rsa.pub test-keypair
+    openstack server create --network private --key-name test-keypair ... test-server
+    fip_id=$(openstack floating ip create public -f value -c id)
+    openstack server add floating ip test-server ${fip_id}
+
+Once done, ensure you have enabled SSH and ICMP (ping) access for the security
+group used for the instance. You can either create a custom security group and
+specify it when creating the instance or add it after creation, or you can
+modify the ``default`` security group created by default for each project.
+Let's do the latter:
+
+.. code-block:: shell
+
+    openstack security group rule create --proto icmp --dst-port 0 default
+    openstack security group rule create --proto tcp --dst-port 22 default
+
+Finally, SSH into the instance. If you used the Cirros instance uploaded by
+default, then you can run the following:
+
+.. code-block:: shell
+
+    openstack server ssh test-server -- -l cirros
+
+This will connect using the ``cirros`` user and the keypair you configured when
+creating the instance.
+
+Remote SSH access to instances
+==============================
+
+You can also SSH to created instances on your DevStack host from other hosts.
+This can be helpful if you are e.g. deploying DevStack in a VM on an existing
+cloud and wish to do development on your local machine. There are a few ways to
+do this.
+
+.. rubric:: Configure instances to be locally accessible
+
+The most obvious way is to configure guests to be locally accessible, as
+described `above <Locally Accessible Guests>`__. This has the advantage of
+requiring no further effort on the client. However, it is more involved and
+requires either support from your cloud or some inadvisable workarounds.
+
+.. rubric:: Use your DevStack host as a jump host
+
+You can choose to use your DevStack host as a jump host. To SSH to a instance
+this way, pass the standard ``-J`` option to the ``openstack ssh`` / ``ssh``
+command. For example:
+
+.. code-block::
+
+    openstack server ssh test-server -- -l cirros -J username@devstack-host
+
+(where ``test-server`` is name of an existing instance, as described
+:ref:`previously <ssh>`, and ``username`` and ``devstack-host`` are the
+username and hostname of your DevStack host).
+
+This can also be configured via your ``~/.ssh/config`` file, making it rather
+effortless. However, it only allows SSH access. If you want to access e.g. a
+web application on the instance, you will need to configure an SSH tunnel and
+forward select ports using the ``-L`` option. For example, to forward HTTP
+traffic:
+
+.. code-block::
+
+    openstack server ssh test-server -- -l cirros -L 8080:username@devstack-host:80
+
+(where ``test-server`` is name of an existing instance, as described
+:ref:`previously <ssh>`, and ``username`` and ``devstack-host`` are the
+username and hostname of your DevStack host).
+
+As you can imagine, this can quickly get out of hand, particularly for more
+complex guest applications with multiple ports.
+
+.. rubric:: Use a proxy or VPN tool
+
+You can use a proxy or VPN tool to enable tunneling for the floating IP
+address range of the ``$PUBLIC_NETWORK_NAME`` network (default: ``public``)
+defined by ``$FLOATING_RANGE`` (default: ``172.24.4.0/24``). There are many
+such tools available to do this. For example, we could use a useful utility
+called `shuttle`__. To enable tunneling using ``shuttle``, first ensure you
+have allowed SSH and HTTP(S) traffic to your DevStack host. Allowing HTTP(S)
+traffic is necessary so you can use the OpenStack APIs remotely. How you do
+this will depend on where your DevStack host is running. Once this is done,
+install ``sshuttle`` on your localhost:
+
+.. code-block:: bash
+
+    sudo apt-get install sshuttle || yum install sshuttle
+
+Finally, start ``sshuttle`` on your localhost using the floating IP address
+range. For example, assuming you are using the default value for
+``$FLOATING_RANGE``, you can do:
+
+.. code-block:: bash
+
+    sshuttle -r username@devstack-host 172.24.4.0/24
+
+(where ``username`` and ``devstack-host`` are the username and hostname of your
+DevStack host).
+
+You should now be able to create an instance and SSH into it:
+
+.. code-block:: bash
+
+    openstack server ssh test-server -- -l cirros
+
+(where ``test-server`` is name of an existing instance, as described
+:ref:`previously <ssh>`)
+
+.. __: https://github.com/sshuttle/sshuttle

doc/source/openrc.rst

@@ -1,68 +0,0 @@
-=====================================
-openrc - User Authentication Settings
-=====================================
-
-``openrc`` configures login credentials suitable for use with the
-OpenStack command-line tools. ``openrc`` sources ``stackrc`` at the
-beginning (which in turn sources the ``localrc`` section of
-``local.conf``) in order to pick up ``HOST_IP`` and/or ``SERVICE_HOST``
-to use in the endpoints. The values shown below are the default values.
-
-OS\_PROJECT\_NAME (OS\_TENANT\_NAME)
-    Keystone has
-    standardized the term *project* as the entity that owns resources. In
-    some places references still exist to the previous term
-    *tenant* for this use. Also, *project\_name* is preferred to
-    *project\_id*.  OS\_TENANT\_NAME remains supported for compatibility
-    with older tools.
-
-    ::
-
-        OS_PROJECT_NAME=demo
-
-OS\_USERNAME
-    In addition to the owning entity (project), OpenStack calls the entity
-    performing the action *user*.
-
-    ::
-
-        OS_USERNAME=demo
-
-OS\_PASSWORD
-    Keystone's default authentication requires a password be provided.
-    The usual cautions about putting passwords in environment variables
-    apply, for most DevStack uses this may be an acceptable tradeoff.
-
-    ::
-
-        OS_PASSWORD=secrete
-
-HOST\_IP, SERVICE\_HOST
-    Set API endpoint host using ``HOST_IP``. ``SERVICE_HOST`` may also
-    be used to specify the endpoint, which is convenient for some
-    ``local.conf`` configurations. Typically, ``HOST_IP`` is set in the
-    ``localrc`` section.
-
-    ::
-
-        HOST_IP=127.0.0.1
-        SERVICE_HOST=$HOST_IP
-
-OS\_AUTH\_URL
-    Authenticating against an OpenStack cloud using Keystone returns a
-    *Token* and *Service Catalog*. The catalog contains the endpoints
-    for all services the user/tenant has access to - including Nova,
-    Glance, Keystone and Swift.
-
-    ::
-
-        OS_AUTH_URL=http://$SERVICE_HOST:5000/v2.0
-
-KEYSTONECLIENT\_DEBUG, NOVACLIENT\_DEBUG
-    Set command-line client log level to ``DEBUG``. These are commented
-    out by default.
-
-    ::
-
-        # export KEYSTONECLIENT_DEBUG=1
-        # export NOVACLIENT_DEBUG=1

doc/source/overview.rst

@@ -7,7 +7,7 @@ and alternative platforms and support services. That evolution has grown
 well beyond what was originally intended and the majority of
 configuration combinations are rarely, if ever, tested. DevStack is not
 a general OpenStack installer and was never meant to be everything to
-everyone..
+everyone.
 
 Below is a list of what is specifically is supported (read that as
 "tested") going forward.
@@ -20,16 +20,15 @@ Base OS
 
 *The OpenStack Technical Committee (TC) has defined the current CI
 strategy to include the latest Ubuntu release and the latest RHEL
-release (for Python 2.6 testing).*
+release.*
 
 -  Ubuntu: current LTS release plus current development release
--  Fedora: current release plus previous release
--  RHEL: current major release
+-  RHEL/CentOS/RockyLinux: current major release
 -  Other OS platforms may continue to be included but the maintenance of
    those platforms shall not be assumed simply due to their presence.
    Having a listed point-of-contact for each additional OS will greatly
    increase its chance of being well-maintained.
--  Patches for Ubuntu and/or Fedora will not be held up due to
+-  Patches for Ubuntu and/or RockyLinux will not be held up due to
    side-effects on other OS platforms.
 
 Databases
@@ -38,7 +37,6 @@ Databases
 *As packaged by the host OS*
 
 -  MySQL
--  PostgreSQL
 
 Queues
 ------
@@ -46,7 +44,6 @@ Queues
 *As packaged by the host OS*
 
 -  Rabbit
--  Qpid
 
 Web Server
 ----------
@@ -58,19 +55,16 @@ Web Server
 OpenStack Network
 -----------------
 
-*Default to Nova Network, optionally use Neutron*
-
--  Nova Network: FlatDHCP
 -  Neutron: A basic configuration approximating the original FlatDHCP
    mode using linuxbridge or OpenVSwitch.
 
 Services
 --------
 
-The default services configured by DevStack are Identity (Keystone),
-Object Storage (Swift), Image Storage (Glance), Block Storage (Cinder),
-Compute (Nova), Network (Nova), Dashboard (Horizon), Orchestration
-(Heat)
+The default services configured by DevStack are Identity (keystone),
+Object Storage (swift), Image Service (glance), Block Storage
+(cinder), Compute (nova), Placement (placement),
+Networking (neutron), Dashboard (horizon).
 
 Additional services not included directly in DevStack can be tied in to
 ``stack.sh`` using the :doc:`plugin mechanism <plugins>` to call
@@ -80,13 +74,4 @@ Node Configurations
 -------------------
 
 -  single node
--  multi-node is not tested regularly by the core team, and even then
-   only minimal configurations are reviewed
-
-Exercises
----------
-
-The DevStack exercise scripts are no longer used as integration and gate
-testing as that job has transitioned to Tempest. They are still
-maintained as a demonstrations of using OpenStack from the command line
-and for quick operational testing.
+-  multi-node configurations as are tested by the gate

doc/source/plugin-registry.rst

@@ -0,0 +1,180 @@
+.. Note to patch submitters:
+
+   # ============================= #
+   # THIS FILE IS AUTOGENERATED !  #
+   # ============================= #
+
+   ** Plugins are found automatically and added to this list **
+
+   This file is created by a periodic proposal job.  You should not
+   edit this file.
+
+   You should edit the files data/devstack-plugins-registry.footer
+   data/devstack-plugins-registry.header to modify this text.
+
+==========================
+ DevStack Plugin Registry
+==========================
+
+The following list is an automatically-generated collection of
+available DevStack plugins.  This includes, but is not limited to,
+official OpenStack projects.
+
+
+======================================== ===
+Plugin Name                              URL
+======================================== ===
+openstack/aodh                           `https://opendev.org/openstack/aodh <https://opendev.org/openstack/aodh>`__
+openstack/barbican                       `https://opendev.org/openstack/barbican <https://opendev.org/openstack/barbican>`__
+openstack/blazar                         `https://opendev.org/openstack/blazar <https://opendev.org/openstack/blazar>`__
+openstack/ceilometer                     `https://opendev.org/openstack/ceilometer <https://opendev.org/openstack/ceilometer>`__
+openstack/cloudkitty                     `https://opendev.org/openstack/cloudkitty <https://opendev.org/openstack/cloudkitty>`__
+openstack/cyborg                         `https://opendev.org/openstack/cyborg <https://opendev.org/openstack/cyborg>`__
+openstack/designate                      `https://opendev.org/openstack/designate <https://opendev.org/openstack/designate>`__
+openstack/devstack-plugin-amqp1          `https://opendev.org/openstack/devstack-plugin-amqp1 <https://opendev.org/openstack/devstack-plugin-amqp1>`__
+openstack/devstack-plugin-ceph           `https://opendev.org/openstack/devstack-plugin-ceph <https://opendev.org/openstack/devstack-plugin-ceph>`__
+openstack/devstack-plugin-container      `https://opendev.org/openstack/devstack-plugin-container <https://opendev.org/openstack/devstack-plugin-container>`__
+openstack/devstack-plugin-kafka          `https://opendev.org/openstack/devstack-plugin-kafka <https://opendev.org/openstack/devstack-plugin-kafka>`__
+openstack/devstack-plugin-nfs            `https://opendev.org/openstack/devstack-plugin-nfs <https://opendev.org/openstack/devstack-plugin-nfs>`__
+openstack/devstack-plugin-open-cas       `https://opendev.org/openstack/devstack-plugin-open-cas <https://opendev.org/openstack/devstack-plugin-open-cas>`__
+openstack/freezer                        `https://opendev.org/openstack/freezer <https://opendev.org/openstack/freezer>`__
+openstack/freezer-api                    `https://opendev.org/openstack/freezer-api <https://opendev.org/openstack/freezer-api>`__
+openstack/freezer-tempest-plugin         `https://opendev.org/openstack/freezer-tempest-plugin <https://opendev.org/openstack/freezer-tempest-plugin>`__
+openstack/freezer-web-ui                 `https://opendev.org/openstack/freezer-web-ui <https://opendev.org/openstack/freezer-web-ui>`__
+openstack/heat                           `https://opendev.org/openstack/heat <https://opendev.org/openstack/heat>`__
+openstack/heat-dashboard                 `https://opendev.org/openstack/heat-dashboard <https://opendev.org/openstack/heat-dashboard>`__
+openstack/ironic                         `https://opendev.org/openstack/ironic <https://opendev.org/openstack/ironic>`__
+openstack/ironic-inspector               `https://opendev.org/openstack/ironic-inspector <https://opendev.org/openstack/ironic-inspector>`__
+openstack/ironic-prometheus-exporter     `https://opendev.org/openstack/ironic-prometheus-exporter <https://opendev.org/openstack/ironic-prometheus-exporter>`__
+openstack/ironic-ui                      `https://opendev.org/openstack/ironic-ui <https://opendev.org/openstack/ironic-ui>`__
+openstack/keystone                       `https://opendev.org/openstack/keystone <https://opendev.org/openstack/keystone>`__
+openstack/kuryr-libnetwork               `https://opendev.org/openstack/kuryr-libnetwork <https://opendev.org/openstack/kuryr-libnetwork>`__
+openstack/magnum                         `https://opendev.org/openstack/magnum <https://opendev.org/openstack/magnum>`__
+openstack/magnum-ui                      `https://opendev.org/openstack/magnum-ui <https://opendev.org/openstack/magnum-ui>`__
+openstack/manila                         `https://opendev.org/openstack/manila <https://opendev.org/openstack/manila>`__
+openstack/manila-tempest-plugin          `https://opendev.org/openstack/manila-tempest-plugin <https://opendev.org/openstack/manila-tempest-plugin>`__
+openstack/manila-ui                      `https://opendev.org/openstack/manila-ui <https://opendev.org/openstack/manila-ui>`__
+openstack/masakari                       `https://opendev.org/openstack/masakari <https://opendev.org/openstack/masakari>`__
+openstack/mistral                        `https://opendev.org/openstack/mistral <https://opendev.org/openstack/mistral>`__
+openstack/monasca-api                    `https://opendev.org/openstack/monasca-api <https://opendev.org/openstack/monasca-api>`__
+openstack/monasca-events-api             `https://opendev.org/openstack/monasca-events-api <https://opendev.org/openstack/monasca-events-api>`__
+openstack/monasca-tempest-plugin         `https://opendev.org/openstack/monasca-tempest-plugin <https://opendev.org/openstack/monasca-tempest-plugin>`__
+openstack/networking-bagpipe             `https://opendev.org/openstack/networking-bagpipe <https://opendev.org/openstack/networking-bagpipe>`__
+openstack/networking-baremetal           `https://opendev.org/openstack/networking-baremetal <https://opendev.org/openstack/networking-baremetal>`__
+openstack/networking-bgpvpn              `https://opendev.org/openstack/networking-bgpvpn <https://opendev.org/openstack/networking-bgpvpn>`__
+openstack/networking-generic-switch      `https://opendev.org/openstack/networking-generic-switch <https://opendev.org/openstack/networking-generic-switch>`__
+openstack/networking-sfc                 `https://opendev.org/openstack/networking-sfc <https://opendev.org/openstack/networking-sfc>`__
+openstack/neutron                        `https://opendev.org/openstack/neutron <https://opendev.org/openstack/neutron>`__
+openstack/neutron-dynamic-routing        `https://opendev.org/openstack/neutron-dynamic-routing <https://opendev.org/openstack/neutron-dynamic-routing>`__
+openstack/neutron-fwaas                  `https://opendev.org/openstack/neutron-fwaas <https://opendev.org/openstack/neutron-fwaas>`__
+openstack/neutron-fwaas-dashboard        `https://opendev.org/openstack/neutron-fwaas-dashboard <https://opendev.org/openstack/neutron-fwaas-dashboard>`__
+openstack/neutron-tempest-plugin         `https://opendev.org/openstack/neutron-tempest-plugin <https://opendev.org/openstack/neutron-tempest-plugin>`__
+openstack/neutron-vpnaas                 `https://opendev.org/openstack/neutron-vpnaas <https://opendev.org/openstack/neutron-vpnaas>`__
+openstack/neutron-vpnaas-dashboard       `https://opendev.org/openstack/neutron-vpnaas-dashboard <https://opendev.org/openstack/neutron-vpnaas-dashboard>`__
+openstack/nova                           `https://opendev.org/openstack/nova <https://opendev.org/openstack/nova>`__
+openstack/octavia                        `https://opendev.org/openstack/octavia <https://opendev.org/openstack/octavia>`__
+openstack/octavia-dashboard              `https://opendev.org/openstack/octavia-dashboard <https://opendev.org/openstack/octavia-dashboard>`__
+openstack/octavia-tempest-plugin         `https://opendev.org/openstack/octavia-tempest-plugin <https://opendev.org/openstack/octavia-tempest-plugin>`__
+openstack/openstacksdk                   `https://opendev.org/openstack/openstacksdk <https://opendev.org/openstack/openstacksdk>`__
+openstack/osprofiler                     `https://opendev.org/openstack/osprofiler <https://opendev.org/openstack/osprofiler>`__
+openstack/ovn-bgp-agent                  `https://opendev.org/openstack/ovn-bgp-agent <https://opendev.org/openstack/ovn-bgp-agent>`__
+openstack/ovn-octavia-provider           `https://opendev.org/openstack/ovn-octavia-provider <https://opendev.org/openstack/ovn-octavia-provider>`__
+openstack/rally-openstack                `https://opendev.org/openstack/rally-openstack <https://opendev.org/openstack/rally-openstack>`__
+openstack/shade                          `https://opendev.org/openstack/shade <https://opendev.org/openstack/shade>`__
+openstack/skyline-apiserver              `https://opendev.org/openstack/skyline-apiserver <https://opendev.org/openstack/skyline-apiserver>`__
+openstack/storlets                       `https://opendev.org/openstack/storlets <https://opendev.org/openstack/storlets>`__
+openstack/tacker                         `https://opendev.org/openstack/tacker <https://opendev.org/openstack/tacker>`__
+openstack/tap-as-a-service               `https://opendev.org/openstack/tap-as-a-service <https://opendev.org/openstack/tap-as-a-service>`__
+openstack/telemetry-tempest-plugin       `https://opendev.org/openstack/telemetry-tempest-plugin <https://opendev.org/openstack/telemetry-tempest-plugin>`__
+openstack/trove                          `https://opendev.org/openstack/trove <https://opendev.org/openstack/trove>`__
+openstack/trove-dashboard                `https://opendev.org/openstack/trove-dashboard <https://opendev.org/openstack/trove-dashboard>`__
+openstack/venus                          `https://opendev.org/openstack/venus <https://opendev.org/openstack/venus>`__
+openstack/venus-dashboard                `https://opendev.org/openstack/venus-dashboard <https://opendev.org/openstack/venus-dashboard>`__
+openstack/vitrage                        `https://opendev.org/openstack/vitrage <https://opendev.org/openstack/vitrage>`__
+openstack/vitrage-dashboard              `https://opendev.org/openstack/vitrage-dashboard <https://opendev.org/openstack/vitrage-dashboard>`__
+openstack/vitrage-tempest-plugin         `https://opendev.org/openstack/vitrage-tempest-plugin <https://opendev.org/openstack/vitrage-tempest-plugin>`__
+openstack/watcher                        `https://opendev.org/openstack/watcher <https://opendev.org/openstack/watcher>`__
+openstack/watcher-dashboard              `https://opendev.org/openstack/watcher-dashboard <https://opendev.org/openstack/watcher-dashboard>`__
+openstack/whitebox-tempest-plugin        `https://opendev.org/openstack/whitebox-tempest-plugin <https://opendev.org/openstack/whitebox-tempest-plugin>`__
+openstack/zaqar                          `https://opendev.org/openstack/zaqar <https://opendev.org/openstack/zaqar>`__
+openstack/zaqar-ui                       `https://opendev.org/openstack/zaqar-ui <https://opendev.org/openstack/zaqar-ui>`__
+openstack/zun                            `https://opendev.org/openstack/zun <https://opendev.org/openstack/zun>`__
+openstack/zun-ui                         `https://opendev.org/openstack/zun-ui <https://opendev.org/openstack/zun-ui>`__
+performa/os-faults                       `https://opendev.org/performa/os-faults <https://opendev.org/performa/os-faults>`__
+starlingx/config                         `https://opendev.org/starlingx/config <https://opendev.org/starlingx/config>`__
+starlingx/fault                          `https://opendev.org/starlingx/fault <https://opendev.org/starlingx/fault>`__
+starlingx/ha                             `https://opendev.org/starlingx/ha <https://opendev.org/starlingx/ha>`__
+starlingx/integ                          `https://opendev.org/starlingx/integ <https://opendev.org/starlingx/integ>`__
+starlingx/metal                          `https://opendev.org/starlingx/metal <https://opendev.org/starlingx/metal>`__
+starlingx/nfv                            `https://opendev.org/starlingx/nfv <https://opendev.org/starlingx/nfv>`__
+starlingx/update                         `https://opendev.org/starlingx/update <https://opendev.org/starlingx/update>`__
+vexxhost/openstack-operator              `https://opendev.org/vexxhost/openstack-operator <https://opendev.org/vexxhost/openstack-operator>`__
+x/almanach                               `https://opendev.org/x/almanach <https://opendev.org/x/almanach>`__
+x/apmec                                  `https://opendev.org/x/apmec <https://opendev.org/x/apmec>`__
+x/bilean                                 `https://opendev.org/x/bilean <https://opendev.org/x/bilean>`__
+x/broadview-collector                    `https://opendev.org/x/broadview-collector <https://opendev.org/x/broadview-collector>`__
+x/collectd-openstack-plugins             `https://opendev.org/x/collectd-openstack-plugins <https://opendev.org/x/collectd-openstack-plugins>`__
+x/devstack-plugin-additional-pkg-repos   `https://opendev.org/x/devstack-plugin-additional-pkg-repos <https://opendev.org/x/devstack-plugin-additional-pkg-repos>`__
+x/devstack-plugin-glusterfs              `https://opendev.org/x/devstack-plugin-glusterfs <https://opendev.org/x/devstack-plugin-glusterfs>`__
+x/devstack-plugin-hdfs                   `https://opendev.org/x/devstack-plugin-hdfs <https://opendev.org/x/devstack-plugin-hdfs>`__
+x/devstack-plugin-libvirt-qemu           `https://opendev.org/x/devstack-plugin-libvirt-qemu <https://opendev.org/x/devstack-plugin-libvirt-qemu>`__
+x/devstack-plugin-mariadb                `https://opendev.org/x/devstack-plugin-mariadb <https://opendev.org/x/devstack-plugin-mariadb>`__
+x/devstack-plugin-tobiko                 `https://opendev.org/x/devstack-plugin-tobiko <https://opendev.org/x/devstack-plugin-tobiko>`__
+x/devstack-plugin-vmax                   `https://opendev.org/x/devstack-plugin-vmax <https://opendev.org/x/devstack-plugin-vmax>`__
+x/drbd-devstack                          `https://opendev.org/x/drbd-devstack <https://opendev.org/x/drbd-devstack>`__
+x/fenix                                  `https://opendev.org/x/fenix <https://opendev.org/x/fenix>`__
+x/gce-api                                `https://opendev.org/x/gce-api <https://opendev.org/x/gce-api>`__
+x/glare                                  `https://opendev.org/x/glare <https://opendev.org/x/glare>`__
+x/group-based-policy                     `https://opendev.org/x/group-based-policy <https://opendev.org/x/group-based-policy>`__
+x/gyan                                   `https://opendev.org/x/gyan <https://opendev.org/x/gyan>`__
+x/horizon-mellanox                       `https://opendev.org/x/horizon-mellanox <https://opendev.org/x/horizon-mellanox>`__
+x/ironic-staging-drivers                 `https://opendev.org/x/ironic-staging-drivers <https://opendev.org/x/ironic-staging-drivers>`__
+x/kingbird                               `https://opendev.org/x/kingbird <https://opendev.org/x/kingbird>`__
+x/meteos                                 `https://opendev.org/x/meteos <https://opendev.org/x/meteos>`__
+x/meteos-ui                              `https://opendev.org/x/meteos-ui <https://opendev.org/x/meteos-ui>`__
+x/mixmatch                               `https://opendev.org/x/mixmatch <https://opendev.org/x/mixmatch>`__
+x/mogan                                  `https://opendev.org/x/mogan <https://opendev.org/x/mogan>`__
+x/mogan-ui                               `https://opendev.org/x/mogan-ui <https://opendev.org/x/mogan-ui>`__
+x/networking-6wind                       `https://opendev.org/x/networking-6wind <https://opendev.org/x/networking-6wind>`__
+x/networking-ansible                     `https://opendev.org/x/networking-ansible <https://opendev.org/x/networking-ansible>`__
+x/networking-arista                      `https://opendev.org/x/networking-arista <https://opendev.org/x/networking-arista>`__
+x/networking-brocade                     `https://opendev.org/x/networking-brocade <https://opendev.org/x/networking-brocade>`__
+x/networking-cisco                       `https://opendev.org/x/networking-cisco <https://opendev.org/x/networking-cisco>`__
+x/networking-cumulus                     `https://opendev.org/x/networking-cumulus <https://opendev.org/x/networking-cumulus>`__
+x/networking-dpm                         `https://opendev.org/x/networking-dpm <https://opendev.org/x/networking-dpm>`__
+x/networking-fortinet                    `https://opendev.org/x/networking-fortinet <https://opendev.org/x/networking-fortinet>`__
+x/networking-hpe                         `https://opendev.org/x/networking-hpe <https://opendev.org/x/networking-hpe>`__
+x/networking-huawei                      `https://opendev.org/x/networking-huawei <https://opendev.org/x/networking-huawei>`__
+x/networking-infoblox                    `https://opendev.org/x/networking-infoblox <https://opendev.org/x/networking-infoblox>`__
+x/networking-l2gw                        `https://opendev.org/x/networking-l2gw <https://opendev.org/x/networking-l2gw>`__
+x/networking-lagopus                     `https://opendev.org/x/networking-lagopus <https://opendev.org/x/networking-lagopus>`__
+x/networking-mlnx                        `https://opendev.org/x/networking-mlnx <https://opendev.org/x/networking-mlnx>`__
+x/networking-nec                         `https://opendev.org/x/networking-nec <https://opendev.org/x/networking-nec>`__
+x/networking-omnipath                    `https://opendev.org/x/networking-omnipath <https://opendev.org/x/networking-omnipath>`__
+x/networking-opencontrail                `https://opendev.org/x/networking-opencontrail <https://opendev.org/x/networking-opencontrail>`__
+x/networking-ovs-dpdk                    `https://opendev.org/x/networking-ovs-dpdk <https://opendev.org/x/networking-ovs-dpdk>`__
+x/networking-plumgrid                    `https://opendev.org/x/networking-plumgrid <https://opendev.org/x/networking-plumgrid>`__
+x/networking-spp                         `https://opendev.org/x/networking-spp <https://opendev.org/x/networking-spp>`__
+x/networking-vpp                         `https://opendev.org/x/networking-vpp <https://opendev.org/x/networking-vpp>`__
+x/networking-vsphere                     `https://opendev.org/x/networking-vsphere <https://opendev.org/x/networking-vsphere>`__
+x/neutron-classifier                     `https://opendev.org/x/neutron-classifier <https://opendev.org/x/neutron-classifier>`__
+x/nova-dpm                               `https://opendev.org/x/nova-dpm <https://opendev.org/x/nova-dpm>`__
+x/nova-mksproxy                          `https://opendev.org/x/nova-mksproxy <https://opendev.org/x/nova-mksproxy>`__
+x/oaktree                                `https://opendev.org/x/oaktree <https://opendev.org/x/oaktree>`__
+x/omni                                   `https://opendev.org/x/omni <https://opendev.org/x/omni>`__
+x/os-xenapi                              `https://opendev.org/x/os-xenapi <https://opendev.org/x/os-xenapi>`__
+x/picasso                                `https://opendev.org/x/picasso <https://opendev.org/x/picasso>`__
+x/rsd-virt-for-nova                      `https://opendev.org/x/rsd-virt-for-nova <https://opendev.org/x/rsd-virt-for-nova>`__
+x/scalpels                               `https://opendev.org/x/scalpels <https://opendev.org/x/scalpels>`__
+x/slogging                               `https://opendev.org/x/slogging <https://opendev.org/x/slogging>`__
+x/stackube                               `https://opendev.org/x/stackube <https://opendev.org/x/stackube>`__
+x/tap-as-a-service-dashboard             `https://opendev.org/x/tap-as-a-service-dashboard <https://opendev.org/x/tap-as-a-service-dashboard>`__
+x/tatu                                   `https://opendev.org/x/tatu <https://opendev.org/x/tatu>`__
+x/trio2o                                 `https://opendev.org/x/trio2o <https://opendev.org/x/trio2o>`__
+x/valet                                  `https://opendev.org/x/valet <https://opendev.org/x/valet>`__
+x/vmware-nsx                             `https://opendev.org/x/vmware-nsx <https://opendev.org/x/vmware-nsx>`__
+x/vmware-vspc                            `https://opendev.org/x/vmware-vspc <https://opendev.org/x/vmware-vspc>`__
+x/whitebox-neutron-tempest-plugin        `https://opendev.org/x/whitebox-neutron-tempest-plugin <https://opendev.org/x/whitebox-neutron-tempest-plugin>`__
+======================================== ===
+
+

doc/source/plugins.rst

@@ -2,38 +2,175 @@
 Plugins
 =======
 
-DevStack has a couple of plugin mechanisms to allow easily adding
-support for additional projects and features.
+The OpenStack ecosystem is wide and deep, and only growing more so
+every day. The value of DevStack is that it's simple enough to
+understand what it's doing clearly. And yet we'd like to support as
+much of the OpenStack Ecosystem as possible. We do that with plugins.
 
-Extras.d Hooks
-==============
+DevStack plugins are bits of bash code that live outside the DevStack
+tree. They are called through a strong contract, so these plugins can
+be sure that they will continue to work in the future as DevStack
+evolves.
 
-These hooks are an extension of the service calls in
-``stack.sh`` at specific points in its run, plus ``unstack.sh`` and
-``clean.sh``. A number of the higher-layer projects are implemented in
-DevStack using this mechanism.
+Prerequisites
+=============
 
-The script in ``extras.d`` is expected to be mostly a dispatcher to
-functions in a ``lib/*`` script. The scripts are named with a
-zero-padded two digits sequence number prefix to control the order that
-the scripts are called, and with a suffix of ``.sh``. DevSack reserves
-for itself the sequence numbers 00 through 09 and 90 through 99.
+If you are planning to create a plugin that is going to host a service in the
+service catalog (that is, your plugin will use the command
+``get_or_create_service``) please make sure that you apply to the `service
+types authority`_ to reserve a valid service-type. This will help to make sure
+that all deployments of your service use the same service-type.
 
-Below is a template that shows handlers for the possible command-line
-arguments:
+Plugin Interface
+================
 
-::
+DevStack supports a standard mechanism for including plugins from
+external repositories. The plugin interface assumes the following:
 
-    # template.sh - DevStack extras.d dispatch script template
+An external git repository that includes a ``devstack/`` top level
+directory. Inside this directory there can be 3 files.
+
+- ``override-defaults`` - a file containing global variables that
+  will be sourced before the lib/* files. This allows the plugin
+  to override the defaults that are otherwise set in the lib/*
+  files.
+
+  For example, override-defaults may export CINDER_ENABLED_BACKENDS
+  to include the plugin-specific storage backend and thus be able
+  to override the default lvm only storage backend for Cinder.
+
+- ``settings`` - a file containing global variables that will be
+  sourced very early in the process. This is helpful if other plugins
+  might depend on this one, and need access to global variables to do
+  their work.
+
+  Your settings should include any ``enable_service`` lines required
+  by your plugin. This is especially important if you are kicking off
+  services using ``run_process`` as it only works with enabled
+  services.
+
+  Be careful to allow users to override global-variables for
+  customizing their environment.  Usually it is best to provide a
+  default value only if the variable is unset or empty; e.g. in bash
+  syntax ``FOO=${FOO:-default}``.
+
+  The file should include a ``define_plugin`` line to indicate the
+  plugin's name, which is the name that should be used by users on
+  "enable_plugin" lines.  It should generally be the last component of
+  the git repo path (e.g., if the plugin's repo is
+  openstack/foo, then the name here should be "foo") ::
+
+    define_plugin <YOUR PLUGIN>
+
+  If your plugin depends on another plugin, indicate it in this file
+  with one or more lines like the following::
+
+    plugin_requires <YOUR PLUGIN> <OTHER PLUGIN>
+
+  For a complete example, if the plugin "foo" depends on "bar", the
+  ``settings`` file should include::
+
+    define_plugin foo
+    plugin_requires foo bar
+
+  Devstack does not currently use this dependency information, so it's
+  important that users continue to add enable_plugin lines in the
+  correct order in ``local.conf``, however adding this information
+  allows other tools to consider dependency information when
+  automatically generating ``local.conf`` files.
+
+- ``plugin.sh`` - the actual plugin. It is executed by devstack at
+  well defined points during a ``stack.sh`` run. The plugin.sh
+  internal structure is discussed below.
+
+
+Plugins are registered by adding the following to the localrc section
+of ``local.conf``.
+
+They are added in the following format::
+
+  [[local|localrc]]
+  enable_plugin <NAME> <GITURL> [GITREF]
+
+- ``name`` - an arbitrary name. (ex: glusterfs, docker, zaqar, congress)
+- ``giturl`` - a valid git url that can be cloned
+- ``gitref`` - an optional git ref (branch / ref / tag) that will be
+  cloned. Defaults to master.
+
+An example would be as follows::
+
+  enable_plugin ec2-api https://opendev.org/openstack/ec2-api
+
+plugin.sh contract
+==================
+
+``plugin.sh`` is a bash script that will be called at specific points
+during ``stack.sh``, ``unstack.sh``, and ``clean.sh``. It will be
+called in the following way::
+
+  source $PATH/TO/plugin.sh <mode> [phase]
+
+``mode`` can be thought of as the major mode being called, currently
+one of: ``stack``, ``unstack``, ``clean``. ``phase`` is used by modes
+which have multiple points during their run where it's necessary to
+be able to execute code. All existing ``mode`` and ``phase`` points
+are considered **strong contracts** and won't be removed without a
+reasonable deprecation period. Additional new ``mode`` or ``phase``
+points may be added at any time if we discover we need them to support
+additional kinds of plugins in devstack.
+
+The current full list of ``mode`` and ``phase`` are:
+
+-  **stack** - Called by ``stack.sh`` four times for different phases
+   of its run:
+
+   -  **pre-install** - Called after system (OS) setup is complete and
+      before project source is installed.
+   -  **install** - Called after the layer 1 and 2 projects source and
+      their dependencies have been installed.
+   -  **post-config** - Called after the layer 1 and 2 services have
+      been configured. All configuration files for enabled services
+      should exist at this point.
+   -  **extra** - Called near the end after layer 1 and 2 services have
+      been started.
+   -  **test-config** - Called at the end of devstack used to configure tempest
+      or any other test environments
+
+-  **unstack** - Called by ``unstack.sh`` before other services are shut
+   down.
+-  **clean** - Called by ``clean.sh`` before other services are cleaned,
+   but after ``unstack.sh`` has been called.
+
+Example plugin
+====================
+
+An example plugin would look something as follows.
+
+``devstack/settings``::
+
+  # settings file for template
+  enable_service template
+
+
+``devstack/plugin.sh``::
+
+    # plugin.sh - DevStack plugin.sh dispatch script template
+
+    function install_template {
+        ...
+    }
+
+    function init_template {
+        ...
+    }
+
+    function configure_template {
+        ...
+    }
 
     # check for service enabled
     if is_service_enabled template; then
 
-        if [[ "$1" == "source" ]]; then
-            # Initial source of lib script
-            source $TOP_DIR/lib/template
-        fi
-
         if [[ "$1" == "stack" && "$2" == "pre-install" ]]; then
             # Set up system services
             echo_summary "Configuring system services Template"
@@ -52,7 +189,7 @@ arguments:
         elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
             # Initialize and start the template service
             echo_summary "Initializing Template"
-            ##init_template
+            init_template
         fi
 
         if [[ "$1" == "unstack" ]]; then
@@ -69,83 +206,129 @@ arguments:
         fi
     fi
 
-The arguments are:
+Plugin Execution Order
+======================
 
--  **source** - Called by each script that utilizes ``extras.d`` hooks;
-   this replaces directly sourcing the ``lib/*`` script.
--  **stack** - Called by ``stack.sh`` three times for different phases
-   of its run:
+Plugins are run after in tree services at each of the stages
+above. For example, if you need something to happen before Keystone
+starts, you should do that at the ``post-config`` phase.
 
-   -  **pre-install** - Called after system (OS) setup is complete and
-      before project source is installed.
-   -  **install** - Called after the layer 1 and 2 projects source and
-      their dependencies have been installed.
-   -  **post-config** - Called after the layer 1 and 2 services have
-      been configured. All configuration files for enabled services
-      should exist at this point.
-   -  **extra** - Called near the end after layer 1 and 2 services have
-      been started. This is the existing hook and has not otherwise
-      changed.
+Multiple plugins can be specified in your ``local.conf``. When that
+happens the plugins will be executed **in order** at each phase. This
+allows plugins to conceptually depend on each other through
+documenting to the user the order they must be declared. A formal
+dependency mechanism is beyond the scope of the current work.
 
--  **unstack** - Called by ``unstack.sh`` before other services are shut
-   down.
--  **clean** - Called by ``clean.sh`` before other services are cleaned,
-   but after ``unstack.sh`` has been called.
+System Packages
+===============
 
 
-Externally Hosted Plugins
-=========================
 
-Based on the extras.d hooks, DevStack supports a standard mechansim
-for including plugins from external repositories. The plugin interface
-assumes the following:
+Devstack based
+--------------
 
-An external git repository that includes a ``devstack/`` top level
-directory. Inside this directory there can be 2 files.
+Devstack provides a custom framework for getting packages installed at
+an early phase of its execution.  These packages may be defined in a
+plugin as files that contain new-line separated lists of packages
+required by the plugin
 
-- ``settings`` - a file containing global variables that will be
-  sourced very early in the process. This is helpful if other plugins
-  might depend on this one, and need access to global variables to do
-  their work.
-- ``plugin.sh`` - the actual plugin. It will be executed by devstack
-  during it's run. The run order will be done in the registration
-  order for these plugins, and will occur immediately after all in
-  tree extras.d dispatch at the phase in question.  The plugin.sh
-  looks like the extras.d dispatcher above **except** it should not
-  include the is_service_enabled conditional. All external plugins are
-  always assumed to be enabled.
+Supported packaging systems include apt and yum across multiple
+distributions.  To enable a plugin to hook into this and install
+package dependencies, packages may be listed at the following
+locations in the top-level of the plugin repository:
 
-Plugins are registered by adding the following to the localrc section
-of ``local.conf``.
+- ``./devstack/files/debs/$plugin_name`` - Packages to install when running
+  on Ubuntu or Debian.
 
-They are added in the following format::
+- ``./devstack/files/rpms/$plugin_name`` - Packages to install when running
+  on Red Hat, Fedora, or CentOS.
 
-  enable_plugin <NAME> <GITURL> [GITREF]
+Although there a no plans to remove this method of installing
+packages, plugins should consider it deprecated for ``bindep`` support
+described below.
 
-- ``name`` - an arbitrary name. (ex: glustfs, docker, zaqar, congress)
-- ``giturl`` - a valid git url that can be cloned
-- ``gitref`` - an optional git ref (branch / ref / tag) that will be
-  cloned. Defaults to master.
+bindep
+------
 
-An example would be as follows::
+The `bindep <https://docs.openstack.org/infra/bindep>`__ project has
+become the defacto standard for OpenStack projects to specify binary
+dependencies.
 
-  enable_plugin glusterfs https://github.com/sdague/devstack-plugins glusterfs
+A plugin may provide a ``./devstack/files/bindep.txt`` file, which
+will be called with the *default* profile to install packages.  For
+details on the syntax, etc. see the bindep documentation.
 
-Hypervisor
-==========
+It is also possible to use the ``bindep.txt`` of projects that are
+being installed from source with the ``-bindep`` flag available in
+install functions.  For example
 
-Hypervisor plugins are fairly new and condense most hypervisor
-configuration into one place.
+.. code-block:: bash
 
-The initial plugin implemented was for Docker support and is a useful
-template for the required support. Plugins are placed in
-``lib/nova_plugins`` and named ``hypervisor-<name>`` where ``<name>`` is
-the value of ``VIRT_DRIVER``. Plugins must define the following
-functions:
+  if use_library_from_git "diskimage-builder"; then
+     GITREPO["diskimage-builder"]=$DISKIMAGE_BUILDER_REPO_URL
+     GITDIR["diskimage-builder"]=$DEST/diskimage-builder
+     GITBRANCH["diskimage-builder"]=$DISKIMAGE_BUILDER_REPO_REF
+     git_clone_by_name "diskimage-builder"
+     setup_dev_lib -bindep "diskimage-builder"
+  fi
 
--  ``install_nova_hypervisor`` - install any external requirements
--  ``configure_nova_hypervisor`` - make configuration changes, including
-   those to other services
--  ``start_nova_hypervisor`` - start any external services
--  ``stop_nova_hypervisor`` - stop any external services
--  ``cleanup_nova_hypervisor`` - remove transient data and cache
+will result in any packages required by the ``bindep.txt`` of the
+``diskimage-builder`` project being installed.  Note however that jobs
+that switch projects between source and released/pypi installs
+(e.g. with a ``foo-dsvm`` and a ``foo-dsvm-src`` test to cover both
+released dependencies and master versions) will have to deal with
+``bindep.txt`` being unavailable without the source directory.
+
+
+Using Plugins in the OpenStack Gate
+===================================
+
+For everyday use, DevStack plugins can exist in any git tree that's
+accessible on the internet. However, when using DevStack plugins in
+the OpenStack gate, they must live in projects in OpenStack's
+gerrit. This allows testing of the plugin as well as provides network
+isolation against upstream git repository failures (which we see often
+enough to be an issue).
+
+Ideally a plugin will be included within the ``devstack`` directory of
+the project they are being tested. For example, the openstack/ec2-api
+project has its plugin support in its own tree.
+
+However, some times a DevStack plugin might be used solely to
+configure a backend service that will be used by the rest of
+OpenStack, so there is no "project tree" per say. Good examples
+include: integration of back end storage (e.g. ceph or glusterfs),
+integration of SDN controllers (e.g. ovn, OpenDayLight), or
+integration of alternate RPC systems (e.g. zmq, qpid). In these cases
+the best practice is to build a dedicated
+``openstack/devstack-plugin-FOO`` project.
+
+Legacy project-config jobs
+--------------------------
+
+To enable a plugin to be used in a gate job, the following lines will
+be needed in your ``jenkins/jobs/<project>.yaml`` definition in
+`project-config <https://opendev.org/openstack/project-config/>`_::
+
+  # Because we are testing a non standard project, add the
+  # our project repository. This makes zuul do the right
+  # reference magic for testing changes.
+  export PROJECTS="openstack/ec2-api $PROJECTS"
+
+  # note the actual url here is somewhat irrelevant because it
+  # caches in nodepool, however make it a valid url for
+  # documentation purposes.
+  export DEVSTACK_LOCAL_CONFIG="enable_plugin ec2-api https://opendev.org/openstack/ec2-api"
+
+Zuul v3 jobs
+------------
+
+See the ``devstack_plugins`` example in :doc:`zuul_ci_jobs_migration`.
+
+See Also
+========
+
+For additional inspiration on devstack plugins you can check out the
+:doc:`Plugin Registry <plugin-registry>`.
+
+.. _service types authority: https://specs.openstack.org/openstack/service-types-authority/

doc/source/stackrc.rst

@@ -1,66 +0,0 @@
-===========================
-stackrc - DevStack Settings
-===========================
-
-``stackrc`` is the primary configuration file for DevStack. It contains
-all of the settings that control the services started and the
-repositories used to download the source for those services. ``stackrc``
-sources the ``localrc`` section of ``local.conf`` to perform the default
-overrides.
-
-DATABASE\_TYPE
-    Select the database backend to use. The default is ``mysql``,
-    ``postgresql`` is also available.
-ENABLED\_SERVICES
-    Specify which services to launch. These generally correspond to
-    screen tabs. The default includes: Glance (API and Registry),
-    Keystone, Nova (API, Certificate, Object Store, Compute, Network,
-    Scheduler, Certificate Authentication), Cinder
-    (Scheduler, API, Volume), Horizon, MySQL, RabbitMQ, Tempest.
-
-    ::
-
-        ENABLED_SERVICES=g-api,g-reg,key,n-api,n-crt,n-obj,n-cpu,n-net,n-cond,c-sch,c-api,c-vol,n-sch,n-cauth,horizon,rabbit,tempest,$DATABASE_TYPE
-
-    Other services that are not enabled by default can be enabled in
-    ``localrc``. For example, to add Swift, use the following service
-    names:
-
-    ::
-
-        enable_service s-proxy s-object s-container s-account
-
-    A service can similarly be disabled:
-
-    ::
-
-        disable_service horizon
-
-Service Repos
-    The Git repositories used to check out the source for each service
-    are controlled by a pair of variables set for each service.
-    ``*_REPO`` points to the repository and ``*_BRANCH`` selects which
-    branch to check out. These may be overridden in ``local.conf`` to
-    pull source from a different repo for testing, such as a Gerrit
-    branch proposal. ``GIT_BASE`` points to the primary repository
-    server.
-
-    ::
-
-        NOVA_REPO=$GIT_BASE/openstack/nova.git
-        NOVA_BRANCH=master
-
-    To pull a branch directly from Gerrit, get the repo and branch from
-    the Gerrit review page:
-
-    ::
-
-        git fetch https://review.openstack.org/p/openstack/nova refs/changes/50/5050/1 && git checkout FETCH_HEAD
-
-    The repo is the stanza following ``fetch`` and the branch is the
-    stanza following that:
-
-    ::
-
-        NOVA_REPO=https://review.openstack.org/p/openstack/nova
-        NOVA_BRANCH=refs/changes/50/5050/1

doc/source/systemd.rst

@@ -0,0 +1,222 @@
+===========================
+ Using Systemd in DevStack
+===========================
+
+By default DevStack is run with all the services as systemd unit
+files. Systemd is now the default init system for nearly every Linux
+distro, and systemd encodes and solves many of the problems related to
+poorly running processes.
+
+Why this instead of screen?
+===========================
+
+The screen model for DevStack was invented when the number of services
+that a DevStack user was going to run was typically < 10. This made
+screen hot keys to jump around very easy. However, the landscape has
+changed (not all services are stoppable in screen as some are under
+Apache, there are typically at least 20 items)
+
+There is also a common developer workflow of changing code in more
+than one service, and needing to restart a bunch of services for that
+to take effect.
+
+Unit Structure
+==============
+
+.. note::
+
+   Originally we actually wanted to do this as user units, however
+   there are issues with running this under non interactive
+   shells. For now, we'll be running as system units. Some user unit
+   code is left in place in case we can switch back later.
+
+All DevStack user units are created as a part of the DevStack slice
+given the name ``devstack@$servicename.service``. This makes it easy
+to understand which services are part of the devstack run, and lets us
+disable / stop them in a single command.
+
+Manipulating Units
+==================
+
+Assuming the unit ``n-cpu`` to make the examples more clear.
+
+Enable a unit (allows it to be started)::
+
+  sudo systemctl enable devstack@n-cpu.service
+
+Disable a unit::
+
+  sudo systemctl disable devstack@n-cpu.service
+
+Start a unit::
+
+  sudo systemctl start devstack@n-cpu.service
+
+Stop a unit::
+
+  sudo systemctl stop devstack@n-cpu.service
+
+Restart a unit::
+
+  sudo systemctl restart devstack@n-cpu.service
+
+See status of a unit::
+
+  sudo systemctl status devstack@n-cpu.service
+
+Operating on more than one unit at a time
+-----------------------------------------
+
+Systemd supports wildcarding for unit operations. To restart every
+service in devstack you can do that following::
+
+  sudo systemctl restart devstack@*
+
+Or to see the status of all Nova processes you can do::
+
+  sudo systemctl status devstack@n-*
+
+We'll eventually make the unit names a bit more meaningful so that
+it's easier to understand what you are restarting.
+
+.. _journalctl-examples:
+
+Querying Logs
+=============
+
+One of the other major things that comes with systemd is journald, a
+consolidated way to access logs (including querying through structured
+metadata). This is accessed by the user via ``journalctl`` command.
+
+
+Logs can be accessed through ``journalctl``. journalctl has powerful
+query facilities. We'll start with some common options.
+
+Follow logs for a specific service::
+
+  sudo journalctl -f --unit devstack@n-cpu.service
+
+Following logs for multiple services simultaneously::
+
+  sudo journalctl -f --unit devstack@n-cpu.service --unit devstack@n-cond.service
+
+or you can even do wild cards to follow all the nova services::
+
+  sudo journalctl -f --unit devstack@n-*
+
+Use higher precision time stamps::
+
+  sudo journalctl -f -o short-precise --unit devstack@n-cpu.service
+
+By default, journalctl strips out "unprintable" characters, including
+ASCII color codes. To keep the color codes (which can be interpreted by
+an appropriate terminal/pager - e.g. ``less``, the default)::
+
+  sudo journalctl -a --unit devstack@n-cpu.service
+
+When outputting to the terminal using the default pager, long lines
+will be truncated, but horizontal scrolling is supported via the
+left/right arrow keys. You can override this by setting the
+``SYSTEMD_LESS`` environment variable to e.g. ``FRXM``.
+
+You can pipe the output to another tool, such as ``grep``. For
+example, to find a server instance UUID in the nova logs::
+
+  sudo journalctl -a --unit devstack@n-* | grep 58391b5c-036f-44d5-bd68-21d3c26349e6
+
+See ``man 1 journalctl`` for more.
+
+Debugging
+=========
+
+Using pdb
+---------
+
+In order to break into a regular pdb session on a systemd-controlled
+service, you need to invoke the process manually - that is, take it out
+of systemd's control.
+
+Discover the command systemd is using to run the service::
+
+  systemctl show devstack@n-sch.service -p ExecStart --no-pager
+
+Stop the systemd service::
+
+  sudo systemctl stop devstack@n-sch.service
+
+Inject your breakpoint in the source, e.g.::
+
+  import pdb; pdb.set_trace()
+
+Invoke the command manually::
+
+  /usr/local/bin/nova-scheduler --config-file /etc/nova/nova.conf
+
+Some executables, such as :program:`nova-compute`, will need to be executed
+with a particular group. This will be shown in the systemd unit file::
+
+  sudo systemctl cat devstack@n-cpu.service | grep Group
+
+::
+
+  Group = libvirt
+
+Use the :program:`sg` tool to execute the command as this group::
+
+  sg libvirt -c '/usr/local/bin/nova-compute --config-file /etc/nova/nova-cpu.conf'
+
+Using remote-pdb
+----------------
+
+`remote-pdb`_ works while the process is under systemd control.
+
+Make sure you have remote-pdb installed::
+
+  sudo pip install remote-pdb
+
+Inject your breakpoint in the source, e.g.::
+
+  import remote_pdb; remote_pdb.set_trace()
+
+Restart the relevant service::
+
+  sudo systemctl restart devstack@n-api.service
+
+The remote-pdb code configures the telnet port when ``set_trace()`` is
+invoked.  Do whatever it takes to hit the instrumented code path, and
+inspect the logs for a message displaying the listening port::
+
+  Sep 07 16:36:12 p8-100-neo devstack@n-api.service[772]: RemotePdb session open at 127.0.0.1:46771, waiting for connection ...
+
+Telnet to that port to enter the pdb session::
+
+  telnet 127.0.0.1 46771
+
+See the `remote-pdb`_ home page for more options.
+
+.. _`remote-pdb`: https://pypi.org/project/remote-pdb/
+
+Future Work
+===========
+
+user units
+----------
+
+It would be great if we could do services as user units, so that there
+is a clear separation of code being run as not root, to ensure running
+as root never accidentally gets baked in as an assumption to
+services. However, user units interact poorly with devstack-gate and
+the way that commands are run as users with ansible and su.
+
+Maybe someday we can figure that out.
+
+References
+==========
+
+- Arch Linux Wiki - https://wiki.archlinux.org/index.php/Systemd/User
+- Python interface to journald -
+  https://www.freedesktop.org/software/systemd/python-systemd/journal.html
+- Systemd documentation on service files -
+  https://www.freedesktop.org/software/systemd/man/systemd.service.html
+- Systemd documentation on exec (can be used to impact service runs) -
+  https://www.freedesktop.org/software/systemd/man/systemd.exec.html

doc/source/tempest.rst

@@ -0,0 +1,25 @@
+=======
+Tempest
+=======
+
+`Tempest`_ is the OpenStack Integration test suite. It is installed by default
+and is used to provide integration testing for many of the OpenStack services.
+Just like DevStack itself, it is possible to extend Tempest with plugins. In
+fact, many Tempest plugin packages also include DevStack plugin to do things
+like pre-create required static resources.
+
+The `Tempest documentation <Tempest>`_ provides a thorough guide to using
+Tempest. However, if you simply wish to run the standard set of Tempest tests
+against an existing deployment, you can do the following:
+
+.. code-block:: shell
+
+    cd /opt/stack/tempest
+    /opt/stack/data/venv/bin/tempest run ...
+
+The above assumes you have installed DevStack in the default location
+(configured via the ``DEST`` configuration variable) and have enabled
+virtualenv-based installation in the standard location (configured via the
+``USE_VENV`` and ``VENV_DEST`` configuration variables, respectively).
+
+.. _Tempest: https://docs.openstack.org/tempest/latest/

doc/source/zuul_ci_jobs_migration.rst

@@ -0,0 +1,320 @@
+===============================
+Migrating Zuul V2 CI jobs to V3
+===============================
+
+The OpenStack CI system moved from Zuul v2 to Zuul v3, and all CI jobs moved to
+the new CI system. All jobs have been migrated automatically to a format
+compatible with Zuul v3; the jobs produced in this way however are suboptimal
+and do not use the capabilities introduced by Zuul v3, which allow for re-use of
+job parts, in the form of Ansible roles, as well as inheritance between jobs.
+
+DevStack hosts a set of roles, plays and jobs that can be used by other
+repositories to define their DevStack based jobs. To benefit from them, jobs
+must be migrated from the legacy v2 ones into v3 native format.
+
+This document provides guidance and examples to make the migration process as
+painless and smooth as possible.
+
+Where to host the job definitions.
+==================================
+
+In Zuul V3 jobs can be defined in the repository that contains the code they
+excercise. If you are writing CI jobs for an OpenStack service you can define
+your DevStack based CI jobs in one of the repositories that host the code for
+your service. If you have a branchless repo, like a Tempest plugin, that is
+a convenient choice to host the job definitions since job changes do not have
+to be backported. For example, see the beginning of the ``.zuul.yaml`` from the
+sahara Tempest plugin repo:
+
+.. code:: yaml
+
+  # In https://opendev.org/openstack/sahara-tests/src/branch/master/.zuul.yaml:
+  - job:
+      name: sahara-tests-tempest
+      description: |
+        Run Tempest tests from the Sahara plugin.
+      parent: devstack-tempest
+
+Which base job to start from
+============================
+
+If your job needs an OpenStack cloud deployed via DevStack, but you don't plan
+on running Tempest tests, you can start from one of the base
+:doc:`jobs <zuul_jobs>` defined in the DevStack repo.
+
+The ``devstack`` job can be used for both single-node jobs and multi-node jobs,
+and it includes the list of services used in the integrated gate (keystone,
+glance, nova, cinder, neutron and swift). Different topologies can be achieved
+by switching the nodeset used in the child job.
+
+The ``devstack-base`` job is similar to ``devstack`` but it does not specify any
+required repo or service to be run in DevStack. It can be useful to setup
+children jobs that use a very narrow DevStack setup.
+
+If your job needs an OpenStack cloud deployed via DevStack, and you do plan
+on running Tempest tests, you can start from one of the base jobs defined in the
+Tempest repo.
+
+The ``devstack-tempest`` job can be used for both single-node jobs and
+multi-node jobs. Different topologies can be achieved by switching the nodeset
+used in the child job.
+
+Jobs can be customized as follows without writing any Ansible code:
+
+- add and/or remove DevStack services
+- add or modify DevStack and services configuration
+- install DevStack plugins
+- extend the number of sub-nodes (multinode only)
+- define extra log files and/or directories to be uploaded on logs.o.o
+- define extra log file extensions to be rewritten to .txt for ease of access
+
+Tempest jobs can be further customized as follows:
+
+- define the Tempest tox environment to be used
+- define the test concurrency
+- define the test regular expression
+
+Writing Ansible code, or importing existing custom roles, jobs can be further
+extended by:
+
+- adding pre and/or post playbooks
+- overriding the run playbook, add custom roles
+
+The (partial) example below extends a Tempest single node base job
+"devstack-tempest" in the Kuryr repository. The parent job name is defined in
+job.parent.
+
+.. code:: yaml
+
+  # https://opendev.org/openstack/kuryr-kubernetes/src/branch/master/.zuul.d/base.yaml:
+  - job:
+      name: kuryr-kubernetes-tempest-base
+      parent: devstack-tempest
+      description: Base kuryr-kubernetes-job
+      required-projects:
+        - openstack/devstack-plugin-container
+        - openstack/kuryr
+        - openstack/kuryr-kubernetes
+        - openstack/kuryr-tempest-plugin
+        - openstack/neutron-lbaas
+      vars:
+        tempest_test_regex: '^(kuryr_tempest_plugin.tests.)'
+        tox_envlist: 'all'
+        devstack_localrc:
+          KURYR_K8S_API_PORT: 8080
+        devstack_services:
+          kubernetes-api: true
+          kubernetes-controller-manager: true
+          kubernetes-scheduler: true
+          kubelet: true
+          kuryr-kubernetes: true
+          (...)
+        devstack_plugins:
+          kuryr-kubernetes: https://opendev.org/openstack/kuryr
+          devstack-plugin-container: https://opendev.org/openstack/devstack-plugin-container
+          neutron-lbaas: https://opendev.org/openstack/neutron-lbaas
+        tempest_plugins:
+          - kuryr-tempest-plugin
+        (...)
+
+Job variables
+=============
+
+Variables can be added to the job in three different places:
+
+- job.vars: these are global variables available to all node in the nodeset
+- job.host-vars.[HOST]: these are variables available only to the specified HOST
+- job.group-vars.[GROUP]: these are variables available only to the specified
+  GROUP
+
+Zuul merges dict variables through job inheritance. Host and group variables
+override variables with the same name defined as global variables.
+
+In the example below, for the sundaes job, hosts that are not part of the
+subnode group will run vanilla and chocolate. Hosts in the subnode group will
+run stracciatella and strawberry.
+
+.. code:: yaml
+
+  - job:
+      name: ice-creams
+      vars:
+        devstack_service:
+          vanilla: true
+          chocolate: false
+      group-vars:
+        subnode:
+          devstack_service:
+            pistacchio: true
+            stracciatella: true
+
+  - job:
+      name: sundaes
+      parent: ice-creams
+      vars:
+        devstack_service:
+          chocolate: true
+      group-vars:
+        subnode:
+          devstack_service:
+            strawberry: true
+            pistacchio: false
+
+
+DevStack Gate Flags
+===================
+
+The old CI system worked using a combination of DevStack, Tempest and
+devstack-gate to setup a test environment and run tests against it. With Zuul
+V3, the logic that used to live in devstack-gate is moved into different repos,
+including DevStack, Tempest and grenade.
+
+DevStack-gate exposes an interface for job definition based on a number of
+DEVSTACK_GATE_* environment variables, or flags. This guide shows how to map
+DEVSTACK_GATE flags into the new
+system.
+
+The repo column indicates in which repository is hosted the code that replaces
+the devstack-gate flag. The new implementation column explains how to reproduce
+the same or a similar behaviour in Zuul v3 jobs. For localrc settings,
+devstack-gate defined a default value. In ansible jobs the default is either the
+value defined in the parent job, or the default from DevStack, if any.
+
+.. list-table:: **DevStack Gate Flags**
+   :widths: 20 10 60
+   :header-rows: 1
+
+   * - DevStack gate flag
+     - Repo
+     - New implementation
+   * - OVERRIDE_ZUUL_BRANCH
+     - zuul
+     - override-checkout: [branch] in the job definition.
+   * - DEVSTACK_GATE_NET_OVERLAY
+     - zuul-jobs
+     - A bridge called br-infra is set up for all jobs that inherit
+       from multinode with a dedicated `bridge role
+       <https://zuul-ci.org/docs/zuul-jobs/general-roles.html#role-multi-node-bridge>`_.
+   * - DEVSTACK_CINDER_VOLUME_CLEAR
+     - devstack
+     - *CINDER_VOLUME_CLEAR: true/false* in devstack_localrc in the
+       job vars.
+   * - DEVSTACK_GATE_NEUTRON
+     - devstack
+     - True by default. To disable, disable all neutron services in
+       devstack_services in the job definition.
+   * - DEVSTACK_GATE_CONFIGDRIVE
+     - devstack
+     - *FORCE_CONFIG_DRIVE: true/false* in devstack_localrc in the job
+       vars.
+   * - DEVSTACK_GATE_INSTALL_TESTONLY
+     - devstack
+     - *INSTALL_TESTONLY_PACKAGES: true/false* in devstack_localrc in
+       the job vars.
+   * - DEVSTACK_GATE_VIRT_DRIVER
+     - devstack
+     - *VIRT_DRIVER: [virt driver]* in devstack_localrc in the job
+       vars.
+   * - DEVSTACK_GATE_LIBVIRT_TYPE
+     - devstack
+     - *LIBVIRT_TYPE: [libvirt type]* in devstack_localrc in the job
+       vars.
+   * - DEVSTACK_GATE_TEMPEST
+     - devstack and tempest
+     - Defined by the job that is used. The ``devstack`` job only runs
+       devstack. The ``devstack-tempest`` one triggers a Tempest run
+       as well.
+   * - DEVSTACK_GATE_TEMPEST_FULL
+     - tempest
+     - *tox_envlist: full* in the job vars.
+   * - DEVSTACK_GATE_TEMPEST_ALL
+     - tempest
+     - *tox_envlist: all* in the job vars.
+   * - DEVSTACK_GATE_TEMPEST_ALL_PLUGINS
+     - tempest
+     - *tox_envlist: all-plugin* in the job vars.
+   * - DEVSTACK_GATE_TEMPEST_SCENARIOS
+     - tempest
+     - *tox_envlist: scenario* in the job vars.
+   * - TEMPEST_CONCURRENCY
+     - tempest
+     - *tempest_concurrency: [value]* in the job vars. This is
+       available only on jobs that inherit from ``devstack-tempest``
+       down.
+   * - DEVSTACK_GATE_TEMPEST_NOTESTS
+     - tempest
+     - *tox_envlist: venv-tempest* in the job vars. This will create
+       Tempest virtual environment but run no tests.
+   * - DEVSTACK_GATE_SMOKE_SERIAL
+     - tempest
+     - *tox_envlist: smoke-serial* in the job vars.
+   * - DEVSTACK_GATE_TEMPEST_DISABLE_TENANT_ISOLATION
+     - tempest
+     - *tox_envlist: full-serial* in the job vars.
+       *TEMPEST_ALLOW_TENANT_ISOLATION: false* in devstack_localrc in
+       the job vars.
+
+
+The following flags have not been migrated yet or are legacy and won't be
+migrated at all.
+
+.. list-table:: **Not Migrated DevStack Gate Flags**
+   :widths: 20 10 60
+   :header-rows: 1
+
+   * - DevStack gate flag
+     - Status
+     - Details
+   * - DEVSTACK_GATE_TOPOLOGY
+     - WIP
+     - The topology depends on the base job that is used and more
+       specifically on the nodeset attached to it. The new job format
+       allows project to define the variables to be passed to every
+       node/node-group that exists in the topology. Named topologies
+       that include the nodeset and the matching variables can be
+       defined in the form of base jobs.
+   * - DEVSTACK_GATE_GRENADE
+     - TBD
+     - Grenade Zuul V3 jobs will be hosted in the grenade repo.
+   * - GRENADE_BASE_BRANCH
+     - TBD
+     - Grenade Zuul V3 jobs will be hosted in the grenade repo.
+   * - DEVSTACK_GATE_NEUTRON_DVR
+     - TBD
+     - Depends on multinode support.
+   * - DEVSTACK_GATE_EXERCISES
+     - TBD
+     - Can be done on request.
+   * - DEVSTACK_GATE_IRONIC
+     - TBD
+     - This will probably be implemented on ironic side.
+   * - DEVSTACK_GATE_IRONIC_DRIVER
+     - TBD
+     - This will probably be implemented on ironic side.
+   * - DEVSTACK_GATE_IRONIC_BUILD_RAMDISK
+     - TBD
+     - This will probably be implemented on ironic side.
+   * - DEVSTACK_GATE_POSTGRES
+     - Legacy
+     - This flag exists in d-g but the only thing that it does is
+       capture postgres logs. This is already supported by the roles
+       in post, so the flag is useless in the new jobs. postgres
+       itself can be enabled via the devstack_service job variable.
+   * - DEVSTACK_GATE_ZEROMQ
+     - Legacy
+     - This has no effect in d-g.
+   * - DEVSTACK_GATE_MQ_DRIVER
+     - Legacy
+     - This has no effect in d-g.
+   * - DEVSTACK_GATE_TEMPEST_STRESS_ARGS
+     - Legacy
+     - Stress is not in Tempest anymore.
+   * - DEVSTACK_GATE_TEMPEST_HEAT_SLOW
+     - Legacy
+     - This is not used anywhere.
+   * - DEVSTACK_GATE_CELLS
+     - Legacy
+     - This has no effect in d-g.
+   * - DEVSTACK_GATE_NOVA_API_METADATA_SPLIT
+     - Legacy
+     - This has no effect in d-g.

doc/source/zuul_jobs.rst

@@ -0,0 +1,4 @@
+Zuul CI Jobs
+============
+
+.. zuul:autojobs::

doc/source/zuul_roles.rst

@@ -0,0 +1,4 @@
+Zuul CI Roles
+=============
+
+.. zuul:autoroles::

driver_certs/cinder_driver_cert.sh

@@ -1,106 +0,0 @@
-#!/usr/bin/env bash
-
-# **cinder_cert.sh**
-
-# This script is a simple wrapper around the tempest volume api tests
-# It requires that you have a working and functional devstack install
-# and that you've enabled your device driver by making the necessary
-# modifications to /etc/cinder/cinder.conf
-
-# This script will refresh your openstack repo's and restart the cinder
-# services to pick up your driver changes.
-# please NOTE; this script assumes your devstack install is functional
-# and includes tempest. A good first step is to make sure you can
-# create volumes on your device before you even try and run this script.
-
-# It also assumes default install location (/opt/stack/xxx)
-# to aid in debug, you should also verify that you've added
-# an output directory for screen logs:
-#
-#     SCREEN_LOGDIR=/opt/stack/screen-logs
-
-set -o pipefail
-
-CERT_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $CERT_DIR/..; pwd)
-
-source $TOP_DIR/functions
-source $TOP_DIR/stackrc
-source $TOP_DIR/openrc
-source $TOP_DIR/lib/infra
-source $TOP_DIR/lib/tempest
-source $TOP_DIR/lib/cinder
-
-TEMPFILE=`mktemp`
-RECLONE=True
-
-function log_message {
-    MESSAGE=$1
-    STEP_HEADER=$2
-    if [[ "$STEP_HEADER" = "True" ]]; then
-        echo -e "\n========================================================" | tee -a $TEMPFILE
-    fi
-    echo -e `date +%m/%d/%y/%T:`"${MESSAGE}" | tee -a $TEMPFILE
-    if [[ "$STEP_HEADER" = "True" ]]; then
-        echo -e "========================================================" | tee -a $TEMPFILE
-    fi
-}
-
-if [[ "$OFFLINE" = "True" ]]; then
-    echo "ERROR: Driver cert requires fresh clone/pull from ${CINDER_BRANCH}"
-    echo "       Please set OFFLINE=False and retry."
-    exit 1
-fi
-
-log_message "RUNNING CINDER DRIVER CERTIFICATION CHECK", True
-log_message "Output is being logged to: $TEMPFILE"
-
-cd $CINDER_DIR
-log_message "Cloning to ${CINDER_REPO}...", True
-install_cinder
-
-log_message "Pull a fresh Clone of cinder repo...", True
-git status | tee -a $TEMPFILE
-git log --pretty=oneline -n 1 | tee -a $TEMPFILE
-
-log_message "Gathering copy of cinder.conf file (passwords will be scrubbed)...", True
-cat /etc/cinder/cinder.conf | egrep -v "(^#.*|^$)" | tee -a $TEMPFILE
-sed -i "s/\(.*password.*=\).*$/\1 xxx/i" $TEMPFILE
-log_message "End of cinder.conf.", True
-
-cd $TOP_DIR
-# Verify tempest is installed/enabled
-if ! is_service_enabled tempest; then
-    log_message "ERROR!!! Cert requires tempest in enabled_services!", True
-    log_message"       Please add tempest to enabled_services and retry."
-    exit 1
-fi
-
-cd $TEMPEST_DIR
-install_tempest
-
-log_message "Verify tempest is current....", True
-git status | tee -a $TEMPFILE
-log_message "Check status and get latest commit..."
-git log --pretty=oneline -n 1 | tee -a $TEMPFILE
-
-
-#stop and restart cinder services
-log_message "Restart Cinder services...", True
-stop_cinder
-sleep 1
-start_cinder
-sleep 5
-
-# run tempest api/volume/test_*
-log_message "Run the actual tempest volume tests (./tools/pretty_tox.sh volume)...", True
-./tools/pretty_tox.sh volume 2>&1 | tee -a $TEMPFILE
-if [[ $? = 0 ]]; then
-    log_message "CONGRATULATIONS!!!  Device driver PASSED!", True
-    log_message "Submit output: ($TEMPFILE)"
-    exit 0
-else
-    log_message "SORRY!!!  Device driver FAILED!", True
-    log_message "Check output in $TEMPFILE"
-    exit 1
-fi

eucarc

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-#
-# source eucarc [username] [tenantname]
-#
-# Create EC2 credentials for the current user as defined by OS_TENANT_NAME:OS_USERNAME
-# Optionally set the tenant/username via openrc
-
-if [[ -n "$1" ]]; then
-    USERNAME=$1
-fi
-if [[ -n "$2" ]]; then
-    TENANT=$2
-fi
-
-# Find the other rc files
-RC_DIR=$(cd $(dirname "${BASH_SOURCE:-$0}") && pwd)
-
-# Get user configuration
-source $RC_DIR/openrc
-
-# Set the ec2 url so euca2ools works
-export EC2_URL=$(keystone catalog --service ec2 | awk '/ publicURL / { print $4 }')
-
-# Create EC2 credentials for the current user
-CREDS=$(openstack ec2 credentials create)
-export EC2_ACCESS_KEY=$(echo "$CREDS" | awk '/ access / { print $4 }')
-export EC2_SECRET_KEY=$(echo "$CREDS" | awk '/ secret / { print $4 }')
-
-# Euca2ools Certificate stuff for uploading bundles
-# See exercises/bundle.sh to see how to get certs using nova cli
-NOVA_KEY_DIR=${NOVA_KEY_DIR:-$RC_DIR}
-export S3_URL=$(keystone catalog --service s3 | awk '/ publicURL / { print $4 }')
-export EC2_USER_ID=42 # nova does not use user id, but bundling requires it
-export EC2_PRIVATE_KEY=${NOVA_KEY_DIR}/pk.pem
-export EC2_CERT=${NOVA_KEY_DIR}/cert.pem
-export NOVA_CERT=${NOVA_KEY_DIR}/cacert.pem
-export EUCALYPTUS_CERT=${NOVA_CERT} # euca-bundle-image seems to require this set
-alias ec2-bundle-image="ec2-bundle-image --cert ${EC2_CERT} --privatekey ${EC2_PRIVATE_KEY} --user ${EC2_USER_ID} --ec2cert ${NOVA_CERT}"
-alias ec2-upload-bundle="ec2-upload-bundle -a ${EC2_ACCESS_KEY} -s ${EC2_SECRET_KEY} --url ${S3_URL} --ec2cert ${NOVA_CERT}"
-

exercise.sh

@@ -1,74 +0,0 @@
-#!/usr/bin/env bash
-
-# **exercise.sh**
-
-# Keep track of the current devstack directory.
-TOP_DIR=$(cd $(dirname "$0") && pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Load local configuration
-source $TOP_DIR/stackrc
-
-# Run everything in the exercises/ directory that isn't explicitly disabled
-
-# comma separated list of script basenames to skip
-# to refrain from exercising euca.sh use SKIP_EXERCISES=euca
-SKIP_EXERCISES=${SKIP_EXERCISES:-""}
-
-# comma separated list of script basenames to run
-# to run only euca.sh use RUN_EXERCISES=euca
-basenames=${RUN_EXERCISES:-""}
-
-EXERCISE_DIR=$TOP_DIR/exercises
-
-if [[ -z "${basenames}" ]]; then
-    # Locate the scripts we should run
-    basenames=$(for b in `ls $EXERCISE_DIR/*.sh`; do basename $b .sh; done)
-else
-    # If RUN_EXERCISES was specified, ignore SKIP_EXERCISES.
-    SKIP_EXERCISES=
-fi
-
-# Track the state of each script
-passes=""
-failures=""
-skips=""
-
-# Loop over each possible script (by basename)
-for script in $basenames; do
-    if [[ ,$SKIP_EXERCISES, =~ ,$script, ]]; then
-        skips="$skips $script"
-    else
-        echo "====================================================================="
-        echo Running $script
-        echo "====================================================================="
-        $EXERCISE_DIR/$script.sh
-        exitcode=$?
-        if [[ $exitcode == 55 ]]; then
-            skips="$skips $script"
-        elif [[ $exitcode -ne 0 ]]; then
-            failures="$failures $script"
-        else
-            passes="$passes $script"
-        fi
-    fi
-done
-
-# output status of exercise run
-echo "====================================================================="
-for script in $skips; do
-    echo SKIP $script
-done
-for script in $passes; do
-    echo PASS $script
-done
-for script in $failures; do
-    echo FAILED $script
-done
-echo "====================================================================="
-
-if [[ -n "$failures" ]]; then
-    exit 1
-fi

exerciserc

@@ -1,32 +0,0 @@
-#!/usr/bin/env bash
-#
-# source exerciserc
-#
-# Configure the DevStack exercise scripts
-# For best results, source this _after_ stackrc/localrc as it will set
-# values only if they are not already set.
-
-# Max time to wait while vm goes from build to active state
-export ACTIVE_TIMEOUT=${ACTIVE_TIMEOUT:-30}
-
-# Max time to wait for proper IP association and dis-association.
-export ASSOCIATE_TIMEOUT=${ASSOCIATE_TIMEOUT:-15}
-
-# Max time till the vm is bootable
-export BOOT_TIMEOUT=${BOOT_TIMEOUT:-30}
-
-# Max time from run instance command until it is running
-export RUNNING_TIMEOUT=${RUNNING_TIMEOUT:-$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT))}
-
-# Max time to wait for a vm to terminate
-export TERMINATE_TIMEOUT=${TERMINATE_TIMEOUT:-30}
-
-# Max time to wait for a euca-volume command to propagate
-export VOLUME_TIMEOUT=${VOLUME_TIMEOUT:-30}
-
-# Max time to wait for a euca-delete command to propagate
-export VOLUME_DELETE_TIMEOUT=${SNAPSHOT_DELETE_TIMEOUT:-60}
-
-# The size of the volume we want to boot from; some storage back-ends
-# do not allow a disk resize, so it's important that this can be tuned
-export DEFAULT_VOLUME_SIZE=${DEFAULT_VOLUME_SIZE:-1}

exercises/aggregates.sh

@@ -1,155 +0,0 @@
-#!/usr/bin/env bash
-
-# **aggregates.sh**
-
-# This script demonstrates how to use host aggregates:
-#
-# *  Create an Aggregate
-# *  Updating Aggregate details
-# *  Testing Aggregate metadata
-# *  Testing Aggregate delete
-# *  Testing General Aggregates (https://blueprints.launchpad.net/nova/+spec/general-host-aggregates)
-# *  Testing add/remove hosts (with one host)
-
-echo "**************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "**************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# Test as the admin user
-. $TOP_DIR/openrc admin admin
-
-# If nova api is not enabled we exit with exitcode 55 so that
-# the exercise is skipped
-is_service_enabled n-api || exit 55
-
-# Cells does not support aggregates.
-is_service_enabled n-cell && exit 55
-
-# Create an aggregate
-# ===================
-
-AGGREGATE_NAME=test_aggregate_$RANDOM
-AGGREGATE2_NAME=test_aggregate_$RANDOM
-AGGREGATE_A_ZONE=nova
-
-function exit_if_aggregate_present {
-    aggregate_name=$1
-
-    if [ $(nova aggregate-list | grep -c " $aggregate_name ") == 0 ]; then
-        echo "SUCCESS $aggregate_name not present"
-    else
-        die $LINENO "found aggregate: $aggregate_name"
-        exit -1
-    fi
-}
-
-exit_if_aggregate_present $AGGREGATE_NAME
-
-AGGREGATE_ID=$(nova aggregate-create $AGGREGATE_NAME $AGGREGATE_A_ZONE | grep " $AGGREGATE_NAME " | get_field 1)
-die_if_not_set $LINENO AGGREGATE_ID "Failure creating AGGREGATE_ID for $AGGREGATE_NAME $AGGREGATE_A_ZONE"
-
-AGGREGATE2_ID=$(nova aggregate-create $AGGREGATE2_NAME $AGGREGATE_A_ZONE | grep " $AGGREGATE2_NAME " | get_field 1)
-die_if_not_set $LINENO AGGREGATE2_ID "Fail creating AGGREGATE2_ID for $AGGREGATE2_NAME $AGGREGATE_A_ZONE"
-
-# check aggregate created
-nova aggregate-list | grep -q " $AGGREGATE_NAME " || die $LINENO "Aggregate $AGGREGATE_NAME not created"
-
-
-# Ensure creating a duplicate fails
-# =================================
-
-if nova aggregate-create $AGGREGATE_NAME $AGGREGATE_A_ZONE; then
-    die $LINENO "could create duplicate aggregate"
-fi
-
-
-# Test aggregate-update (and aggregate-details)
-# =============================================
-AGGREGATE_NEW_NAME=test_aggregate_$RANDOM
-
-nova aggregate-update $AGGREGATE_ID $AGGREGATE_NEW_NAME
-nova aggregate-details $AGGREGATE_ID | grep $AGGREGATE_NEW_NAME
-nova aggregate-details $AGGREGATE_ID | grep $AGGREGATE_A_ZONE
-
-nova aggregate-update $AGGREGATE_ID $AGGREGATE_NAME $AGGREGATE_A_ZONE
-nova aggregate-details $AGGREGATE_ID | grep $AGGREGATE_NAME
-nova aggregate-details $AGGREGATE_ID | grep $AGGREGATE_A_ZONE
-
-
-# Test aggregate-set-metadata
-# ===========================
-META_DATA_1_KEY=asdf
-META_DATA_2_KEY=foo
-META_DATA_3_KEY=bar
-
-#ensure no additional metadata is set
-nova aggregate-details $AGGREGATE_ID | egrep "\|[{u ]*'availability_zone.+$AGGREGATE_A_ZONE'[ }]*\|"
-
-nova aggregate-set-metadata $AGGREGATE_ID ${META_DATA_1_KEY}=123
-nova aggregate-details $AGGREGATE_ID | grep $META_DATA_1_KEY
-nova aggregate-details $AGGREGATE_ID | grep 123
-
-nova aggregate-set-metadata $AGGREGATE_ID ${META_DATA_2_KEY}=456
-nova aggregate-details $AGGREGATE_ID | grep $META_DATA_1_KEY
-nova aggregate-details $AGGREGATE_ID | grep $META_DATA_2_KEY
-
-nova aggregate-set-metadata $AGGREGATE_ID $META_DATA_2_KEY ${META_DATA_3_KEY}=789
-nova aggregate-details $AGGREGATE_ID | grep $META_DATA_1_KEY
-nova aggregate-details $AGGREGATE_ID | grep $META_DATA_3_KEY
-
-nova aggregate-details $AGGREGATE_ID | grep $META_DATA_2_KEY && die $LINENO "ERROR metadata was not cleared"
-
-nova aggregate-set-metadata $AGGREGATE_ID $META_DATA_3_KEY $META_DATA_1_KEY
-nova aggregate-details $AGGREGATE_ID | egrep "\|[{u ]*'availability_zone.+$AGGREGATE_A_ZONE'[ }]*\|"
-
-
-# Test aggregate-add/remove-host
-# ==============================
-if [ "$VIRT_DRIVER" == "xenserver" ]; then
-    echo "TODO(johngarbutt) add tests for add/remove host from pool aggregate"
-fi
-FIRST_HOST=$(nova host-list | grep compute | get_field 1 | head -1)
-# Make sure can add two aggregates to same host
-nova aggregate-add-host $AGGREGATE_ID $FIRST_HOST
-nova aggregate-add-host $AGGREGATE2_ID $FIRST_HOST
-if nova aggregate-add-host $AGGREGATE2_ID $FIRST_HOST; then
-    die $LINENO "could add duplicate host to single aggregate"
-fi
-nova aggregate-remove-host $AGGREGATE2_ID $FIRST_HOST
-nova aggregate-remove-host $AGGREGATE_ID $FIRST_HOST
-
-# Test aggregate-delete
-# =====================
-nova aggregate-delete $AGGREGATE_ID
-nova aggregate-delete $AGGREGATE2_ID
-exit_if_aggregate_present $AGGREGATE_NAME
-
-set +o xtrace
-echo "**************************************************"
-echo "End DevStack Exercise: $0"
-echo "**************************************************"

exercises/boot_from_volume.sh

@@ -1,223 +0,0 @@
-#!/usr/bin/env bash
-
-# **boot_from_volume.sh**
-
-# This script demonstrates how to boot from a volume.  It does the following:
-#
-# *  Create a bootable volume
-# *  Boot a volume-backed instance
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import project functions
-source $TOP_DIR/lib/cinder
-source $TOP_DIR/lib/neutron
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# If cinder is not enabled we exit with exitcode 55 so that
-# the exercise is skipped
-is_service_enabled cinder || exit 55
-
-# Ironic does not support boot from volume.
-[ "$VIRT_DRIVER" == "ironic" ] && exit 55
-
-# Instance type to create
-DEFAULT_INSTANCE_TYPE=${DEFAULT_INSTANCE_TYPE:-m1.tiny}
-
-# Boot this image, use first AMI image if unset
-DEFAULT_IMAGE_NAME=${DEFAULT_IMAGE_NAME:-ami}
-
-# Security group name
-SECGROUP=${SECGROUP:-boot_secgroup}
-
-# Instance and volume names
-VM_NAME=${VM_NAME:-ex-bfv-inst}
-VOL_NAME=${VOL_NAME:-ex-vol-bfv}
-
-
-# Launching a server
-# ==================
-
-# List servers for tenant:
-nova list
-
-# Images
-# ------
-
-# List the images available
-openstack image list
-
-# Grab the id of the image to launch
-IMAGE=$(openstack image list | egrep " $DEFAULT_IMAGE_NAME " | get_field 1)
-die_if_not_set $LINENO IMAGE "Failure getting image $DEFAULT_IMAGE_NAME"
-
-# Security Groups
-# ---------------
-
-# List security groups
-nova secgroup-list
-
-if is_service_enabled n-cell; then
-    # Cells does not support security groups, so force the use of "default"
-    SECGROUP="default"
-    echo "Using the default security group because of Cells."
-else
-    # Create a secgroup
-    if ! nova secgroup-list | grep -q $SECGROUP; then
-        nova secgroup-create $SECGROUP "$SECGROUP description"
-        if ! timeout $ASSOCIATE_TIMEOUT sh -c "while ! nova secgroup-list | grep -q $SECGROUP; do sleep 1; done"; then
-            echo "Security group not created"
-            exit 1
-        fi
-    fi
-fi
-
-# Configure Security Group Rules
-if ! nova secgroup-list-rules $SECGROUP | grep -q icmp; then
-    nova secgroup-add-rule $SECGROUP icmp -1 -1 0.0.0.0/0
-fi
-if ! nova secgroup-list-rules $SECGROUP | grep -q " tcp .* 22 "; then
-    nova secgroup-add-rule $SECGROUP tcp 22 22 0.0.0.0/0
-fi
-
-# List secgroup rules
-nova secgroup-list-rules $SECGROUP
-
-# Set up instance
-# ---------------
-
-# List flavors
-nova flavor-list
-
-# Select a flavor
-INSTANCE_TYPE=$(nova flavor-list | grep $DEFAULT_INSTANCE_TYPE | get_field 1)
-if [[ -z "$INSTANCE_TYPE" ]]; then
-    # grab the first flavor in the list to launch if default doesn't exist
-    INSTANCE_TYPE=$(nova flavor-list | head -n 4 | tail -n 1 | get_field 1)
-fi
-
-# Clean-up from previous runs
-nova delete $VM_NAME || true
-if ! timeout $ACTIVE_TIMEOUT sh -c "while nova show $VM_NAME; do sleep 1; done"; then
-    echo "server didn't terminate!"
-    exit 1
-fi
-
-# Setup Keypair
-KEY_NAME=test_key
-KEY_FILE=key.pem
-nova keypair-delete $KEY_NAME || true
-nova keypair-add $KEY_NAME > $KEY_FILE
-chmod 600 $KEY_FILE
-
-# Set up volume
-# -------------
-
-# Delete any old volume
-cinder delete $VOL_NAME || true
-if ! timeout $ACTIVE_TIMEOUT sh -c "while cinder list | grep $VOL_NAME; do sleep 1; done"; then
-    echo "Volume $VOL_NAME not deleted"
-    exit 1
-fi
-
-# Create the bootable volume
-start_time=$(date +%s)
-cinder create --image-id $IMAGE --display-name=$VOL_NAME --display-description "test bootable volume: $VOL_NAME" $DEFAULT_VOLUME_SIZE || \
-    die $LINENO "Failure creating volume $VOL_NAME"
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! cinder list | grep $VOL_NAME | grep available; do sleep 1; done"; then
-    echo "Volume $VOL_NAME not created"
-    exit 1
-fi
-end_time=$(date +%s)
-echo "Completed cinder create in $((end_time - start_time)) seconds"
-
-# Get volume ID
-VOL_ID=$(cinder list | grep $VOL_NAME  | get_field 1)
-die_if_not_set $LINENO VOL_ID "Failure retrieving volume ID for $VOL_NAME"
-
-# Boot instance
-# -------------
-
-# Boot using the --block-device-mapping param. The format of mapping is:
-# <dev_name>=<id>:<type>:<size(GB)>:<delete_on_terminate>
-# Leaving the middle two fields blank appears to do-the-right-thing
-VM_UUID=$(nova boot --flavor $INSTANCE_TYPE --image $IMAGE --block-device-mapping vda=$VOL_ID --security-groups=$SECGROUP --key-name $KEY_NAME $VM_NAME | grep ' id ' | get_field 2)
-die_if_not_set $LINENO VM_UUID "Failure launching $VM_NAME"
-
-# Check that the status is active within ACTIVE_TIMEOUT seconds
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! nova show $VM_UUID | grep status | grep -q ACTIVE; do sleep 1; done"; then
-    echo "server didn't become active!"
-    exit 1
-fi
-
-# Get the instance IP
-IP=$(get_instance_ip $VM_UUID $PRIVATE_NETWORK_NAME)
-
-die_if_not_set $LINENO IP "Failure retrieving IP address"
-
-# Private IPs can be pinged in single node deployments
-ping_check "$PRIVATE_NETWORK_NAME" $IP $BOOT_TIMEOUT
-
-# Clean up
-# --------
-
-# Delete volume backed instance
-nova delete $VM_UUID || die $LINENO "Failure deleting instance $VM_NAME"
-if ! timeout $TERMINATE_TIMEOUT sh -c "while nova list | grep -q $VM_UUID; do sleep 1; done"; then
-    echo "Server $VM_NAME not deleted"
-    exit 1
-fi
-
-# Wait for volume to be released
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! cinder list | grep $VOL_NAME | grep available; do sleep 1; done"; then
-    echo "Volume $VOL_NAME not released"
-    exit 1
-fi
-
-# Delete volume
-start_time=$(date +%s)
-cinder delete $VOL_ID || die $LINENO "Failure deleting volume $VOLUME_NAME"
-if ! timeout $ACTIVE_TIMEOUT sh -c "while cinder list | grep $VOL_NAME; do sleep 1; done"; then
-    echo "Volume $VOL_NAME not deleted"
-    exit 1
-fi
-end_time=$(date +%s)
-echo "Completed cinder delete in $((end_time - start_time)) seconds"
-
-if [[ $SECGROUP = "default" ]] ; then
-    echo "Skipping deleting default security group"
-else
-    # Delete secgroup
-    nova secgroup-delete $SECGROUP || die $LINENO "Failure deleting security group $SECGROUP"
-fi
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/bundle.sh

@@ -1,74 +0,0 @@
-#!/usr/bin/env bash
-
-# **bundle.sh**
-
-# we will use the ``euca2ools`` cli tool that wraps the python boto
-# library to test ec2 bundle upload compatibility
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import EC2 configuration
-source $TOP_DIR/eucarc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# Remove old certificates
-rm -f $TOP_DIR/cacert.pem
-rm -f $TOP_DIR/cert.pem
-rm -f $TOP_DIR/pk.pem
-
-# If nova api is not enabled we exit with exitcode 55 so that
-# the exercise is skipped
-is_service_enabled n-api || exit 55
-
-# Get Certificates
-nova x509-get-root-cert $TOP_DIR/cacert.pem
-nova x509-create-cert $TOP_DIR/pk.pem $TOP_DIR/cert.pem
-
-# Max time to wait for image to be registered
-REGISTER_TIMEOUT=${REGISTER_TIMEOUT:-15}
-
-BUCKET=testbucket
-IMAGE=bundle.img
-truncate -s 5M /tmp/$IMAGE
-euca-bundle-image -i /tmp/$IMAGE || die $LINENO "Failure bundling image $IMAGE"
-
-euca-upload-bundle --debug -b $BUCKET -m /tmp/$IMAGE.manifest.xml || die $LINENO "Failure uploading bundle $IMAGE to $BUCKET"
-
-AMI=`euca-register $BUCKET/$IMAGE.manifest.xml | cut -f2`
-die_if_not_set $LINENO AMI "Failure registering $BUCKET/$IMAGE"
-
-# Wait for the image to become available
-if ! timeout $REGISTER_TIMEOUT sh -c "while euca-describe-images | grep $AMI | grep -q available; do sleep 1; done"; then
-    die $LINENO "Image $AMI not available within $REGISTER_TIMEOUT seconds"
-fi
-
-# Clean up
-euca-deregister $AMI || die $LINENO "Failure deregistering $AMI"
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/client-args.sh

@@ -1,176 +0,0 @@
-#!/usr/bin/env bash
-
-# **client-args.sh**
-
-# Test OpenStack client authentication arguments handling
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# Unset all of the known NOVA_* vars
-unset NOVA_API_KEY
-unset NOVA_ENDPOINT_NAME
-unset NOVA_PASSWORD
-unset NOVA_PROJECT_ID
-unset NOVA_REGION_NAME
-unset NOVA_URL
-unset NOVA_USERNAME
-unset NOVA_VERSION
-
-# Save the known variables for later
-export x_TENANT_NAME=$OS_TENANT_NAME
-export x_USERNAME=$OS_USERNAME
-export x_PASSWORD=$OS_PASSWORD
-export x_AUTH_URL=$OS_AUTH_URL
-
-# Unset the usual variables to force argument processing
-unset OS_TENANT_NAME
-unset OS_USERNAME
-unset OS_PASSWORD
-unset OS_AUTH_URL
-
-# Common authentication args
-TENANT_ARG="--os-tenant-name=$x_TENANT_NAME"
-ARGS="--os-username=$x_USERNAME --os-password=$x_PASSWORD --os-auth-url=$x_AUTH_URL"
-
-# Set global return
-RETURN=0
-
-# Keystone client
-# ---------------
-if [[ "$ENABLED_SERVICES" =~ "key" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "key" ]]; then
-        STATUS_KEYSTONE="Skipped"
-    else
-        echo -e "\nTest Keystone"
-        if keystone $TENANT_ARG $ARGS catalog --service identity; then
-            STATUS_KEYSTONE="Succeeded"
-        else
-            STATUS_KEYSTONE="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-# Nova client
-# -----------
-
-if [[ "$ENABLED_SERVICES" =~ "n-api" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "n-api" ]]; then
-        STATUS_NOVA="Skipped"
-        STATUS_EC2="Skipped"
-    else
-        # Test OSAPI
-        echo -e "\nTest Nova"
-        if nova $TENANT_ARG $ARGS flavor-list; then
-            STATUS_NOVA="Succeeded"
-        else
-            STATUS_NOVA="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-# Cinder client
-# -------------
-
-if [[ "$ENABLED_SERVICES" =~ "c-api" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "c-api" ]]; then
-        STATUS_CINDER="Skipped"
-    else
-        echo -e "\nTest Cinder"
-        if cinder $TENANT_ARG $ARGS list; then
-            STATUS_CINDER="Succeeded"
-        else
-            STATUS_CINDER="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-# Glance client
-# -------------
-
-if [[ "$ENABLED_SERVICES" =~ "g-api" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "g-api" ]]; then
-        STATUS_GLANCE="Skipped"
-    else
-        echo -e "\nTest Glance"
-        if openstack $TENANT_ARG $ARGS image list; then
-            STATUS_GLANCE="Succeeded"
-        else
-            STATUS_GLANCE="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-# Swift client
-# ------------
-
-if [[ "$ENABLED_SERVICES" =~ "swift" || "$ENABLED_SERVICES" =~ "s-proxy" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "swift" ]]; then
-        STATUS_SWIFT="Skipped"
-    else
-        echo -e "\nTest Swift"
-        if swift $TENANT_ARG $ARGS stat; then
-            STATUS_SWIFT="Succeeded"
-        else
-            STATUS_SWIFT="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-set +o xtrace
-
-
-# Results
-# =======
-
-function report {
-    if [[ -n "$2" ]]; then
-        echo "$1: $2"
-    fi
-}
-
-echo -e "\n"
-report "Keystone" $STATUS_KEYSTONE
-report "Nova" $STATUS_NOVA
-report "Cinder" $STATUS_CINDER
-report "Glance" $STATUS_GLANCE
-report "Swift" $STATUS_SWIFT
-
-if (( $RETURN == 0 )); then
-    echo "*********************************************************************"
-    echo "SUCCESS: End DevStack Exercise: $0"
-    echo "*********************************************************************"
-fi
-
-exit $RETURN

exercises/client-env.sh

@@ -1,188 +0,0 @@
-#!/usr/bin/env bash
-
-# **client-env.sh**
-
-# Test OpenStack client environment variable handling
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc admin
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# Unset all of the known NOVA_* vars
-unset NOVA_API_KEY
-unset NOVA_ENDPOINT_NAME
-unset NOVA_PASSWORD
-unset NOVA_PROJECT_ID
-unset NOVA_REGION_NAME
-unset NOVA_URL
-unset NOVA_USERNAME
-unset NOVA_VERSION
-
-for i in OS_TENANT_NAME OS_USERNAME OS_PASSWORD OS_AUTH_URL; do
-    is_set $i
-    if [[ $? -ne 0 ]]; then
-        echo "$i expected to be set"
-        ABORT=1
-    fi
-done
-if [[ -n "$ABORT" ]]; then
-    exit 1
-fi
-
-# Set global return
-RETURN=0
-
-# Keystone client
-# ---------------
-if [[ "$ENABLED_SERVICES" =~ "key" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "key" ]]; then
-        STATUS_KEYSTONE="Skipped"
-    else
-        echo -e "\nTest Keystone"
-        if openstack endpoint show identity; then
-            STATUS_KEYSTONE="Succeeded"
-        else
-            STATUS_KEYSTONE="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-# Nova client
-# -----------
-
-if [[ "$ENABLED_SERVICES" =~ "n-api" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "n-api" ]]; then
-        STATUS_NOVA="Skipped"
-        STATUS_EC2="Skipped"
-    else
-        # Test OSAPI
-        echo -e "\nTest Nova"
-        if nova flavor-list; then
-            STATUS_NOVA="Succeeded"
-        else
-            STATUS_NOVA="Failed"
-            RETURN=1
-        fi
-
-        # Test EC2 API
-        echo -e "\nTest EC2"
-        # Get EC2 creds
-        source $TOP_DIR/eucarc
-
-        if euca-describe-images; then
-            STATUS_EC2="Succeeded"
-        else
-            STATUS_EC2="Failed"
-            RETURN=1
-        fi
-
-        # Clean up side effects
-        unset NOVA_VERSION
-    fi
-fi
-
-# Cinder client
-# -------------
-
-if [[ "$ENABLED_SERVICES" =~ "c-api" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "c-api" ]]; then
-        STATUS_CINDER="Skipped"
-    else
-        echo -e "\nTest Cinder"
-        if cinder list; then
-            STATUS_CINDER="Succeeded"
-        else
-            STATUS_CINDER="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-# Glance client
-# -------------
-
-if [[ "$ENABLED_SERVICES" =~ "g-api" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "g-api" ]]; then
-        STATUS_GLANCE="Skipped"
-    else
-        echo -e "\nTest Glance"
-        if openstack image list; then
-            STATUS_GLANCE="Succeeded"
-        else
-            STATUS_GLANCE="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-# Swift client
-# ------------
-
-
-if [[ "$ENABLED_SERVICES" =~ "swift" || "$ENABLED_SERVICES" =~ "s-proxy" ]]; then
-    if [[ "$SKIP_EXERCISES" =~ "swift" ]]; then
-        STATUS_SWIFT="Skipped"
-    else
-        echo -e "\nTest Swift"
-        if swift stat; then
-            STATUS_SWIFT="Succeeded"
-        else
-            STATUS_SWIFT="Failed"
-            RETURN=1
-        fi
-    fi
-fi
-
-set +o xtrace
-
-
-# Results
-# =======
-
-function report {
-    if [[ -n "$2" ]]; then
-        echo "$1: $2"
-    fi
-}
-
-echo -e "\n"
-report "Keystone" $STATUS_KEYSTONE
-report "Nova" $STATUS_NOVA
-report "EC2" $STATUS_EC2
-report "Cinder" $STATUS_CINDER
-report "Glance" $STATUS_GLANCE
-report "Swift" $STATUS_SWIFT
-
-if (( $RETURN == 0 )); then
-    echo "*********************************************************************"
-    echo "SUCCESS: End DevStack Exercise: $0"
-    echo "*********************************************************************"
-fi
-
-exit $RETURN

exercises/euca.sh

@@ -1,192 +0,0 @@
-#!/usr/bin/env bash
-
-# **euca.sh**
-
-# we will use the ``euca2ools`` cli tool that wraps the python boto
-# library to test ec2 compatibility
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-VOLUME_SIZE=1
-ATTACH_DEVICE=/dev/vdc
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import EC2 configuration
-source $TOP_DIR/eucarc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# Import project functions
-source $TOP_DIR/lib/neutron
-
-# If nova api is not enabled we exit with exitcode 55 so that
-# the exercise is skipped
-is_service_enabled n-api || exit 55
-
-# Instance type to create
-DEFAULT_INSTANCE_TYPE=${DEFAULT_INSTANCE_TYPE:-m1.tiny}
-
-# Boot this image, use first AMI image if unset
-DEFAULT_IMAGE_NAME=${DEFAULT_IMAGE_NAME:-ami}
-
-# Security group name
-SECGROUP=${SECGROUP:-euca_secgroup}
-
-
-# Launching a server
-# ==================
-
-# Find a machine image to boot
-IMAGE=`euca-describe-images | grep machine | grep ${DEFAULT_IMAGE_NAME} | cut -f2 | head -n1`
-die_if_not_set $LINENO IMAGE "Failure getting image $DEFAULT_IMAGE_NAME"
-
-if is_service_enabled n-cell; then
-    # Cells does not support security groups, so force the use of "default"
-    SECGROUP="default"
-    echo "Using the default security group because of Cells."
-else
-    # Add a secgroup
-    if ! euca-describe-groups | grep -q $SECGROUP; then
-        euca-add-group -d "$SECGROUP description" $SECGROUP
-        if ! timeout $ASSOCIATE_TIMEOUT sh -c "while ! euca-describe-groups | grep -q $SECGROUP; do sleep 1; done"; then
-            die $LINENO "Security group not created"
-        fi
-    fi
-fi
-
-# Launch it
-INSTANCE=`euca-run-instances -g $SECGROUP -t $DEFAULT_INSTANCE_TYPE $IMAGE | grep INSTANCE | cut -f2`
-die_if_not_set $LINENO INSTANCE "Failure launching instance"
-
-# Assure it has booted within a reasonable time
-if ! timeout $RUNNING_TIMEOUT sh -c "while ! euca-describe-instances $INSTANCE | grep -q running; do sleep 1; done"; then
-    die $LINENO "server didn't become active within $RUNNING_TIMEOUT seconds"
-fi
-
-# Volumes
-# -------
-if is_service_enabled c-vol && ! is_service_enabled n-cell && [ "$VIRT_DRIVER" != "ironic" ]; then
-    VOLUME_ZONE=`euca-describe-availability-zones | head -n1 | cut -f2`
-    die_if_not_set $LINENO VOLUME_ZONE "Failure to find zone for volume"
-
-    VOLUME=`euca-create-volume -s 1 -z $VOLUME_ZONE | cut -f2`
-    die_if_not_set $LINENO VOLUME "Failure to create volume"
-
-    # Test that volume has been created
-    VOLUME=`euca-describe-volumes $VOLUME | cut -f2`
-    die_if_not_set $LINENO VOLUME "Failure to get volume"
-
-    # Test volume has become available
-    if ! timeout $RUNNING_TIMEOUT sh -c "while ! euca-describe-volumes $VOLUME | grep -q available; do sleep 1; done"; then
-        die $LINENO "volume didn't become available within $RUNNING_TIMEOUT seconds"
-    fi
-
-    # Attach volume to an instance
-    euca-attach-volume -i $INSTANCE -d $ATTACH_DEVICE $VOLUME || \
-        die $LINENO "Failure attaching volume $VOLUME to $INSTANCE"
-    if ! timeout $ACTIVE_TIMEOUT sh -c "while ! euca-describe-volumes $VOLUME | grep -A 1 in-use | grep -q attach; do sleep 1; done"; then
-        die $LINENO "Could not attach $VOLUME to $INSTANCE"
-    fi
-
-    # Detach volume from an instance
-    euca-detach-volume $VOLUME || \
-        die $LINENO "Failure detaching volume $VOLUME to $INSTANCE"
-    if ! timeout $ACTIVE_TIMEOUT sh -c "while ! euca-describe-volumes $VOLUME | grep -q available; do sleep 1; done"; then
-        die $LINENO "Could not detach $VOLUME to $INSTANCE"
-    fi
-
-    # Remove volume
-    euca-delete-volume $VOLUME || \
-        die $LINENO "Failure to delete volume"
-    if ! timeout $ACTIVE_TIMEOUT sh -c "while euca-describe-volumes | grep $VOLUME; do sleep 1; done"; then
-        die $LINENO "Could not delete $VOLUME"
-    fi
-else
-    echo "Volume Tests Skipped"
-fi
-
-if is_service_enabled n-cell; then
-    echo "Floating IP Tests Skipped because of Cells."
-else
-    # Allocate floating address
-    FLOATING_IP=`euca-allocate-address | cut -f2`
-    die_if_not_set $LINENO FLOATING_IP "Failure allocating floating IP"
-    # describe all instances at this moment
-    euca-describe-instances
-    # Associate floating address
-    euca-associate-address -i $INSTANCE $FLOATING_IP || \
-        die $LINENO "Failure associating address $FLOATING_IP to $INSTANCE"
-
-    # Authorize pinging
-    euca-authorize -P icmp -s 0.0.0.0/0 -t -1:-1 $SECGROUP || \
-        die $LINENO "Failure authorizing rule in $SECGROUP"
-
-    # Test we can ping our floating ip within ASSOCIATE_TIMEOUT seconds
-    ping_check "$PUBLIC_NETWORK_NAME" $FLOATING_IP $ASSOCIATE_TIMEOUT
-
-    # Revoke pinging
-    euca-revoke -P icmp -s 0.0.0.0/0 -t -1:-1 $SECGROUP || \
-        die $LINENO "Failure revoking rule in $SECGROUP"
-
-    # Release floating address
-    euca-disassociate-address $FLOATING_IP || \
-        die $LINENO "Failure disassociating address $FLOATING_IP"
-
-    # Wait just a tick for everything above to complete so release doesn't fail
-    if ! timeout $ASSOCIATE_TIMEOUT sh -c "while euca-describe-addresses | grep $INSTANCE | grep -q $FLOATING_IP; do sleep 1; done"; then
-        die $LINENO "Floating ip $FLOATING_IP not disassociated within $ASSOCIATE_TIMEOUT seconds"
-    fi
-
-    # Release floating address
-    euca-release-address $FLOATING_IP || \
-        die $LINENO "Failure releasing address $FLOATING_IP"
-
-    # Wait just a tick for everything above to complete so terminate doesn't fail
-    if ! timeout $ASSOCIATE_TIMEOUT sh -c "while euca-describe-addresses | grep -q $FLOATING_IP; do sleep 1; done"; then
-        die $LINENO "Floating ip $FLOATING_IP not released within $ASSOCIATE_TIMEOUT seconds"
-    fi
-fi
-
-# Terminate instance
-euca-terminate-instances $INSTANCE || \
-    die $LINENO "Failure terminating instance $INSTANCE"
-
-# Assure it has terminated within a reasonable time. The behaviour of this
-# case changed with bug/836978. Requesting the status of an invalid instance
-# will now return an error message including the instance id, so we need to
-# filter that out.
-if ! timeout $TERMINATE_TIMEOUT sh -c "while euca-describe-instances $INSTANCE | grep -ve '\(InstanceNotFound\|InvalidInstanceID\.NotFound\)' | grep -q $INSTANCE; do sleep 1; done"; then
-    die $LINENO "server didn't terminate within $TERMINATE_TIMEOUT seconds"
-fi
-
-if [[ "$SECGROUP" = "default" ]] ; then
-    echo "Skipping deleting default security group"
-else
-    # Delete secgroup
-    euca-delete-group $SECGROUP || die $LINENO "Failure deleting security group $SECGROUP"
-fi
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/floating_ips.sh

@@ -1,215 +0,0 @@
-#!/usr/bin/env bash
-
-# **floating_ips.sh** - using the cloud can be fun
-
-# Test instance connectivity with the ``nova`` command from ``python-novaclient``
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import project functions
-source $TOP_DIR/lib/neutron
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# If nova api is not enabled we exit with exitcode 55 so that
-# the exercise is skipped
-is_service_enabled n-api || exit 55
-
-# Instance type to create
-DEFAULT_INSTANCE_TYPE=${DEFAULT_INSTANCE_TYPE:-m1.tiny}
-
-# Boot this image, use first AMI image if unset
-DEFAULT_IMAGE_NAME=${DEFAULT_IMAGE_NAME:-ami}
-
-# Security group name
-SECGROUP=${SECGROUP:-test_secgroup}
-
-# Default floating IP pool name
-DEFAULT_FLOATING_POOL=${DEFAULT_FLOATING_POOL:-public}
-
-# Additional floating IP pool and range
-TEST_FLOATING_POOL=${TEST_FLOATING_POOL:-test}
-
-# Instance name
-VM_NAME="ex-float"
-
-# Cells does not support floating ips API calls
-is_service_enabled n-cell && exit 55
-
-# Launching a server
-# ==================
-
-# List servers for tenant:
-nova list
-
-# Images
-# ------
-
-# List the images available
-openstack image list
-
-# Grab the id of the image to launch
-IMAGE=$(openstack image list | egrep " $DEFAULT_IMAGE_NAME " | get_field 1)
-die_if_not_set $LINENO IMAGE "Failure getting image $DEFAULT_IMAGE_NAME"
-
-# Security Groups
-# ---------------
-
-# List security groups
-nova secgroup-list
-
-# Create a secgroup
-if ! nova secgroup-list | grep -q $SECGROUP; then
-    nova secgroup-create $SECGROUP "$SECGROUP description"
-    if ! timeout $ASSOCIATE_TIMEOUT sh -c "while ! nova secgroup-list | grep -q $SECGROUP; do sleep 1; done"; then
-        die $LINENO "Security group not created"
-    fi
-fi
-
-# Configure Security Group Rules
-if ! nova secgroup-list-rules $SECGROUP | grep -q icmp; then
-    nova secgroup-add-rule $SECGROUP icmp -1 -1 0.0.0.0/0
-fi
-if ! nova secgroup-list-rules $SECGROUP | grep -q " tcp .* 22 "; then
-    nova secgroup-add-rule $SECGROUP tcp 22 22 0.0.0.0/0
-fi
-
-# List secgroup rules
-nova secgroup-list-rules $SECGROUP
-
-# Set up instance
-# ---------------
-
-# List flavors
-nova flavor-list
-
-# Select a flavor
-INSTANCE_TYPE=$(nova flavor-list | grep $DEFAULT_INSTANCE_TYPE | get_field 1)
-if [[ -z "$INSTANCE_TYPE" ]]; then
-    # grab the first flavor in the list to launch if default doesn't exist
-    INSTANCE_TYPE=$(nova flavor-list | head -n 4 | tail -n 1 | get_field 1)
-    die_if_not_set $LINENO INSTANCE_TYPE "Failure retrieving INSTANCE_TYPE"
-fi
-
-# Clean-up from previous runs
-nova delete $VM_NAME || true
-if ! timeout $ACTIVE_TIMEOUT sh -c "while nova show $VM_NAME; do sleep 1; done"; then
-    die $LINENO "server didn't terminate!"
-    exit 1
-fi
-
-# Boot instance
-# -------------
-
-VM_UUID=$(nova boot --flavor $INSTANCE_TYPE --image $IMAGE --security-groups=$SECGROUP $VM_NAME | grep ' id ' | get_field 2)
-die_if_not_set $LINENO VM_UUID "Failure launching $VM_NAME"
-
-# Check that the status is active within ACTIVE_TIMEOUT seconds
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! nova show $VM_UUID | grep status | grep -q ACTIVE; do sleep 1; done"; then
-    die $LINENO "server didn't become active!"
-fi
-
-# Get the instance IP
-IP=$(get_instance_ip $VM_UUID $PRIVATE_NETWORK_NAME)
-die_if_not_set $LINENO IP "Failure retrieving IP address"
-
-# Private IPs can be pinged in single node deployments
-ping_check "$PRIVATE_NETWORK_NAME" $IP $BOOT_TIMEOUT
-
-# Floating IPs
-# ------------
-
-# Allocate a floating IP from the default pool
-FLOATING_IP=$(nova floating-ip-create | grep $DEFAULT_FLOATING_POOL | get_field 1)
-die_if_not_set $LINENO FLOATING_IP "Failure creating floating IP from pool $DEFAULT_FLOATING_POOL"
-
-# List floating addresses
-if ! timeout $ASSOCIATE_TIMEOUT sh -c "while ! nova floating-ip-list | grep -q $FLOATING_IP; do sleep 1; done"; then
-    die $LINENO "Floating IP not allocated"
-fi
-
-# Add floating IP to our server
-nova add-floating-ip $VM_UUID $FLOATING_IP || \
-    die $LINENO "Failure adding floating IP $FLOATING_IP to $VM_NAME"
-
-# Test we can ping our floating IP within ASSOCIATE_TIMEOUT seconds
-ping_check "$PUBLIC_NETWORK_NAME" $FLOATING_IP $ASSOCIATE_TIMEOUT
-
-if ! is_service_enabled neutron; then
-    # Allocate an IP from second floating pool
-    TEST_FLOATING_IP=$(nova floating-ip-create $TEST_FLOATING_POOL | grep $TEST_FLOATING_POOL | get_field 1)
-    die_if_not_set $LINENO TEST_FLOATING_IP "Failure creating floating IP in $TEST_FLOATING_POOL"
-
-    # list floating addresses
-    if ! timeout $ASSOCIATE_TIMEOUT sh -c "while ! nova floating-ip-list | grep $TEST_FLOATING_POOL | grep -q $TEST_FLOATING_IP; do sleep 1; done"; then
-        die $LINENO "Floating IP not allocated"
-    fi
-fi
-
-# Dis-allow icmp traffic (ping)
-nova secgroup-delete-rule $SECGROUP icmp -1 -1 0.0.0.0/0 || \
-    die $LINENO "Failure deleting security group rule from $SECGROUP"
-
-if ! timeout $ASSOCIATE_TIMEOUT sh -c "while nova secgroup-list-rules $SECGROUP | grep -q icmp; do sleep 1; done"; then
-    die $LINENO "Security group rule not deleted from $SECGROUP"
-fi
-
-# FIXME (anthony): make xs support security groups
-if [ "$VIRT_DRIVER" != "ironic" -a "$VIRT_DRIVER" != "xenserver" -a "$VIRT_DRIVER" != "openvz" ]; then
-    # Test we can aren't able to ping our floating ip within ASSOCIATE_TIMEOUT seconds
-    ping_check "$PUBLIC_NETWORK_NAME" $FLOATING_IP $ASSOCIATE_TIMEOUT Fail
-fi
-
-# Clean up
-# --------
-
-if ! is_service_enabled neutron; then
-    # Delete second floating IP
-    nova floating-ip-delete $TEST_FLOATING_IP || \
-        die $LINENO "Failure deleting floating IP $TEST_FLOATING_IP"
-fi
-
-# Delete the floating ip
-nova floating-ip-delete $FLOATING_IP || \
-    die $LINENO "Failure deleting floating IP $FLOATING_IP"
-
-# Delete instance
-nova delete $VM_UUID || die $LINENO "Failure deleting instance $VM_NAME"
-# Wait for termination
-if ! timeout $TERMINATE_TIMEOUT sh -c "while nova list | grep -q $VM_UUID; do sleep 1; done"; then
-    die $LINENO "Server $VM_NAME not deleted"
-fi
-
-# Delete secgroup
-nova secgroup-delete $SECGROUP || \
-    die $LINENO "Failure deleting security group $SECGROUP"
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/horizon.sh

@@ -1,45 +0,0 @@
-#!/usr/bin/env bash
-
-# **horizon.sh**
-
-# Sanity check that horizon started if enabled
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-is_service_enabled horizon || exit 55
-
-# can we get the front page
-curl http://$SERVICE_HOST 2>/dev/null | grep -q '<h3.*>Log In</h3>' || die $LINENO "Horizon front page not functioning!"
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"
-

exercises/neutron-adv-test.sh

@@ -1,453 +0,0 @@
-#!/usr/bin/env bash
-#
-# Copyright 2012, Cisco Systems
-# Copyright 2012, VMware, Inc.
-# Copyright 2012, NTT MCL, Inc.
-#
-# Please direct any questions to dedutta@cisco.com, dwendlandt@vmware.com, nachi@nttmcl.com
-#
-# **neutron-adv-test.sh**
-
-# Perform integration testing of Nova and other components with Neutron.
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-
-set -o errtrace
-
-trap failed ERR
-function failed {
-    local r=$?
-    set +o errtrace
-    set +o xtrace
-    echo "Failed to execute"
-    echo "Starting cleanup..."
-    delete_all
-    echo "Finished cleanup"
-    exit $r
-}
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-# Environment
-# -----------
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import neutron functions
-source $TOP_DIR/lib/neutron
-
-# If neutron is not enabled we exit with exitcode 55, which means exercise is skipped.
-neutron_plugin_check_adv_test_requirements || exit 55
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# Neutron Settings
-# ----------------
-
-TENANTS="DEMO1"
-# TODO (nati)_Test public network
-#TENANTS="DEMO1,DEMO2"
-
-PUBLIC_NAME="admin"
-DEMO1_NAME="demo1"
-DEMO2_NAME="demo2"
-
-PUBLIC_NUM_NET=1
-DEMO1_NUM_NET=1
-DEMO2_NUM_NET=2
-
-PUBLIC_NET1_CIDR="200.0.0.0/24"
-DEMO1_NET1_CIDR="10.10.0.0/24"
-DEMO2_NET1_CIDR="10.20.0.0/24"
-DEMO2_NET2_CIDR="10.20.1.0/24"
-
-PUBLIC_NET1_GATEWAY="200.0.0.1"
-DEMO1_NET1_GATEWAY="10.10.0.1"
-DEMO2_NET1_GATEWAY="10.20.0.1"
-DEMO2_NET2_GATEWAY="10.20.1.1"
-
-PUBLIC_NUM_VM=1
-DEMO1_NUM_VM=1
-DEMO2_NUM_VM=2
-
-PUBLIC_VM1_NET='admin-net1'
-DEMO1_VM1_NET='demo1-net1'
-# Multinic settings. But this is fail without nic setting in OS image
-DEMO2_VM1_NET='demo2-net1'
-DEMO2_VM2_NET='demo2-net2'
-
-PUBLIC_NUM_ROUTER=1
-DEMO1_NUM_ROUTER=1
-DEMO2_NUM_ROUTER=1
-
-PUBLIC_ROUTER1_NET="admin-net1"
-DEMO1_ROUTER1_NET="demo1-net1"
-DEMO2_ROUTER1_NET="demo2-net1"
-
-# Various functions
-# -----------------
-
-function foreach_tenant {
-    COMMAND=$1
-    for TENANT in ${TENANTS//,/ };do
-        eval ${COMMAND//%TENANT%/$TENANT}
-    done
-}
-
-function foreach_tenant_resource {
-    COMMAND=$1
-    RESOURCE=$2
-    for TENANT in ${TENANTS//,/ };do
-        eval 'NUM=$'"${TENANT}_NUM_$RESOURCE"
-        for i in `seq $NUM`;do
-            local COMMAND_LOCAL=${COMMAND//%TENANT%/$TENANT}
-            COMMAND_LOCAL=${COMMAND_LOCAL//%NUM%/$i}
-            eval $COMMAND_LOCAL
-        done
-    done
-}
-
-function foreach_tenant_vm {
-    COMMAND=$1
-    foreach_tenant_resource "$COMMAND" 'VM'
-}
-
-function foreach_tenant_net {
-    COMMAND=$1
-    foreach_tenant_resource "$COMMAND" 'NET'
-}
-
-function get_image_id {
-    local IMAGE_ID=$(openstack image list | egrep " $DEFAULT_IMAGE_NAME " | get_field 1)
-    die_if_not_set $LINENO IMAGE_ID "Failure retrieving IMAGE_ID"
-    echo "$IMAGE_ID"
-}
-
-function get_tenant_id {
-    local TENANT_NAME=$1
-    local TENANT_ID=`openstack project list | grep " $TENANT_NAME " | head -n 1 | get_field 1`
-    die_if_not_set $LINENO TENANT_ID "Failure retrieving TENANT_ID for $TENANT_NAME"
-    echo "$TENANT_ID"
-}
-
-function get_user_id {
-    local USER_NAME=$1
-    local USER_ID=`openstack user list | grep $USER_NAME | awk '{print $2}'`
-    die_if_not_set $LINENO USER_ID "Failure retrieving USER_ID for $USER_NAME"
-    echo "$USER_ID"
-}
-
-function get_role_id {
-    local ROLE_NAME=$1
-    local ROLE_ID=`openstack role list | grep $ROLE_NAME | awk '{print $2}'`
-    die_if_not_set $LINENO ROLE_ID "Failure retrieving ROLE_ID for $ROLE_NAME"
-    echo "$ROLE_ID"
-}
-
-function get_network_id {
-    local NETWORK_NAME="$1"
-    local NETWORK_ID=`neutron net-list -F id  -- --name=$NETWORK_NAME | awk "NR==4" | awk '{print $2}'`
-    echo $NETWORK_ID
-}
-
-function get_flavor_id {
-    local INSTANCE_TYPE=$1
-    local FLAVOR_ID=`nova flavor-list | grep $INSTANCE_TYPE | awk '{print $2}'`
-    die_if_not_set $LINENO FLAVOR_ID "Failure retrieving FLAVOR_ID for $INSTANCE_TYPE"
-    echo "$FLAVOR_ID"
-}
-
-function confirm_server_active {
-    local VM_UUID=$1
-    if ! timeout $ACTIVE_TIMEOUT sh -c "while ! nova show $VM_UUID | grep status | grep -q ACTIVE; do sleep 1; done"; then
-        echo "server '$VM_UUID' did not become active!"
-        false
-    fi
-}
-
-function neutron_debug_admin {
-    local os_username=$OS_USERNAME
-    local os_tenant_id=$OS_TENANT_ID
-    source $TOP_DIR/openrc admin admin
-    neutron-debug $@
-    source $TOP_DIR/openrc $os_username $os_tenant_id
-}
-
-function add_tenant {
-    openstack project create $1
-    openstack user create $2 --password ${ADMIN_PASSWORD} --project $1
-    openstack role add Member --project $1 --user $2
-}
-
-function remove_tenant {
-    local TENANT=$1
-    local TENANT_ID=$(get_tenant_id $TENANT)
-    openstack project delete $TENANT_ID
-}
-
-function remove_user {
-    local USER=$1
-    local USER_ID=$(get_user_id $USER)
-    openstack user delete $USER_ID
-}
-
-function create_tenants {
-    source $TOP_DIR/openrc admin admin
-    add_tenant demo1 demo1 demo1
-    add_tenant demo2 demo2 demo2
-    source $TOP_DIR/openrc demo demo
-}
-
-function delete_tenants_and_users {
-    source $TOP_DIR/openrc admin admin
-    remove_user demo1
-    remove_tenant demo1
-    remove_user demo2
-    remove_tenant demo2
-    echo "removed all tenants"
-    source $TOP_DIR/openrc demo demo
-}
-
-function create_network {
-    local TENANT=$1
-    local GATEWAY=$2
-    local CIDR=$3
-    local NUM=$4
-    local EXTRA=$5
-    local NET_NAME="${TENANT}-net$NUM"
-    local ROUTER_NAME="${TENANT}-router${NUM}"
-    source $TOP_DIR/openrc admin admin
-    local TENANT_ID=$(get_tenant_id $TENANT)
-    source $TOP_DIR/openrc $TENANT $TENANT
-    local NET_ID=$(neutron net-create --tenant-id $TENANT_ID $NET_NAME $EXTRA| grep ' id ' | awk '{print $4}' )
-    die_if_not_set $LINENO NET_ID "Failure creating NET_ID for $TENANT_ID $NET_NAME $EXTRA"
-    neutron subnet-create --ip-version 4 --tenant-id $TENANT_ID --gateway $GATEWAY $NET_ID $CIDR
-    neutron_debug_admin probe-create --device-owner compute $NET_ID
-    source $TOP_DIR/openrc demo demo
-}
-
-function create_networks {
-    foreach_tenant_net 'create_network ${%TENANT%_NAME} ${%TENANT%_NET%NUM%_GATEWAY} ${%TENANT%_NET%NUM%_CIDR} %NUM% ${%TENANT%_NET%NUM%_EXTRA}'
-    #TODO(nati) test security group function
-    # allow ICMP for both tenant's security groups
-    #source $TOP_DIR/openrc demo1 demo1
-    #$NOVA secgroup-add-rule default icmp -1 -1 0.0.0.0/0
-    #source $TOP_DIR/openrc demo2 demo2
-    #$NOVA secgroup-add-rule default icmp -1 -1 0.0.0.0/0
-}
-
-function create_vm {
-    local TENANT=$1
-    local NUM=$2
-    local NET_NAMES=$3
-    source $TOP_DIR/openrc $TENANT $TENANT
-    local NIC=""
-    for NET_NAME in ${NET_NAMES//,/ };do
-        NIC="$NIC --nic net-id="`get_network_id $NET_NAME`
-    done
-    #TODO (nati) Add multi-nic test
-    #TODO (nati) Add public-net test
-    local VM_UUID=`nova boot --flavor $(get_flavor_id m1.tiny) \
-        --image $(get_image_id) \
-        $NIC \
-        $TENANT-server$NUM | grep ' id ' | cut -d"|" -f3 | sed 's/ //g'`
-    die_if_not_set $LINENO VM_UUID "Failure launching $TENANT-server$NUM"
-    confirm_server_active $VM_UUID
-}
-
-function create_vms {
-    foreach_tenant_vm 'create_vm ${%TENANT%_NAME} %NUM% ${%TENANT%_VM%NUM%_NET}'
-}
-
-function ping_ip {
-    # Test agent connection.  Assumes namespaces are disabled, and
-    # that DHCP is in use, but not L3
-    local VM_NAME=$1
-    local NET_NAME=$2
-    IP=$(get_instance_ip $VM_NAME $NET_NAME)
-    ping_check $NET_NAME $IP $BOOT_TIMEOUT
-}
-
-function check_vm {
-    local TENANT=$1
-    local NUM=$2
-    local VM_NAME="$TENANT-server$NUM"
-    local NET_NAME=$3
-    source $TOP_DIR/openrc $TENANT $TENANT
-    ping_ip $VM_NAME $NET_NAME
-    # TODO (nati) test ssh connection
-    # TODO (nati) test inter connection between vm
-    # TODO (nati) test dhcp host routes
-    # TODO (nati) test multi-nic
-}
-
-function check_vms {
-    foreach_tenant_vm 'check_vm ${%TENANT%_NAME} %NUM% ${%TENANT%_VM%NUM%_NET}'
-}
-
-function shutdown_vm {
-    local TENANT=$1
-    local NUM=$2
-    source $TOP_DIR/openrc $TENANT $TENANT
-    VM_NAME=${TENANT}-server$NUM
-    nova delete $VM_NAME
-}
-
-function shutdown_vms {
-    foreach_tenant_vm 'shutdown_vm ${%TENANT%_NAME} %NUM%'
-    if ! timeout $TERMINATE_TIMEOUT sh -c "while nova list | grep -q ACTIVE; do sleep 1; done"; then
-        die $LINENO "Some VMs failed to shutdown"
-    fi
-}
-
-function delete_network {
-    local TENANT=$1
-    local NUM=$2
-    local NET_NAME="${TENANT}-net$NUM"
-    source $TOP_DIR/openrc admin admin
-    local TENANT_ID=$(get_tenant_id $TENANT)
-    #TODO(nati) comment out until l3-agent merged
-    #for res in port subnet net router;do
-    for net_id in `neutron net-list -c id -c name | grep $NET_NAME | awk '{print $2}'`;do
-        delete_probe $net_id
-        neutron subnet-list | grep $net_id | awk '{print $2}' | xargs -I% neutron subnet-delete %
-        neutron net-delete $net_id
-    done
-    source $TOP_DIR/openrc demo demo
-}
-
-function delete_networks {
-    foreach_tenant_net 'delete_network ${%TENANT%_NAME} %NUM%'
-    # TODO(nati) add secuirty group check after it is implemented
-    # source $TOP_DIR/openrc demo1 demo1
-    # nova secgroup-delete-rule default icmp -1 -1 0.0.0.0/0
-    # source $TOP_DIR/openrc demo2 demo2
-    # nova secgroup-delete-rule default icmp -1 -1 0.0.0.0/0
-}
-
-function create_all {
-    create_tenants
-    create_networks
-    create_vms
-}
-
-function delete_all {
-    shutdown_vms
-    delete_networks
-    delete_tenants_and_users
-}
-
-function all {
-    create_all
-    check_vms
-    delete_all
-}
-
-# Test functions
-# --------------
-
-function test_functions {
-    IMAGE=$(get_image_id)
-    echo $IMAGE
-
-    TENANT_ID=$(get_tenant_id demo)
-    echo $TENANT_ID
-
-    FLAVOR_ID=$(get_flavor_id m1.tiny)
-    echo $FLAVOR_ID
-
-    NETWORK_ID=$(get_network_id admin)
-    echo $NETWORK_ID
-}
-
-# Usage and main
-# --------------
-
-function usage {
-    echo "$0: [-h]"
-    echo "  -h, --help              Display help message"
-    echo "  -t, --tenant            Create tenants"
-    echo "  -n, --net               Create networks"
-    echo "  -v, --vm                Create vms"
-    echo "  -c, --check             Check connection"
-    echo "  -x, --delete-tenants    Delete tenants"
-    echo "  -y, --delete-nets       Delete networks"
-    echo "  -z, --delete-vms        Delete vms"
-    echo "  -T, --test              Test functions"
-}
-
-function main {
-
-    echo Description
-
-    if [ $# -eq 0 ] ; then
-        # if no args are provided, run all tests
-        all
-    else
-
-        while [ "$1" != "" ]; do
-            case $1 in
-                -h | --help )   usage
-                                exit
-                                ;;
-                -n | --net )    create_networks
-                                exit
-                                ;;
-                -v | --vm )     create_vms
-                                exit
-                                ;;
-                -t | --tenant ) create_tenants
-                                exit
-                                ;;
-                -c | --check )   check_vms
-                                exit
-                                ;;
-                -T | --test )   test_functions
-                                exit
-                                ;;
-                -x | --delete-tenants ) delete_tenants_and_users
-                                exit
-                                ;;
-                -y | --delete-nets ) delete_networks
-                                exit
-                                ;;
-                -z | --delete-vms ) shutdown_vms
-                                exit
-                                ;;
-                -a | --all )    all
-                                exit
-                                ;;
-                * )             usage
-                                exit 1
-            esac
-            shift
-        done
-    fi
-}
-
-# Kick off script
-# ---------------
-
-echo $*
-main $*
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/sahara.sh

@@ -1,43 +0,0 @@
-#!/usr/bin/env bash
-
-# **sahara.sh**
-
-# Sanity check that Sahara started if enabled
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-is_service_enabled sahara || exit 55
-
-curl http://$SERVICE_HOST:8386/ 2>/dev/null | grep -q 'Auth' || die $LINENO "Sahara API isn't functioning!"
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/sec_groups.sh

@@ -1,81 +0,0 @@
-#!/usr/bin/env bash
-
-# **sec_groups.sh**
-
-# Test security groups via the command line
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# If nova api is not enabled we exit with exitcode 55 so that
-# the exercise is skipped
-is_service_enabled n-api || exit 55
-
-
-# Testing Security Groups
-# =======================
-
-# List security groups
-nova secgroup-list
-
-# Create random name for new sec group and create secgroup of said name
-SEC_GROUP_NAME="ex-secgroup-$(openssl rand -hex 4)"
-nova secgroup-create $SEC_GROUP_NAME 'a test security group'
-
-# Add some rules to the secgroup
-RULES_TO_ADD=( 22 3389 5900 )
-
-for RULE in "${RULES_TO_ADD[@]}"; do
-    nova secgroup-add-rule $SEC_GROUP_NAME tcp $RULE $RULE 0.0.0.0/0
-done
-
-# Check to make sure rules were added
-SEC_GROUP_RULES=( $(nova secgroup-list-rules $SEC_GROUP_NAME | grep -v \- | grep -v 'Source Group' | cut -d '|' -f3 | tr -d ' ') )
-die_if_not_set $LINENO SEC_GROUP_RULES "Failure retrieving SEC_GROUP_RULES for $SEC_GROUP_NAME"
-for i in "${RULES_TO_ADD[@]}"; do
-    skip=
-    for j in "${SEC_GROUP_RULES[@]}"; do
-        [[ $i == $j ]] && { skip=1; break; }
-    done
-    [[ -n $skip ]] || exit 1
-done
-
-# Delete rules and secgroup
-for RULE in "${RULES_TO_ADD[@]}"; do
-    nova secgroup-delete-rule $SEC_GROUP_NAME tcp $RULE $RULE 0.0.0.0/0
-done
-
-# Delete secgroup
-nova secgroup-delete $SEC_GROUP_NAME || \
-    die $LINENO "Failure deleting security group $SEC_GROUP_NAME"
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/swift.sh

@@ -1,66 +0,0 @@
-#!/usr/bin/env bash
-
-# **swift.sh**
-
-# Test swift via the ``swift`` command line from ``python-swiftclient``
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# If swift is not enabled we exit with exitcode 55 which mean
-# exercise is skipped.
-is_service_enabled s-proxy || exit 55
-
-# Container name
-CONTAINER=ex-swift
-
-
-# Testing Swift
-# =============
-
-# Check if we have to swift via keystone
-swift stat || die $LINENO "Failure getting status"
-
-# We start by creating a test container
-openstack container create $CONTAINER || die $LINENO "Failure creating container $CONTAINER"
-
-# add some files into it.
-openstack object create $CONTAINER /etc/issue || die $LINENO "Failure uploading file to container $CONTAINER"
-
-# list them
-openstack object list $CONTAINER || die $LINENO "Failure listing contents of container $CONTAINER"
-
-# And we may want to delete them now that we have tested that
-# everything works.
-swift delete $CONTAINER || die $LINENO "Failure deleting container $CONTAINER"
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/volumes.sh

@@ -1,224 +0,0 @@
-#!/usr/bin/env bash
-
-# **volumes.sh**
-
-# Test cinder volumes with the ``cinder`` command from ``python-cinderclient``
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import project functions
-source $TOP_DIR/lib/cinder
-source $TOP_DIR/lib/neutron
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-# If cinder is not enabled we exit with exitcode 55 which mean
-# exercise is skipped.
-is_service_enabled cinder || exit 55
-
-# Ironic does not currently support volume attachment.
-[ "$VIRT_DRIVER" == "ironic" ] && exit 55
-
-# Instance type to create
-DEFAULT_INSTANCE_TYPE=${DEFAULT_INSTANCE_TYPE:-m1.tiny}
-
-# Boot this image, use first AMI image if unset
-DEFAULT_IMAGE_NAME=${DEFAULT_IMAGE_NAME:-ami}
-
-# Security group name
-SECGROUP=${SECGROUP:-vol_secgroup}
-
-# Instance and volume names
-VM_NAME=${VM_NAME:-ex-vol-inst}
-VOL_NAME="ex-vol-$(openssl rand -hex 4)"
-
-
-# Launching a server
-# ==================
-
-# List servers for tenant:
-nova list
-
-# Images
-# ------
-
-# List the images available
-openstack image list
-
-# Grab the id of the image to launch
-IMAGE=$(openstack image list | egrep " $DEFAULT_IMAGE_NAME " | get_field 1)
-die_if_not_set $LINENO IMAGE "Failure getting image $DEFAULT_IMAGE_NAME"
-
-# Security Groups
-# ---------------
-
-# List security groups
-nova secgroup-list
-
-if is_service_enabled n-cell; then
-    # Cells does not support security groups, so force the use of "default"
-    SECGROUP="default"
-    echo "Using the default security group because of Cells."
-else
-    # Create a secgroup
-    if ! nova secgroup-list | grep -q $SECGROUP; then
-        nova secgroup-create $SECGROUP "$SECGROUP description"
-        if ! timeout $ASSOCIATE_TIMEOUT sh -c "while ! nova secgroup-list | grep -q $SECGROUP; do sleep 1; done"; then
-            echo "Security group not created"
-            exit 1
-        fi
-    fi
-fi
-
-# Configure Security Group Rules
-if ! nova secgroup-list-rules $SECGROUP | grep -q icmp; then
-    nova secgroup-add-rule $SECGROUP icmp -1 -1 0.0.0.0/0
-fi
-if ! nova secgroup-list-rules $SECGROUP | grep -q " tcp .* 22 "; then
-    nova secgroup-add-rule $SECGROUP tcp 22 22 0.0.0.0/0
-fi
-
-# List secgroup rules
-nova secgroup-list-rules $SECGROUP
-
-# Set up instance
-# ---------------
-
-# List flavors
-nova flavor-list
-
-# Select a flavor
-INSTANCE_TYPE=$(nova flavor-list | grep $DEFAULT_INSTANCE_TYPE | get_field 1)
-if [[ -z "$INSTANCE_TYPE" ]]; then
-    # grab the first flavor in the list to launch if default doesn't exist
-    INSTANCE_TYPE=$(nova flavor-list | head -n 4 | tail -n 1 | get_field 1)
-    die_if_not_set $LINENO INSTANCE_TYPE "Failure retrieving INSTANCE_TYPE"
-fi
-
-# Clean-up from previous runs
-nova delete $VM_NAME || true
-if ! timeout $ACTIVE_TIMEOUT sh -c "while nova show $VM_NAME; do sleep 1; done"; then
-    die $LINENO "server didn't terminate!"
-fi
-
-# Boot instance
-# -------------
-
-VM_UUID=$(nova boot --flavor $INSTANCE_TYPE --image $IMAGE --security-groups=$SECGROUP $VM_NAME | grep ' id ' | get_field 2)
-die_if_not_set $LINENO VM_UUID "Failure launching $VM_NAME"
-
-# Check that the status is active within ACTIVE_TIMEOUT seconds
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! nova show $VM_UUID | grep status | grep -q ACTIVE; do sleep 1; done"; then
-    die $LINENO "server didn't become active!"
-fi
-
-# Get the instance IP
-IP=$(get_instance_ip $VM_UUID $PRIVATE_NETWORK_NAME)
-
-die_if_not_set $LINENO IP "Failure retrieving IP address"
-
-# Private IPs can be pinged in single node deployments
-ping_check "$PRIVATE_NETWORK_NAME" $IP $BOOT_TIMEOUT
-
-# Volumes
-# -------
-
-# Verify it doesn't exist
-if [[ -n $(cinder list | grep $VOL_NAME | head -1 | get_field 2) ]]; then
-    die $LINENO "Volume $VOL_NAME already exists"
-fi
-
-# Create a new volume
-start_time=$(date +%s)
-cinder create --display-name $VOL_NAME --display-description "test volume: $VOL_NAME" $DEFAULT_VOLUME_SIZE || \
-    die $LINENO "Failure creating volume $VOL_NAME"
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! cinder list | grep $VOL_NAME | grep available; do sleep 1; done"; then
-    die $LINENO "Volume $VOL_NAME not created"
-fi
-end_time=$(date +%s)
-echo "Completed cinder create in $((end_time - start_time)) seconds"
-
-# Get volume ID
-VOL_ID=$(cinder list | grep $VOL_NAME | head -1 | get_field 1)
-die_if_not_set $LINENO VOL_ID "Failure retrieving volume ID for $VOL_NAME"
-
-# Attach to server
-DEVICE=/dev/vdb
-start_time=$(date +%s)
-nova volume-attach $VM_UUID $VOL_ID $DEVICE || \
-    die $LINENO "Failure attaching volume $VOL_NAME to $VM_NAME"
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! cinder list | grep $VOL_NAME | grep in-use; do sleep 1; done"; then
-    die $LINENO "Volume $VOL_NAME not attached to $VM_NAME"
-fi
-end_time=$(date +%s)
-echo "Completed volume-attach in $((end_time - start_time)) seconds"
-
-VOL_ATTACH=$(cinder list | grep $VOL_NAME | head -1 | get_field -1)
-die_if_not_set $LINENO VOL_ATTACH "Failure retrieving $VOL_NAME status"
-if [[ "$VOL_ATTACH" != $VM_UUID ]]; then
-    die $LINENO "Volume not attached to correct instance"
-fi
-
-# Clean up
-# --------
-
-# Detach volume
-start_time=$(date +%s)
-nova volume-detach $VM_UUID $VOL_ID || die $LINENO "Failure detaching volume $VOL_NAME from $VM_NAME"
-if ! timeout $ACTIVE_TIMEOUT sh -c "while ! cinder list | grep $VOL_NAME | grep available; do sleep 1; done"; then
-    die $LINENO "Volume $VOL_NAME not detached from $VM_NAME"
-fi
-end_time=$(date +%s)
-echo "Completed volume-detach in $((end_time - start_time)) seconds"
-
-# Delete volume
-start_time=$(date +%s)
-cinder delete $VOL_ID || die $LINENO "Failure deleting volume $VOL_NAME"
-if ! timeout $ACTIVE_TIMEOUT sh -c "while cinder list | grep $VOL_NAME; do sleep 1; done"; then
-    die $LINENO "Volume $VOL_NAME not deleted"
-fi
-end_time=$(date +%s)
-echo "Completed cinder delete in $((end_time - start_time)) seconds"
-
-# Delete instance
-nova delete $VM_UUID || die $LINENO "Failure deleting instance $VM_NAME"
-if ! timeout $TERMINATE_TIMEOUT sh -c "while nova list | grep -q $VM_UUID; do sleep 1; done"; then
-    die $LINENO "Server $VM_NAME not deleted"
-fi
-
-if [[ $SECGROUP = "default" ]] ; then
-    echo "Skipping deleting default security group"
-else
-    # Delete secgroup
-    nova secgroup-delete $SECGROUP || die $LINENO "Failure deleting security group $SECGROUP"
-fi
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

exercises/zaqar.sh

@@ -1,43 +0,0 @@
-#!/usr/bin/env bash
-
-# **zaqar.sh**
-
-# Sanity check that Zaqar started if enabled
-
-echo "*********************************************************************"
-echo "Begin DevStack Exercise: $0"
-echo "*********************************************************************"
-
-# This script exits on an error so that errors don't compound and you see
-# only the first error that occurred.
-set -o errexit
-
-# Print the commands being run so that we can see the command that triggers
-# an error.  It is also useful for following allowing as the install occurs.
-set -o xtrace
-
-
-# Settings
-# ========
-
-# Keep track of the current directory
-EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
-TOP_DIR=$(cd $EXERCISE_DIR/..; pwd)
-
-# Import common functions
-source $TOP_DIR/functions
-
-# Import configuration
-source $TOP_DIR/openrc
-
-# Import exercise configuration
-source $TOP_DIR/exerciserc
-
-is_service_enabled zaqar-server || exit 55
-
-curl http://$SERVICE_HOST:8888/v1/ 2>/dev/null | grep -q 'queue_name' || die $LINENO "Zaqar API not functioning!"
-
-set +o xtrace
-echo "*********************************************************************"
-echo "SUCCESS: End DevStack Exercise: $0"
-echo "*********************************************************************"

extras.d/40-dib.sh

@@ -1,27 +0,0 @@
-# dib.sh - Devstack extras script to install diskimage-builder
-
-if is_service_enabled dib; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source
-        source $TOP_DIR/lib/dib
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        echo_summary "Installing diskimage-builder"
-        install_dib
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        # no-op
-        :
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        # no-op
-        :
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        # no-op
-        :
-    fi
-
-    if [[ "$1" == "clean" ]]; then
-        # no-op
-        :
-    fi
-fi

extras.d/50-ironic.sh

@@ -1,43 +0,0 @@
-# ironic.sh - Devstack extras script to install ironic
-
-if is_service_enabled ir-api ir-cond; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source
-        source $TOP_DIR/lib/ironic
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        echo_summary "Installing Ironic"
-        install_ironic
-        install_ironicclient
-        cleanup_ironic
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        echo_summary "Configuring Ironic"
-        configure_ironic
-
-        if is_service_enabled key; then
-            create_ironic_accounts
-        fi
-
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        # Initialize ironic
-        init_ironic
-
-        # Start the ironic API and ironic taskmgr components
-        echo_summary "Starting Ironic"
-        start_ironic
-
-        if [[ "$IRONIC_BAREMETAL_BASIC_OPS" = "True" ]]; then
-            prepare_baremetal_basic_ops
-        fi
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        stop_ironic
-        if [[ "$IRONIC_BAREMETAL_BASIC_OPS" = "True" ]]; then
-            cleanup_baremetal_basic_ops
-        fi
-    fi
-
-    if [[ "$1" == "clean" ]]; then
-        cleanup_ironic
-    fi
-fi

extras.d/60-ceph.sh

@@ -1,75 +0,0 @@
-# ceph.sh - DevStack extras script to install Ceph
-
-if is_service_enabled ceph; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source
-        source $TOP_DIR/lib/ceph
-    elif [[ "$1" == "stack" && "$2" == "pre-install" ]]; then
-        echo_summary "Installing Ceph"
-        check_os_support_ceph
-        if [ "$REMOTE_CEPH" = "False" ]; then
-            install_ceph
-            echo_summary "Configuring Ceph"
-            configure_ceph
-            # NOTE (leseb): Do everything here because we need to have Ceph started before the main
-            # OpenStack components. Ceph OSD must start here otherwise we can't upload any images.
-            echo_summary "Initializing Ceph"
-            init_ceph
-            start_ceph
-        else
-            install_ceph_remote
-        fi
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        if is_service_enabled glance; then
-            echo_summary "Configuring Glance for Ceph"
-            configure_ceph_glance
-        fi
-        if is_service_enabled nova; then
-            echo_summary "Configuring Nova for Ceph"
-            configure_ceph_nova
-        fi
-        if is_service_enabled cinder; then
-            echo_summary "Configuring Cinder for Ceph"
-            configure_ceph_cinder
-        fi
-        if is_service_enabled cinder || is_service_enabled nova; then
-            # NOTE (leseb): the part below is a requirement to attach Ceph block devices
-            echo_summary "Configuring libvirt secret"
-            import_libvirt_secret_ceph
-        fi
-
-        if [ "$REMOTE_CEPH" = "False" ]; then
-            if is_service_enabled glance; then
-                echo_summary "Configuring Glance for Ceph"
-                configure_ceph_embedded_glance
-            fi
-            if is_service_enabled nova; then
-                echo_summary "Configuring Nova for Ceph"
-                configure_ceph_embedded_nova
-            fi
-            if is_service_enabled cinder; then
-                echo_summary "Configuring Cinder for Ceph"
-                configure_ceph_embedded_cinder
-            fi
-        fi
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        if [ "$REMOTE_CEPH" = "True" ]; then
-            cleanup_ceph_remote
-        else
-            cleanup_ceph_embedded
-            stop_ceph
-        fi
-        cleanup_ceph_general
-    fi
-
-    if [[ "$1" == "clean" ]]; then
-        if [ "$REMOTE_CEPH" = "True" ]; then
-            cleanup_ceph_remote
-        else
-            cleanup_ceph_embedded
-        fi
-        cleanup_ceph_general
-    fi
-fi

extras.d/70-gantt.sh

@@ -1,31 +0,0 @@
-# gantt.sh - Devstack extras script to install Gantt
-
-if is_service_enabled n-sch; then
-    disable_service gantt
-fi
-
-if is_service_enabled gantt; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source
-        source $TOP_DIR/lib/gantt
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        echo_summary "Installing Gantt"
-        install_gantt
-        cleanup_gantt
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        echo_summary "Configuring Gantt"
-        configure_gantt
-
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        # Initialize gantt
-        init_gantt
-
-        # Start gantt
-        echo_summary "Starting Gantt"
-        start_gantt
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        stop_gantt
-    fi
-fi

extras.d/70-sahara.sh

@@ -1,29 +0,0 @@
-# sahara.sh - DevStack extras script to install Sahara
-
-if is_service_enabled sahara; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source
-        source $TOP_DIR/lib/sahara
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        echo_summary "Installing sahara"
-        install_sahara
-        install_python_saharaclient
-        cleanup_sahara
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        echo_summary "Configuring sahara"
-        configure_sahara
-        create_sahara_accounts
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        echo_summary "Initializing sahara"
-        sahara_register_images
-        start_sahara
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        stop_sahara
-    fi
-
-    if [[ "$1" == "clean" ]]; then
-        cleanup_sahara
-    fi
-fi

extras.d/70-trove.sh

@@ -1,32 +0,0 @@
-# trove.sh - Devstack extras script to install Trove
-
-if is_service_enabled trove; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source
-        source $TOP_DIR/lib/trove
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        echo_summary "Installing Trove"
-        install_trove
-        install_troveclient
-        cleanup_trove
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        echo_summary "Configuring Trove"
-        configure_trove
-
-        if is_service_enabled key; then
-            create_trove_accounts
-        fi
-
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        # Initialize trove
-        init_trove
-
-        # Start the trove API and trove taskmgr components
-        echo_summary "Starting Trove"
-        start_trove
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        stop_trove
-    fi
-fi

extras.d/70-tuskar.sh

@@ -1,205 +0,0 @@
-# Install and start the **Tuskar** service
-#
-# To enable, add the following to your localrc
-#
-# enable_service tuskar
-# enable_service tuskar-api
-
-
-if is_service_enabled tuskar; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source, do nothing as functions sourced
-        # are below rather than in lib/tuskar
-        echo_summary "source extras tuskar"
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        echo_summary "Installing Tuskar"
-        install_tuskarclient
-        install_tuskar
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        echo_summary "Configuring Tuskar"
-        configure_tuskar
-        configure_tuskarclient
-
-        if is_service_enabled key; then
-            create_tuskar_accounts
-        fi
-
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        echo_summary "Initializing Tuskar"
-        init_tuskar
-        start_tuskar
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        stop_tuskar
-    fi
-fi
-
-# library code (equivalent to lib/tuskar)
-# ---------
-# - install_tuskarclient
-# - install_tuskar
-# - configure_tuskarclient
-# - configure_tuskar
-# - init_tuskar
-# - start_tuskar
-# - stop_tuskar
-# - cleanup_tuskar
-
-# Save trace setting
-XTRACE=$(set +o | grep xtrace)
-set +o xtrace
-
-
-# Defaults
-# --------
-
-# tuskar repos
-TUSKAR_REPO=${TUSKAR_REPO:-${GIT_BASE}/openstack/tuskar.git}
-TUSKAR_BRANCH=${TUSKAR_BRANCH:-master}
-
-TUSKARCLIENT_REPO=${TUSKARCLIENT_REPO:-${GIT_BASE}/openstack/python-tuskarclient.git}
-TUSKARCLIENT_BRANCH=${TUSKARCLIENT_BRANCH:-master}
-
-# set up default directories
-TUSKAR_DIR=$DEST/tuskar
-TUSKARCLIENT_DIR=$DEST/python-tuskarclient
-TUSKAR_AUTH_CACHE_DIR=${TUSKAR_AUTH_CACHE_DIR:-/var/cache/tuskar}
-TUSKAR_STANDALONE=$(trueorfalse False TUSKAR_STANDALONE)
-TUSKAR_CONF_DIR=/etc/tuskar
-TUSKAR_CONF=$TUSKAR_CONF_DIR/tuskar.conf
-TUSKAR_API_HOST=${TUSKAR_API_HOST:-$HOST_IP}
-TUSKAR_API_PORT=${TUSKAR_API_PORT:-8585}
-
-# Tell Tempest this project is present
-TEMPEST_SERVICES+=,tuskar
-
-# Functions
-# ---------
-
-# Test if any Tuskar services are enabled
-# is_tuskar_enabled
-function is_tuskar_enabled {
-    [[ ,${ENABLED_SERVICES} =~ ,"tuskar-" ]] && return 0
-    return 1
-}
-
-# cleanup_tuskar() - Remove residual data files, anything left over from previous
-# runs that a clean run would need to clean up
-function cleanup_tuskar {
-    sudo rm -rf $TUSKAR_AUTH_CACHE_DIR
-}
-
-# configure_tuskar() - Set config files, create data dirs, etc
-function configure_tuskar {
-    setup_develop $TUSKAR_DIR
-
-    if [[ ! -d $TUSKAR_CONF_DIR ]]; then
-        sudo mkdir -p $TUSKAR_CONF_DIR
-    fi
-    sudo chown $STACK_USER $TUSKAR_CONF_DIR
-    # remove old config files
-    rm -f $TUSKAR_CONF_DIR/tuskar-*.conf
-
-    TUSKAR_POLICY_FILE=$TUSKAR_CONF_DIR/policy.json
-
-    cp $TUSKAR_DIR/etc/tuskar/policy.json $TUSKAR_POLICY_FILE
-    cp $TUSKAR_DIR/etc/tuskar/tuskar.conf.sample $TUSKAR_CONF
-
-    # common options
-    iniset $TUSKAR_CONF database connection `database_connection_url tuskar`
-
-    # logging
-    iniset $TUSKAR_CONF DEFAULT debug $ENABLE_DEBUG_LOG_LEVEL
-    iniset $TUSKAR_CONF DEFAULT use_syslog $SYSLOG
-    if [ "$LOG_COLOR" == "True" ] && [ "$SYSLOG" == "False" ]; then
-        # Add color to logging output
-        setup_colorized_logging $TUSKAR_CONF DEFAULT tenant user
-    fi
-
-    configure_auth_token_middleware $TUSKAR_CONF tuskar $TUSKAR_AUTH_CACHE_DIR
-
-    if is_ssl_enabled_service "key"; then
-        iniset $TUSKAR_CONF clients_keystone ca_file $SSL_BUNDLE_FILE
-    fi
-
-    iniset $TUSKAR_CONF tuskar_api bind_port $TUSKAR_API_PORT
-
-}
-
-# init_tuskar() - Initialize database
-function init_tuskar {
-
-    # (re)create tuskar database
-    recreate_database tuskar
-
-    tuskar-dbsync --config-file $TUSKAR_CONF
-    create_tuskar_cache_dir
-}
-
-# create_tuskar_cache_dir() - Part of the init_tuskar() process
-function create_tuskar_cache_dir {
-    # Create cache dirs
-    sudo mkdir -p $TUSKAR_AUTH_CACHE_DIR
-    sudo chown $STACK_USER $TUSKAR_AUTH_CACHE_DIR
-}
-
-# install_tuskarclient() - Collect source and prepare
-function install_tuskarclient {
-    git_clone $TUSKARCLIENT_REPO $TUSKARCLIENT_DIR $TUSKARCLIENT_BRANCH
-    setup_develop $TUSKARCLIENT_DIR
-}
-
-# configure_tuskarclient() - Set config files, create data dirs, etc
-function configure_tuskarclient {
-    setup_develop $TUSKARCLIENT_DIR
-}
-
-# install_tuskar() - Collect source and prepare
-function install_tuskar {
-    git_clone $TUSKAR_REPO $TUSKAR_DIR $TUSKAR_BRANCH
-}
-
-# start_tuskar() - Start running processes, including screen
-function start_tuskar {
-    run_process tuskar-api "tuskar-api --config-file=$TUSKAR_CONF"
-}
-
-# stop_tuskar() - Stop running processes
-function stop_tuskar {
-    # Kill the screen windows
-    local serv
-    for serv in tuskar-api; do
-        stop_process $serv
-    done
-}
-
-# create_tuskar_accounts() - Set up common required tuskar accounts
-function create_tuskar_accounts {
-    # migrated from files/keystone_data.sh
-    local service_tenant=$(openstack project list | awk "/ $SERVICE_TENANT_NAME / { print \$2 }")
-    local admin_role=$(openstack role list | awk "/ admin / { print \$2 }")
-
-    local tuskar_user=$(get_or_create_user "tuskar" \
-        "$SERVICE_PASSWORD" $service_tenant)
-    get_or_add_user_role $admin_role $tuskar_user $service_tenant
-
-    if [[ "$KEYSTONE_CATALOG_BACKEND" = 'sql' ]]; then
-
-        local tuskar_service=$(get_or_create_service "tuskar" \
-                "management" "Tuskar Management Service")
-        get_or_create_endpoint $tuskar_service \
-            "$REGION_NAME" \
-            "$SERVICE_PROTOCOL://$TUSKAR_API_HOST:$TUSKAR_API_PORT" \
-            "$SERVICE_PROTOCOL://$TUSKAR_API_HOST:$TUSKAR_API_PORT" \
-            "$SERVICE_PROTOCOL://$TUSKAR_API_HOST:$TUSKAR_API_PORT"
-    fi
-}
-
-# Restore xtrace
-$XTRACE
-
-# Tell emacs to use shell-script-mode
-## Local variables:
-## mode: shell-script
-## End:

extras.d/70-zaqar.sh

@@ -1,29 +0,0 @@
-# zaqar.sh - Devstack extras script to install Zaqar
-
-if is_service_enabled zaqar-server; then
-    if [[ "$1" == "source" ]]; then
-        # Initial source
-        source $TOP_DIR/lib/zaqar
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        echo_summary "Installing Zaqar"
-        install_zaqarclient
-        install_zaqar
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        echo_summary "Configuring Zaqar"
-        configure_zaqar
-        configure_zaqarclient
-
-        if is_service_enabled key; then
-            create_zaqar_accounts
-        fi
-
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        echo_summary "Initializing Zaqar"
-        init_zaqar
-        start_zaqar
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        stop_zaqar
-    fi
-fi

extras.d/80-opendaylight.sh

@@ -1,76 +0,0 @@
-# opendaylight.sh - DevStack extras script
-
-if is_service_enabled odl-server odl-compute; then
-    # Initial source
-    [[ "$1" == "source" ]] && source $TOP_DIR/lib/opendaylight
-fi
-
-if is_service_enabled odl-server; then
-    if [[ "$1" == "source" ]]; then
-        # no-op
-        :
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        install_opendaylight
-        configure_opendaylight
-        init_opendaylight
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        configure_ml2_odl
-        # This has to start before Neutron
-        start_opendaylight
-    elif [[ "$1" == "stack" && "$2" == "post-extra" ]]; then
-        # no-op
-        :
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        stop_opendaylight
-        cleanup_opendaylight
-    fi
-
-    if [[ "$1" == "clean" ]]; then
-        # no-op
-        :
-    fi
-fi
-
-if is_service_enabled odl-compute; then
-    if [[ "$1" == "source" ]]; then
-        # no-op
-        :
-    elif [[ "$1" == "stack" && "$2" == "install" ]]; then
-        install_opendaylight-compute
-    elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
-        if is_service_enabled nova; then
-            create_nova_conf_neutron
-        fi
-    elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        echo_summary "Initializing OpenDaylight"
-        ODL_LOCAL_IP=${ODL_LOCAL_IP:-$HOST_IP}
-        ODL_MGR_PORT=${ODL_MGR_PORT:-6640}
-        read ovstbl <<< $(sudo ovs-vsctl get Open_vSwitch . _uuid)
-        sudo ovs-vsctl set-manager tcp:$ODL_MGR_IP:$ODL_MGR_PORT
-        if [[ -n "$ODL_PROVIDER_MAPPINGS" ]] && [[ "$ENABLE_TENANT_VLANS" == "True" ]]; then
-            sudo ovs-vsctl set Open_vSwitch $ovstbl \
-                other_config:provider_mappings=$ODL_PROVIDER_MAPPINGS
-        fi
-        sudo ovs-vsctl set Open_vSwitch $ovstbl other_config:local_ip=$ODL_LOCAL_IP
-    elif [[ "$1" == "stack" && "$2" == "post-extra" ]]; then
-        # no-op
-        :
-    fi
-
-    if [[ "$1" == "unstack" ]]; then
-        sudo ovs-vsctl del-manager
-        BRIDGES=$(sudo ovs-vsctl list-br)
-        for bridge in $BRIDGES ; do
-            sudo ovs-vsctl del-controller $bridge
-        done
-
-        stop_opendaylight-compute
-    fi
-
-    if [[ "$1" == "clean" ]]; then
-        # no-op
-        :
-    fi
-fi

extras.d/80-tempest.sh

@@ -6,17 +6,22 @@ if is_service_enabled tempest; then
         source $TOP_DIR/lib/tempest
     elif [[ "$1" == "stack" && "$2" == "install" ]]; then
         echo_summary "Installing Tempest"
-        install_tempest
+        async_runfunc install_tempest
     elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
         # Tempest config must come after layer 2 services are running
-        create_tempest_accounts
+        :
     elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
-        echo_summary "Initializing Tempest"
-        configure_tempest
-        init_tempest
+        # Tempest config must come after all other plugins are run
+        :
     elif [[ "$1" == "stack" && "$2" == "post-extra" ]]; then
         # local.conf Tempest option overrides
         :
+    elif [[ "$1" == "stack" && "$2" == "test-config" ]]; then
+        async_wait install_tempest
+        echo_summary "Initializing Tempest"
+        configure_tempest
+        echo_summary "Installing Tempest Plugins"
+        install_tempest_plugins
     fi
 
     if [[ "$1" == "unstack" ]]; then
@@ -29,4 +34,3 @@ if is_service_enabled tempest; then
         :
     fi
 fi
-

extras.d/README.md

@@ -14,10 +14,13 @@ The scripts are sourced at the beginning of each script that calls them. The
 entire `stack.sh` variable space is available.  The scripts are
 sourced with one or more arguments, the first of which defines the hook phase:
 
-    source | stack | unstack | clean
+    override_defaults | source | stack | unstack | clean
 
-    source: always called first in any of the scripts, used to set the
-        initial defaults in a lib/* script or similar
+    override_defaults: always called first in any of the scripts, used to
+        override defaults (if need be) that are otherwise set in lib/* scripts
+
+    source: called by stack.sh. Used to set the initial defaults in a lib/*
+        script or similar
 
     stack: called by stack.sh.  There are four possible values for
         the second arg to distinguish the phase stack.sh is in:

files/apache-ceilometer.template

@@ -1,15 +0,0 @@
-Listen %PORT%
-
-<VirtualHost *:%PORT%>
-    WSGIDaemonProcess ceilometer-api processes=2 threads=10 user=%USER% display-name=%{GROUP}
-    WSGIProcessGroup ceilometer-api
-    WSGIScriptAlias / %WSGIAPP%
-    WSGIApplicationGroup %{GLOBAL}
-    <IfVersion >= 2.4>
-        ErrorLogFormat "%{cu}t %M"
-    </IfVersion>
-    ErrorLog /var/log/%APACHE_NAME%/ceilometer.log
-    CustomLog /var/log/%APACHE_NAME%/ceilometer_access.log combined
-</VirtualHost>
-
-WSGISocketPrefix /var/run/%APACHE_NAME%

files/apache-cinder-api.template

@@ -0,0 +1,26 @@
+Listen %PUBLICPORT%
+
+<VirtualHost *:%PUBLICPORT%>
+    WSGIDaemonProcess osapi_volume processes=%APIWORKERS% threads=1 user=%USER% display-name=%{GROUP} %VIRTUALENV%
+    WSGIProcessGroup osapi_volume
+    WSGIScriptAlias / %CINDER_BIN_DIR%/cinder-wsgi
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+    <IfVersion >= 2.4>
+      ErrorLogFormat "%{cu}t %M"
+    </IfVersion>
+    ErrorLog /var/log/%APACHE_NAME%/c-api.log
+    %SSLENGINE%
+    %SSLCERTFILE%
+    %SSLKEYFILE%
+
+    <Directory %CINDER_BIN_DIR%>
+        <IfVersion >= 2.4>
+            Require all granted
+        </IfVersion>
+        <IfVersion < 2.4>
+            Order allow,deny
+            Allow from all
+        </IfVersion>
+    </Directory>
+</VirtualHost>

files/apache-dib-pip-repo.template

@@ -1,15 +0,0 @@
-Listen %DIB_PIP_REPO_PORT%
-
-<VirtualHost *:%DIB_PIP_REPO_PORT%>
-    DocumentRoot %DIB_PIP_REPO%
-    <Directory %DIB_PIP_REPO%>
-        DirectoryIndex index.html
-        Require all granted
-        Order allow,deny
-        allow from all
-    </Directory>
-
-    ErrorLog /var/log/%APACHE_NAME%/dib_pip_repo_error.log
-    LogLevel warn
-    CustomLog /var/log/%APACHE_NAME%/dib_pip_repo_access.log combined
-</VirtualHost>

files/apache-horizon.template

@@ -1,5 +1,5 @@
 <VirtualHost *:80>
-    WSGIScriptAlias / %HORIZON_DIR%/openstack_dashboard/wsgi/django.wsgi
+    WSGIScriptAlias %WEBROOT% %HORIZON_DIR%/openstack_dashboard/wsgi.py
     WSGIDaemonProcess horizon user=%USER% group=%GROUP% processes=3 threads=10 home=%HORIZON_DIR% display-name=%{GROUP}
     WSGIApplicationGroup %{GLOBAL}
 
@@ -8,7 +8,10 @@
     WSGIProcessGroup horizon
 
     DocumentRoot %HORIZON_DIR%/.blackhole/
-    Alias /media %HORIZON_DIR%/openstack_dashboard/static
+    Alias %WEBROOT%/media %HORIZON_DIR%/openstack_dashboard/static
+    Alias %WEBROOT%/static %HORIZON_DIR%/static
+
+    RedirectMatch "^/$" "%WEBROOT%/"
 
     <Directory />
         Options FollowSymLinks
@@ -28,10 +31,13 @@
             Require all granted
         </IfVersion>
     </Directory>
-
+    <IfVersion >= 2.4>
+      ErrorLogFormat "%{cu}t %M"
+    </IfVersion>
     ErrorLog /var/log/%APACHE_NAME%/horizon_error.log
     LogLevel warn
     CustomLog /var/log/%APACHE_NAME%/horizon_access.log combined
 </VirtualHost>
 
+%WSGIPYTHONHOME%
 WSGISocketPrefix /var/run/%APACHE_NAME%

files/apache-ironic.template

@@ -1,12 +0,0 @@
-Listen %PUBLICPORT%
-
-<VirtualHost *:%PUBLICPORT%>
-    DocumentRoot "%HTTPROOT%"
-    <Directory "%HTTPROOT%">
-        Options Indexes FollowSymLinks
-        AllowOverride None
-        Order allow,deny
-        Allow from all
-        Require all granted
-    </Directory>
-</VirtualHost>

files/apache-keystone.template

@@ -1,34 +1,37 @@
 Listen %PUBLICPORT%
-Listen %ADMINPORT%
+LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %D(us)" keystone_combined
+
+<Directory %KEYSTONE_BIN%>
+    Require all granted
+</Directory>
 
 <VirtualHost *:%PUBLICPORT%>
-    WSGIDaemonProcess keystone-public processes=5 threads=1 user=%USER% display-name=%{GROUP}
+    WSGIDaemonProcess keystone-public processes=3 threads=1 user=%USER% display-name=%{GROUP} %VIRTUALENV%
     WSGIProcessGroup keystone-public
-    WSGIScriptAlias / %PUBLICWSGI%
+    WSGIScriptAlias / %KEYSTONE_BIN%/keystone-wsgi-public
     WSGIApplicationGroup %{GLOBAL}
     WSGIPassAuthorization On
-    <IfVersion >= 2.4>
-      ErrorLogFormat "%{cu}t %M"
-    </IfVersion>
+    ErrorLogFormat "%M"
     ErrorLog /var/log/%APACHE_NAME%/keystone.log
-    CustomLog /var/log/%APACHE_NAME%/keystone_access.log combined
+    CustomLog /var/log/%APACHE_NAME%/keystone_access.log keystone_combined
     %SSLENGINE%
     %SSLCERTFILE%
     %SSLKEYFILE%
 </VirtualHost>
 
-<VirtualHost *:%ADMINPORT%>
-    WSGIDaemonProcess keystone-admin processes=5 threads=1 user=%USER% display-name=%{GROUP}
-    WSGIProcessGroup keystone-admin
-    WSGIScriptAlias / %ADMINWSGI%
+%SSLLISTEN%<VirtualHost *:443>
+%SSLLISTEN%    %SSLENGINE%
+%SSLLISTEN%    %SSLCERTFILE%
+%SSLLISTEN%    %SSLKEYFILE%
+%SSLLISTEN%    SSLProtocol -all +TLSv1.3 +TLSv1.2
+%SSLLISTEN%</VirtualHost>
+
+Alias /identity %KEYSTONE_BIN%/keystone-wsgi-public
+<Location /identity>
+    SetHandler wsgi-script
+    Options +ExecCGI
+
+    WSGIProcessGroup keystone-public
     WSGIApplicationGroup %{GLOBAL}
     WSGIPassAuthorization On
-    <IfVersion >= 2.4>
-      ErrorLogFormat "%{cu}t %M"
-    </IfVersion>
-    ErrorLog /var/log/%APACHE_NAME%/keystone.log
-    CustomLog /var/log/%APACHE_NAME%/keystone_access.log combined
-    %SSLENGINE%
-    %SSLCERTFILE%
-    %SSLKEYFILE%
-</VirtualHost>
+</Location>

files/apache-neutron.template

@@ -0,0 +1,37 @@
+Listen %PUBLICPORT%
+LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %D(us)" neutron_combined
+
+<Directory %NEUTRON_BIN%>
+    Require all granted
+</Directory>
+
+<VirtualHost *:%PUBLICPORT%>
+    WSGIDaemonProcess neutron-server processes=%APIWORKERS% threads=1 user=%USER% display-name=%{GROUP} %VIRTUALENV%
+    WSGIProcessGroup neutron-server
+    WSGIScriptAlias / %NEUTRON_BIN%/neutron-api
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+    ErrorLogFormat "%M"
+    ErrorLog /var/log/%APACHE_NAME%/neutron.log
+    CustomLog /var/log/%APACHE_NAME%/neutron_access.log neutron_combined
+    %SSLENGINE%
+    %SSLCERTFILE%
+    %SSLKEYFILE%
+</VirtualHost>
+
+
+%SSLLISTEN%<VirtualHost *:443>
+%SSLLISTEN%    %SSLENGINE%
+%SSLLISTEN%    %SSLCERTFILE%
+%SSLLISTEN%    %SSLKEYFILE%
+%SSLLISTEN%    SSLProtocol -all +TLSv1.3 +TLSv1.2
+%SSLLISTEN%</VirtualHost>
+
+Alias /networking %NEUTRON_BIN%/neutron-api
+<Location /networking>
+    SetHandler wsgi-script
+    Options +ExecCGI
+    WSGIProcessGroup neutron-server
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+</Location>

files/apache-nova-api.template

@@ -0,0 +1,25 @@
+Listen %PUBLICPORT%
+
+<VirtualHost *:%PUBLICPORT%>
+    WSGIDaemonProcess nova-api processes=%APIWORKERS% threads=1 user=%USER% display-name=%{GROUP} %VIRTUALENV%
+    WSGIProcessGroup nova-api
+    WSGIScriptAlias / %PUBLICWSGI%
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+    <IfVersion >= 2.4>
+      ErrorLogFormat "%M"
+    </IfVersion>
+    ErrorLog /var/log/%APACHE_NAME%/nova-api.log
+    %SSLENGINE%
+    %SSLCERTFILE%
+    %SSLKEYFILE%
+</VirtualHost>
+
+Alias /compute %PUBLICWSGI%
+<Location /compute>
+    SetHandler wsgi-script
+    Options +ExecCGI
+    WSGIProcessGroup nova-api
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+</Location>

files/apache-nova-metadata.template

@@ -0,0 +1,25 @@
+Listen %PUBLICPORT%
+
+<VirtualHost *:%PUBLICPORT%>
+    WSGIDaemonProcess nova-metadata processes=%APIWORKERS% threads=1 user=%USER% display-name=%{GROUP} %VIRTUALENV%
+    WSGIProcessGroup nova-metadata
+    WSGIScriptAlias / %PUBLICWSGI%
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+    <IfVersion >= 2.4>
+      ErrorLogFormat "%M"
+    </IfVersion>
+    ErrorLog /var/log/%APACHE_NAME%/nova-metadata.log
+    %SSLENGINE%
+    %SSLCERTFILE%
+    %SSLKEYFILE%
+</VirtualHost>
+
+Alias /metadata %PUBLICWSGI%
+<Location /metadata>
+    SetHandler wsgi-script
+    Options +ExecCGI
+    WSGIProcessGroup nova-metadata
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+</Location>

files/apache-placement-api.template

@@ -0,0 +1,27 @@
+# NOTE(sbauza): This virtualhost is only here because some directives can
+# only be set by a virtualhost or server context, so that's why the port is not bound.
+# TODO(sbauza): Find a better way to identify a free port that is not corresponding to an existing
+# vhost.
+<VirtualHost *:8780>
+    WSGIDaemonProcess placement-api processes=%APIWORKERS% threads=1 user=%USER% display-name=%{GROUP} %VIRTUALENV%
+    WSGIProcessGroup placement-api
+    WSGIScriptAlias / %PUBLICWSGI%
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+    <IfVersion >= 2.4>
+      ErrorLogFormat "%M"
+    </IfVersion>
+    ErrorLog /var/log/%APACHE_NAME%/placement-api.log
+    %SSLENGINE%
+    %SSLCERTFILE%
+    %SSLKEYFILE%
+</VirtualHost>
+
+Alias /placement %PUBLICWSGI%
+<Location /placement>
+    SetHandler wsgi-script
+    Options +ExecCGI
+    WSGIProcessGroup placement-api
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIPassAuthorization On
+</Location>

files/apts

@@ -1 +0,0 @@
-debs/

files/debs/ceilometer-collector

@@ -1,6 +0,0 @@
-python-pymongo #NOPRIME
-mongodb-server #NOPRIME
-libnspr4-dev
-pkg-config
-libxml2-dev
-libxslt-dev

files/debs/cinder

@@ -1,6 +1,4 @@
-tgt
 lvm2
 qemu-utils
-libpq-dev
-open-iscsi
-open-iscsi-utils # Deprecated since quantal dist:precise
+tgt # NOPRIME
+thin-provisioning-tools

files/debs/dstat

@@ -1 +1,2 @@
-dstat
+dstat # dist:bionic
+pcp

files/debs/general

@@ -1,29 +1,39 @@
-bridge-utils
-pylint
-screen
-unzip
-wget
-psmisc
+apache2
+apache2-dev
+bc
+bsdmainutils
+curl
+default-jre-headless  # NOPRIME
+g++
+gawk
 gcc
+gettext  # used for compiling message catalogs
 git
-graphviz # testonly - docs
+graphviz # needed for docs
+iputils-ping
+libapache2-mod-proxy-uwsgi
+libffi-dev # for pyOpenSSL
+libjpeg-dev # Pillow 3.0.0
+libpcre3-dev # for python-pcre
+libpq-dev  # psycopg2
+libssl-dev # for pyOpenSSL
+libsystemd-dev # for systemd-python
+libxml2-dev  # lxml
+libxslt1-dev  # lxml
+libyaml-dev
 lsof # useful when debugging
 openssh-server
 openssl
-python-virtualenv
-python-unittest2
-iputils-ping
-wget
-curl
-tcpdump
-euca2ools # only for testing client
+pkg-config
+psmisc
+python3-dev
+python3-pip
+python3-systemd
+python3-venv
 tar
-python-cmd2 # dist:precise
-python-dev
-python-mock # testonly
-python2.7
-bc
-libyaml-dev
-libffi-dev
-libssl-dev # for pyOpenSSL
-gettext  # used for compiling message catalogs
+tcpdump
+unzip
+uuid-runtime
+wget
+wget
+zlib1g-dev

files/debs/glance

@@ -1,13 +0,0 @@
-libmysqlclient-dev  # testonly
-libpq-dev           # testonly
-libssl-dev          # testonly
-libxml2-dev
-libxslt1-dev        # testonly
-python-eventlet
-python-routes
-python-greenlet
-python-sqlalchemy
-python-pastedeploy
-python-xattr
-python-iso8601
-zlib1g-dev           # testonly

files/debs/heat

@@ -1 +0,0 @@
-gettext # dist:trusty

files/debs/horizon

@@ -1,19 +1,2 @@
 apache2  # NOPRIME
 libapache2-mod-wsgi  # NOPRIME
-python-beautifulsoup
-python-dateutil
-python-paste
-python-pastedeploy
-python-anyjson
-python-routes
-python-xattr
-python-sqlalchemy
-python-webob
-pylint
-python-eventlet
-python-nose
-python-mox
-python-coverage
-python-cherrypy3 # why?
-python-migrate
-libpcre3-dev  # pyScss

files/debs/ironic

@@ -1,18 +0,0 @@
-docker.io
-ipmitool
-iptables
-ipxe
-libguestfs0
-libvirt-bin
-openssh-client
-openvswitch-switch
-openvswitch-datapath-dkms
-python-libguestfs
-python-libvirt
-qemu
-qemu-kvm
-qemu-utils
-sgabios
-syslinux
-tftpd-hpa
-xinetd