openstack/magnum
Code Issues Proposed changes

Add documentation for a developer quickstart guide

Browse Source 
Change-Id: Idda4b0a39076e5f473cbb4182cdcba202267ab69
This commit is contained in:
Steven Dake 2014-12-10 12:56:31 -07:00
parent 5405375608
commit 5b8036ea6f
3 changed files with 270 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
README.rst
View File

@ -8,7 +8,7 @@ new Openstack project for containers.
* Documentation: http://docs.openstack.org/developer/magnum
* Source: http://git.openstack.org/cgit/stackforge/magnum
* Bugs: http://bugs.launchpad.net/magnum
* ReST Client: http://github.com/stackforge/python-magnumclient
* ReST Client: http://git.openstack.org/cgit/stackforge/python-magnumclient
Architecture
------------
@ -21,23 +21,21 @@ There are five different types of objects in the Magnum system:
* Service: A port to Pod mapping
* Container: A docker container
Three binaries work together to compose the Magnum system. The first binary
Two binaries work together to compose the Magnum system. The first binary
accessed by the python-magnumclient code is the magnum-api ReST server. The
ReST server may run as one process or multiple processes. When a ReST request
is sent to the client API, the request is sent via AMQP to the magnum-backend
process.
process. The ReST server is horizontally scalable. AT this time, the backend
is limited to one process, but we intend to add horizontal scalability to the
backend as well.
The magnum-backend process runs on each machine where a docker server is
running or where a k8s minion is located. The backend processor contacts the
appropriate backend (for the container object, docker, for the server & pod
objects, k8s). The backend then executes the operation requested and sends the
results to the third binary.
The magnum-backend process runs on a controller machine and connects to a
kubernetes or docker ReST API endpoint. The kubernetes and docker ReST API
endpoints are managed by the bay object.
The third binary, magnum-conductor, reads and writes the database with
information related to the object operated upon. The conductor then returns
the new object back up the call stack, where it may be used to provide
information to the client or used for processing the operation. There is only
one magnum-conductor process running.
When service or pod objects are created, Kubernetes is directly contacted via
the k8s ReST API. When container objects are acted upon, the docker ReST API
is directly contacted.
Features
--------
@ -46,80 +44,7 @@ Features
* Integration with Keystone for multi-tenant security.
* Integraiton with Neutron for k8s multi-tenancy network security.
Installation
------------
* Configure Keystone::
$ source openrc admin admin
$ keystone user-create --name=magnum \
--pass=<secure-magnum-password> \
--email=magnum@example.com
$ keystone service-create --name=container \
--type=container \
--description="Magnum Container Service"
$ keystone endpoint-create --service=container \
--publicurl=http://127.0.0.1:9511/v1 \
--internalurl=http://127.0.0.1:9511/v1 \
--adminurl=http://127.0.0.1:9511/v1
* Install Magnum::
$ git clone http://github.com/stackforge/magnum
$ cd magnum
$ sudo python ./setup.py install
$ cd ..
* Install Magnum's Python Client::
$ git clone http://github.com/stackforge/python-magnumclient
$ cd python-magnumclient
$ sudo python ./setup.py install
$ cd ..
Run
---
* Start magnum-api::
$ magnum-api &
* Start magnum-conductor::
$ magnum-conductor &
* Start magnum-backend (should be started where a docker server or kubernetes api server is running)::
$ magnum-backend &
Access Magnum via ReST API
--------------------------
* Note the magnum ReST API is not yet plumbed *
* select a subcommand::
bay-create
bay-delete
bay-list
bay-show
container-create
container-delete
container-execute
container-list
container-logs
container-pause
container-reboot
container-show
container-start
container-stop
container-unpause
pod-create
pod-delete
pod-list
pod-show
service-create
service-delete
service-list
service-show
* Run the operation::
$ magnum bay-list
Installation and Usage
----------------------
For installation and usage, please read the developer installation guide
located at doc/source/dev/dev-quickstart.rst.

