From db7cd407f544a3852428a02853a6d52955985cb3 Mon Sep 17 00:00:00 2001
From: Hongbin Lu <hongbin.lu@huawei.com>
Date: Fri, 9 Sep 2016 15:04:38 -0500
Subject: [PATCH] Document how to use zun devstack plugin

* Add content about how to install Zun with devstack plugin
* Move the content about how to manually add Zun to devstack to a
  separated document.

Change-Id: I5737c18fa9b26e43936aa8959e48e5c14d06ef3c
---
 README.rst                         |   1 +
 doc/source/dev/manual-devstack.rst | 162 +++++++++++++++++++++++++++++
 doc/source/dev/quickstart.rst      | 119 +--------------------
 3 files changed, 165 insertions(+), 117 deletions(-)
 create mode 100644 doc/source/dev/manual-devstack.rst

diff --git a/README.rst b/README.rst
index eadba7eb2..627432216 100644
--- a/README.rst
+++ b/README.rst
@@ -9,6 +9,7 @@ Please fill here a long description which must be at least 3 lines wrapped on
 Note that this is a hard requirement.
 
 * Free software: Apache license
+* Get Started: https://github.com/openstack/zun/blob/master/doc/source/dev/quickstart.rst
 * Documentation: http://docs.openstack.org/developer/zun
 * Source: http://git.openstack.org/cgit/openstack/zun
 * Bugs: http://bugs.launchpad.net/zun
