Merge "Add a doc describing a quick live environment"

This commit is contained in:
Zuul 2018-11-27 10:22:08 +00:00 committed by Gerrit Code Review
commit f776e49022
3 changed files with 201 additions and 2 deletions

View File

@ -366,8 +366,10 @@ examples. Gabbi can provide a useful way of doing test driven development of a
new handler: create a YAML file that describes the desired URLs and behavior
and write the code to make it pass.
It is also possible to use gabbi against a running placement service, for
example in devstack. See `gabbi-run`_ to get started.
It's also possible to use gabbi against a running placement service, for
example in devstack. See `gabbi-run`_ to get started. If you don't want to
go to the trouble of using devstack, but do want a live server see
:doc:`quick-dev`.
Database Schema Changes
=======================

View File

@ -0,0 +1,196 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
===========================
Quick Placement Development
===========================
.. note:: This is one of many ways to achieve a simple *live* development
enviroment for the placement service. This isn't meant to be the
best way, or the only way. Its purpose is more to demonstrate the
steps involved, so that people can learn from those steps and choose
to assemble them in whatever ways work best for them.
This content was originally written in a `blog post
<https://anticdent.org/quick-placement-development.html>`_, which
perhaps explains its folksy tone.
Here are some instructions on how to spin up the placement wsgi script with
uwsgi and a stubbed out ``placement.conf``, in case you want to see what
happens. The idea here is that you want to experiment with the current
placement code, using a live database, but you're not concerned with other
services, don't want to deal with devstack, but need a level of interaction
with the code and process that something like `placedock
<https://github.com/cdent/placedock>`_ can't provide.
*As ever, even all of the above has lots of assumptions about experience and
context. This document assumes you are someone who either is an OpenStack (and
probably placement) developer, or would like to be one.*
To make this go you need a unix-like OS, with a python3 dev environment, and
git and mysql (or postgresql) installed. We'll be doing this work from within a
virtualenv, built from the ``tox.ini`` in the placement code.
Get The Code
============
The placement code lives at
https://git.openstack.org/cgit/openstack/placement . We want to clone that::
git clone git://git.openstack.org/openstack/placement
cd placement
Setup The Database
==================
We need to 1) create the database, 2) create a virtualenv to have the command,
3) use it to create the tables.
The database can have whatever name you like. Whatever you choose, use it
throughout this process. We choose ``placement``. You may need a user and
password to talk to your database, setting that up is out of scope for this
document::
mysql -uroot -psecret -e "DROP DATABASE IF EXISTS placement;"
mysql -uroot -psecret -e "CREATE DATABASE placement CHARACTER SET utf8;"
You may also need to set permissions::
mysql -uroot -psecret \
-e "GRANT ALL PRIVILEGES ON placement.* TO 'root'@'%' identified by 'secret';"
Create a bare minimum placement.conf in the ``/etc/placement``
directory (which you may need to create)::
[placement_database]
connection = mysql+pymysql://root:secret@127.0.0.1/placement?charset=utf8
.. note:: You may choose the location of the configuration file on the command
line when using the ``placement-manage`` command.
Make the ``placement-manage`` command available by updating a virtualenv::
tox -epy36 --notest
Run the command to create the tables::
.tox/py36/bin/placement-manage db sync
You can confirm the tables are there with ``mysqlshow placement``
Run The Service
===============
Now we want to run the service. We need to update ``placement.conf`` so it will
produce debugging output and use the ``noauth`` strategy for authentication (so
we don't also have to run Keystone). Make ``placement.conf`` look like this
(adjusting for your database settings)::
[DEFAULT]
debug = True
[placement_database]
connection = mysql+pymysql://root:secret@127.0.0.1/placement?charset=utf8
[api]
auth_strategy = noauth2
We need to install the uwsgi package into the virtualenv::
.tox/py36/bin/pip install uwsgi
And then use uwsgi to run the service. Start it with::
.tox/py36/bin/uwsgi --http :8000 --wsgi-file .tox/py36/bin/placement-api --processes 2 --threads 10
.. note:: Adjust ``processes`` and ``threads`` as required. If you do not
provide these arguments the server will be a single process and
thus perform poorly.
If that worked you'll see lots of debug output and ``spawned uWSGI worker``.
Test that things are working from another terminal with curl::
curl -v http://localhost:8000/
Get a list of resource providers with (the ``x-auth-token`` header is
required, ``openstack-api-version`` is optional but makes sure we are getting
the latest functionality)::
curl -H 'x-auth-token: admin' \
-H 'openstack-api-version: placement latest' \
http://localhost:8000/resource_providers
The result ought to look something like this::
{"resource_providers": []}
If it doesn't then something went wrong with the above and there should be more
information in the terminal where ``uwsgi`` is running.
From here you can experiment with creating resource providers and related
placement features. If you change the placement code, ``ctrl-c`` to kill the
uwsgi process and start it up again. For testing, you might enjoy
`placecat <https://github.com/cdent/placecat>`_.
Here's all of the above as single script. As stated above this is for
illustrative purposes. You should make your own::
#!/bin/bash
set -xe
# Change these as required
CONF_DIR=/etc/placement
DB_DRIVER=mysql+pymysql # we assume mysql throughout, feel free to change
DB_NAME=placement
DB_USER=root
DB_PASS=secret
REPO=git://git.openstack.org/openstack/placement
# Create a directory for configuration to live.
[[ -d $CONF_DIR ]] || (sudo mkdir $CONF_DIR && sudo chown $USER $CONF_DIR)
# Establish database. Some of this may need sudo powers. Don't be shy
# about changing the script.
mysql -u$DB_USER -p$DB_PASS -e "DROP DATABASE IF EXISTS $DB_NAME;"
mysql -u$DB_USER -p$DB_PASS -e "CREATE DATABASE $DB_NAME CHARACTER SET utf8;"
mysql -u$DB_USER -p$DB_PASS -e "GRANT ALL PRIVILEGES ON $DB_NAME.* TO '$DB_USER'@'%' IDENTIFIED BY '$DB_PASS';"
# clone the right code
git clone $REPO
cd placement
# establish virtenv
tox -epy36 --notest
# write placement.conf
cat<<EOF > $CONF_DIR/placement.conf
[DEFAULT]
debug = True
[placement_database]
connection = $DB_DRIVER://${DB_USER}:${DB_PASS}@127.0.0.1/${DB_NAME}?charset=utf8
[api]
auth_strategy = noauth2
EOF
# Create database tables
.tox/py36/bin/placement-manage db sync
# install uwsgi
.tox/py36/bin/pip install uwsgi
# run uwsgi
.tox/py36/bin/uwsgi --http :8000 --wsgi-file .tox/py36/bin/placement-api --processes 2 --threads 10

View File

@ -247,6 +247,7 @@ This history of placement microversions may be found in
configuration/index
contributor/index
contributor/api-ref-guideline
contributor/quick-dev
install/controller-install-obs
install/controller-install-rdo
install/controller-install-ubuntu