253
doc/source/dev/dev-quickstart.rst Normal file
View File

@ -0,0 +1,253 @@
.. _dev-quickstart:
=====================
Developer Quick-Start
=====================
This is a quick walkthrough to get you started developing code for Magnum.
This assumes you are already familiar with submitting code reviews to
an OpenStack project.
.. seealso::
https://wiki.openstack.org/wiki/GerritWorkflow
Install prerequisites::
# Ubuntu/Debian:
sudo apt-get install python-dev libssl-dev python-pip libmysqlclient-dev libxml2-dev libxslt-dev libpq-dev git git-review libffi-dev gettext python-tox
# Fedora/RHEL:
sudo yum install python-devel openssl-devel python-pip mysql-devel libxml2-devel libxslt-devel postgresql-devel git git-review libffi-devel gettext ipmitool
# openSUSE/SLE 12:
sudo zypper install git git-review libffi-devel libmysqlclient-devel libopenssl-devel libxml2-devel libxslt-devel postgresql-devel python-devel python-flake8 python-nose python-pip python-setuptools-git python-testrepository python-tox python-virtualenv gettext-runtime
sudo easy_install nose
sudo pip install virtualenv setuptools-git flake8 tox testrepository
If using RHEL and yum reports “No package python-pip available” and “No
package git-review available”, use the EPEL software repository. Instructions
can be found at `<http://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_.
You may need to explicitly upgrade virtualenv if you've installed the one
from your OS distribution and it is too old (tox will complain). You can
upgrade it individually, if you need to::
sudo pip install -U virtualenv
Ironic source code should be pulled directly from git::
# from your home or source directory
cd ~
git clone https://git.openstack.org/stackforge/magnum
cd magnum
Set up a local environment for development and testing should be done with tox::
# create a virtualenv for development
tox -evenv -- echo 'done'
Activate the virtual environment whenever you want to work in it.
All further commands in this section should be run with the venv active::
source .tox/venv/bin/activate
All unit tests should be run using tox. To run Magnum's entire test suite::
# run all tests (unit and pep8)
tox
To run a specific test, use a positional argument for the unit tests::
# run a specific test for Python 2.7
tox -epy27 -- test_conductor
You may pass options to the test programs using positional arguments::
# run all the Python 2.7 unit tests (in parallel!)
tox -epy27 -- --parallel
To run only the pep8/flake8 syntax and style checks::
tox -epep8
When you're done, deactivate the virtualenv::
deactivate
======================================
Exercising the Services Using DevStack
======================================
DevStack does not yet have Magnum support. It is, however, necessary to
develop Magnum from a devstack environment at the present time. Magnum depends
on Ironic to create and schedule bare metal machines. These instructions show
how to use Ironic in a virtualized environment so only one machine is needed
to develop.
Clone DevStack::
cd ~
git clone https://github.com/openstack-dev/devstack.git devstack
Create devstack/localrc with minimal settings required to enable Ironic.
Magnum depends on Ironic for bare metal provisioning of an micro-OS containing
Kubernetes and Docker. For Ironic, we recommend using the pxe+ssh driver::
cd devstack
cat >localrc <<END
# Credentials
ADMIN_PASSWORD=password
DATABASE_PASSWORD=password
RABBIT_PASSWORD=password
SERVICE_PASSWORD=password
SERVICE_TOKEN=password
# Enable Ironic API and Ironic Conductor
enable_service ironic
enable_service ir-api
enable_service ir-cond
# Enable Neutron which is required by Ironic and disable nova-network.
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
# Create 5 virtual machines to pose as Ironic's baremetal nodes.
IRONIC_VM_COUNT=5
IRONIC_VM_SSH_PORT=22
IRONIC_BAREMETAL_BASIC_OPS=True
# The parameters below represent the minimum possible values to create
# functional nodes.
IRONIC_VM_SPECS_RAM=1024
IRONIC_VM_SPECS_DISK=10
# Size of the ephemeral partition in GB. Use 0 for no ephemeral partition.
IRONIC_VM_EPHEMERAL_DISK=0
VIRT_DRIVER=ironic
# By default, DevStack creates a 10.0.0.0/24 network for instances.
# If this overlaps with the hosts network, you may adjust with the
# following.
NETWORK_GATEWAY=10.1.0.1
FIXED_RANGE=10.1.0.0/24
FIXED_NETWORK_SIZE=256
# Log all output to files
LOGFILE=$HOME/devstack.log
SCREEN_LOGDIR=$HOME/logs
IRONIC_VM_LOG_DIR=$HOME/ironic-bm-logs
END
At this time, Magnum has only been tested with the Fedora Atomic micro-OS.
Magnum will likely work with other micro-OS platforms, but each one requires
individual support.
The next step is to store the Fedora Atomic micro-OS in glance. The steps for
making the Atomic images for Ironic are a bit detailed, but fortunately one
of the core Magnum developers has written some simple scripts to automate
the process::
cd ~
git clone http://github.com/sdake/fedora-atomic-to-liveos-pxe
cd fedora-atomic-to-liveos-pxe
wget http://dl.fedoraproject.org/pub/alt/stage/21_RC5/Cloud/Images/x86_64/Fedora-Cloud-Atomic-20141203-21.x86_64.qcow2
./convert.sh
./register-with-glance.sh
Next, create a database in MySQL for Magnum::
mysql -h 127.0.0.1 -u root -ppassword mysql <<EOF
CREATE DATABASE IF NOT EXISTS magnum DEFAULT CHARACTER SET utf8;
GRANT ALL PRIVILEGES ON magnum.* TO
'root'@'%' IDENTIFIED BY 'password'
EOF
Next, clone and install magnum::
cd ~
git clone https://github.com/stackforge/magnum
cd magnum
sudo pip install -e .
Next, clone and install the client::
cd ~
git clone https://github.com/stackforge/python-magnumclient
cd python-magnumclient
sudo pip install -e .
Next, configure the database for use with Magnum::
magnum-db-manage upgrade
Next configure the database connection for Magnum::
sed -i "s/#connection=.*/connection=mysql:\/\/root@localhost\/magnum/" etc/magnum/magnum.conf.sample
Finally, configure the keystone endpoint::
keystone service-create --name=container \
--type=container \
--description="Magnum Container Service"
keystone endpoint-create --service=container \
--publicurl=http://127.0.0.1:9511/v1 \
--internalurl=http://127.0.0.1:9511/v1 \
--adminurl=http://127.0.0.1:9511/v1
Next start the API service::
magnum-api
Next start the ackend service in a new window::
magnum-backend
Create a new shell, and source the devstack openrc script::
. ~/repos/devstack/openrc admin admin
To get started, list the available commands and resources::
magnum help
A bay can be created with 3 nodes. One node will be configured as a master
Kubernetes node, while the remaining two nodes will be configured as minions::
magnum bay-create --name=cats --type=baremetal --image_id=<IMAGE_ID_FROM_GLANCE_REGISTRATION_SCRIPT> --node_count=3
The existing bays can be listed as follows::
magnum bay-list
If you make some code changes and want to test their effects,
just restart either magnum-api or magnum-backend. the -e option to
pip install will link to the location from where the source code
was installed.
================================
Building developer documentation
================================
If you would like to build the documentation locally, eg. to test your
documentation changes before uploading them for review, run these
commands to build the documentation set::
# activate your development virtualenv
source .tox/venv/bin/activate
# build the docs
tox -egendocs
Now use your browser to open the top-level index.html located at::
magnum/doc/build/html/index.html

3
doc/source/index.rst
View File

@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to magnum's documentation!
Welcome to Magnum's documentation!
========================================================
Contents:
@ -12,6 +12,7 @@ Contents:
:maxdepth: 2
readme
quickstart
installation
usage
contributing