diff --git a/doc/source/dev/manual-devstack.rst b/doc/source/dev/manual-devstack.rst
new file mode 100644
index 000000000..32e3ad33e
--- /dev/null
+++ b/doc/source/dev/manual-devstack.rst
@@ -0,0 +1,162 @@
+.. _manual-install:
+
+===============================
+Manually Adding Zun to DevStack
+===============================
+If you are getting started with zun it is recommended you follow the
+:ref:`quickstart` to get up and running with zun. This guide covers
+a more in-depth process to setup zun with devstack.
+
+This session has only been tested on Ubuntu 14.04 (Trusty).
+We recommend users to select one of it if it is possible.
+
+Clone devstack::
+
+    # Create a root directory for devstack if needed
+    sudo mkdir -p /opt/stack
+    sudo chown $USER /opt/stack
+
+    git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack
+
+We will run devstack with minimal local.conf settings required to enable
+required OpenStack services::
+
+    cat > /opt/stack/devstack/local.conf << END
+    [[local|localrc]]
+    HOST_IP=$(ip addr | grep 'state UP' -A2 | tail -n1 | awk '{print $2}' | cut -f1  -d'/')
+    DATABASE_PASSWORD=password
+    RABBIT_PASSWORD=password
+    SERVICE_TOKEN=password
+    SERVICE_PASSWORD=password
+    ADMIN_PASSWORD=password
+    END
+
+More devstack configuration information can be found at
+http://docs.openstack.org/developer/devstack/configuration.html
+
+More neutron configuration information can be found at
+http://docs.openstack.org/developer/devstack/guides/neutron.html
+
+Run devstack::
+
+    cd /opt/stack/devstack
+    ./stack.sh
+
+Prepare your session to be able to use the various openstack clients including
+nova, neutron, and glance. Create a new shell, and source the devstack openrc
+script::
+
+    source /opt/stack/devstack/openrc admin admin
+
+Create a database in MySQL for zun::
+
+    mysql -h 127.0.0.1 -u root -ppassword mysql <<EOF
+    CREATE DATABASE IF NOT EXISTS zun DEFAULT CHARACTER SET utf8;
+    GRANT ALL PRIVILEGES ON zun.* TO
+        'root'@'%' IDENTIFIED BY 'password'
+    EOF
+
+Create the service credentials for zun::
+
+    openstack user create --password password zun
+    openstack role add --project service --user zun admin
+
+Clone and install zun::
+
+    cd ~
+    git clone https://git.openstack.org/openstack/zun
+    cd zun
+    sudo pip install -e .
+
+Configure zun::
+
+    # create the zun conf directory
+    ZUN_CONF_DIR=/etc/zun
+    ZUN_CONF=$ZUN_CONF_DIR/zun.conf
+    sudo mkdir -p $ZUN_CONF_DIR
+    sudo chown -R ${USER} $ZUN_CONF_DIR
+
+    # generate sample config file and modify it as necessary
+    sudo chown -R ${USER} .
+    tox -egenconfig
+    sudo cp etc/zun/zun.conf.sample $ZUN_CONF_DIR/zun.conf
+    sudo cp etc/zun/api-paste.ini $ZUN_CONF_DIR/api-paste.ini
+
+    # copy policy.json
+    sudo cp etc/zun/policy.json $ZUN_CONF_DIR/policy.json
+
+    # enable debugging output
+    sudo sed -i "s/#debug\s*=.*/debug=true/" $ZUN_CONF
+
+    # set RabbitMQ userid
+    sudo sed -i "s/#rabbit_userid\s*=.*/rabbit_userid=stackrabbit/" \
+             $ZUN_CONF
+
+    # set RabbitMQ password
+    sudo sed -i "s/#rabbit_password\s*=.*/rabbit_password=password/" \
+             $ZUN_CONF
+
+    # set SQLAlchemy connection string to connect to MySQL
+    sudo sed -i "s/#connection\s*=.*/connection=mysql:\/\/root:password@localhost\/zun/" \
+             $ZUN_CONF
+
+    # set keystone_auth
+    source /opt/stack/devstack/openrc admin admin
+    iniset $ZUN_CONF keystone_auth auth_type password
+    iniset $ZUN_CONF keystone_auth username zun
+    iniset $ZUN_CONF keystone_auth password password
+    iniset $ZUN_CONF keystone_auth project_name service
+    iniset $ZUN_CONF keystone_auth project_domain_id default
+    iniset $ZUN_CONF keystone_auth user_domain_id default
+    iniset $ZUN_CONF keystone_auth auth_url ${OS_AUTH_URL/v2.0/v3}
+
+    # NOTE: keystone_authtoken section is deprecated and will be removed.
+    iniset $ZUN_CONF keystone_authtoken username zun
+    iniset $ZUN_CONF keystone_authtoken password password
+    iniset $ZUN_CONF keystone_authtoken project_name service
+    iniset $ZUN_CONF keystone_authtoken auth_url ${OS_AUTH_URL/v2.0/v3}
+    iniset $ZUN_CONF keystone_authtoken auth_version v3
+    iniset $ZUN_CONF keystone_authtoken auth_type password
+    iniset $ZUN_CONF keystone_authtoken user_domain_id default
+    iniset $ZUN_CONF keystone_authtoken project_domain_id default
+
+Clone and install the zun client::
+
+    cd ~
+    git clone https://git.openstack.org/openstack/python-zunclient
+    cd python-zunclient
+    sudo pip install -e .
+
+Install docker::
+
+    curl -fsSL https://get.docker.com/ | sudo sh
+    sudo usermod -a -G docker $(whoami)
+
+Configure the database for use with zun. Please note that DB migration
+does not work for SQLite backend. The SQLite database does not
+have any support for the ALTER statement needed by relational schema
+based migration tools. Hence DB Migration will not work for SQLite
+backend::
+
+    zun-db-manage upgrade
+
+Configure the keystone endpoint::
+
+    openstack service create --name=zun \
+                              --description="Zun Container Service" \
+                              container
+    openstack endpoint create --publicurl http://127.0.0.1:9512/v1 \
+                              --adminurl http://127.0.0.1:9512/v1 \
+                              --internalurl http://127.0.0.1:9512/v1 \
+                              --region=RegionOne \
+                              container
+
+Start the API service in a new screen::
+
+    sg docker zun-api
+
+Start the compute service in a new screen::
+
+    sg docker zun-compute
+
+Zun should now be up and running!
diff --git a/doc/source/dev/quickstart.rst b/doc/source/dev/quickstart.rst
index 1297044c2..654fdb641 100644
--- a/doc/source/dev/quickstart.rst
+++ b/doc/source/dev/quickstart.rst
@@ -81,17 +81,15 @@ required OpenStack services::
 
     cat > /opt/stack/devstack/local.conf << END
     [[local|localrc]]
+    HOST_IP=$(ip addr | grep 'state UP' -A2 | tail -n1 | awk '{print $2}' | cut -f1  -d'/')
     DATABASE_PASSWORD=password
     RABBIT_PASSWORD=password
     SERVICE_TOKEN=password
     SERVICE_PASSWORD=password
     ADMIN_PASSWORD=password
-    # zun requires the following to be set correctly
-    PUBLIC_INTERFACE=eth1
+    enable_plugin zun https://git.openstack.org/openstack/zun
     END
 
-**NOTE:** Update PUBLIC_INTERFACE as appropriate for your system.
-
 More devstack configuration information can be found at
 http://docs.openstack.org/developer/devstack/configuration.html
 
@@ -109,119 +107,6 @@ script::
 
     source /opt/stack/devstack/openrc admin admin
 
-Create a database in MySQL for zun::
-
-    mysql -h 127.0.0.1 -u root -ppassword mysql <<EOF
-    CREATE DATABASE IF NOT EXISTS zun DEFAULT CHARACTER SET utf8;
-    GRANT ALL PRIVILEGES ON zun.* TO
-        'root'@'%' IDENTIFIED BY 'password'
-    EOF
-
-Create the service credentials for zun::
-
-    openstack user create --password password zun
-    openstack role add --project service --user zun admin
-
-Clone and install zun::
-
-    cd ~
-    git clone https://git.openstack.org/openstack/zun
-    cd zun
-    sudo pip install -e .
-
-Configure zun::
-
-    # create the zun conf directory
-    ZUN_CONF_DIR=/etc/zun
-    ZUN_CONF=$ZUN_CONF_DIR/zun.conf
-    sudo mkdir -p $ZUN_CONF_DIR
-    sudo chown -R ${USER} $ZUN_CONF_DIR
-
-    # generate sample config file and modify it as necessary
-    sudo chown -R ${USER} .
-    tox -egenconfig
-    sudo cp etc/zun/zun.conf.sample $ZUN_CONF_DIR/zun.conf
-    sudo cp etc/zun/api-paste.ini $ZUN_CONF_DIR/api-paste.ini
-
-    # copy policy.json
-    sudo cp etc/zun/policy.json $ZUN_CONF_DIR/policy.json
-
-    # enable debugging output
-    sudo sed -i "s/#debug\s*=.*/debug=true/" $ZUN_CONF
-
-    # set RabbitMQ userid
-    sudo sed -i "s/#rabbit_userid\s*=.*/rabbit_userid=stackrabbit/" \
-             $ZUN_CONF
-
-    # set RabbitMQ password
-    sudo sed -i "s/#rabbit_password\s*=.*/rabbit_password=password/" \
-             $ZUN_CONF
-
-    # set SQLAlchemy connection string to connect to MySQL
-    sudo sed -i "s/#connection\s*=.*/connection=mysql:\/\/root:password@localhost\/zun/" \
-             $ZUN_CONF
-
-    # set keystone_auth
-    source /opt/stack/devstack/openrc admin admin
-    iniset $ZUN_CONF keystone_auth auth_type password
-    iniset $ZUN_CONF keystone_auth username zun
-    iniset $ZUN_CONF keystone_auth password password
-    iniset $ZUN_CONF keystone_auth project_name service
-    iniset $ZUN_CONF keystone_auth project_domain_id default
-    iniset $ZUN_CONF keystone_auth user_domain_id default
-    iniset $ZUN_CONF keystone_auth auth_url ${OS_AUTH_URL/v2.0/v3}
-
-    # NOTE: keystone_authtoken section is deprecated and will be removed.
-    iniset $ZUN_CONF keystone_authtoken username zun
-    iniset $ZUN_CONF keystone_authtoken password password
-    iniset $ZUN_CONF keystone_authtoken project_name service
-    iniset $ZUN_CONF keystone_authtoken auth_url ${OS_AUTH_URL/v2.0/v3}
-    iniset $ZUN_CONF keystone_authtoken auth_version v3
-    iniset $ZUN_CONF keystone_authtoken auth_type password
-    iniset $ZUN_CONF keystone_authtoken user_domain_id default
-    iniset $ZUN_CONF keystone_authtoken project_domain_id default
-
-Clone and install the zun client::
-
-    cd ~
-    git clone https://git.openstack.org/openstack/python-zunclient
-    cd python-zunclient
-    sudo pip install -e .
-
-Install docker::
-
-    curl -fsSL https://get.docker.com/ | sudo sh
-    sudo usermod -a -G docker $(whoami)
-
-Configure the database for use with zun. Please note that DB migration
-does not work for SQLite backend. The SQLite database does not
-have any support for the ALTER statement needed by relational schema
-based migration tools. Hence DB Migration will not work for SQLite
-backend::
-
-    zun-db-manage upgrade
-
-Configure the keystone endpoint::
-
-    openstack service create --name=zun \
-                              --description="Zun Container Service" \
-                              container
-    openstack endpoint create --publicurl http://127.0.0.1:9512/v1 \
-                              --adminurl http://127.0.0.1:9512/v1 \
-                              --internalurl http://127.0.0.1:9512/v1 \
-                              --region=RegionOne \
-                              container
-
-Start the API service in a new screen::
-
-    sg docker zun-api
-
-Start the compute service in a new screen::
-
-    sg docker zun-compute
-
-Zun should now be up and running!
-
 Using the service
 =================