394 lines
13 KiB
ReStructuredText
394 lines
13 KiB
ReStructuredText
.. _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 update
|
|
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
|
|
|
|
# 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
|
|
|
|
Magnum 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 -- python -V
|
|
|
|
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 Nova, Heat, and Neutron to create and schedule virtual machines to simulate
|
|
bare-metal. For milestone #2 we intend to introduce support for Ironic
|
|
deployment of baremetal nodes.
|
|
|
|
This session has only been tested on Ubuntu 14.04 (Trusty) and Fedora 21.
|
|
We recommend users to select one of them if it is possible.
|
|
|
|
NB: Magnum depends on a command line tool in kubernetes called kubectl
|
|
to execute its operations with Kubernetes. We are addressing this in milestone
|
|
#2 by implementing a native ReST client for Kubernetes. In the meantime, the
|
|
required action is to install kubectl manually.
|
|
|
|
Install binary distribution of kubectl distributed by Google::
|
|
|
|
wget https://github.com/GoogleCloudPlatform/kubernetes/releases/download/v0.7.0/kubernetes.tar.gz
|
|
tar -xzvf kubernetes.tar.gz
|
|
sudo cp -a kubernetes/platforms/linux/amd64/kubectl /usr/bin/kubectl
|
|
|
|
Clone DevStack::
|
|
|
|
cd ~
|
|
git clone https://github.com/openstack-dev/devstack.git devstack
|
|
|
|
Create devstack/localrc with minimal settings required to enable Heat
|
|
and Neutron, refer to http://docs.openstack.org/developer/devstack/guides/neutron.html
|
|
for more detailed neutron configuration.::
|
|
|
|
cd devstack
|
|
cat >localrc <<END
|
|
# Modify to your environment
|
|
FLOATING_RANGE=192.168.1.224/27
|
|
PUBLIC_NETWORK_GATEWAY=192.168.1.225
|
|
PUBLIC_INTERFACE=em1
|
|
|
|
# Credentials
|
|
ADMIN_PASSWORD=password
|
|
DATABASE_PASSWORD=password
|
|
RABBIT_PASSWORD=password
|
|
SERVICE_PASSWORD=password
|
|
SERVICE_TOKEN=password
|
|
|
|
enable_service rabbit
|
|
|
|
# Enable Neutron which is required by Magnum 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
|
|
|
|
FIXED_RANGE=10.0.0.0/24
|
|
|
|
Q_USE_SECGROUP=True
|
|
ENABLE_TENANT_VLANS=True
|
|
TENANT_VLAN_RANGE=
|
|
|
|
PHYSICAL_NETWORK=public
|
|
OVS_PHYSICAL_BRIDGE=br-ex
|
|
|
|
# Log all output to files
|
|
LOGFILE=$HOME/devstack.log
|
|
SCREEN_LOGDIR=$HOME/logs
|
|
|
|
END
|
|
./stack.sh
|
|
|
|
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 in the heat template.
|
|
|
|
The next step is to store the Fedora Atomic micro-OS in glance. The steps for
|
|
updating Fedora Atomic images are a bit detailed. Fortunately one of the core
|
|
developers has made Atomic images avaliable via the web:
|
|
|
|
If using the m-1 tag or tarball, please use the documentation shipped with the
|
|
milestone as the current master instructions are slightly incompatible.
|
|
|
|
Create a new shell, and source the devstack openrc script::
|
|
|
|
source ~/devstack/openrc admin admin
|
|
|
|
cd ~
|
|
wget https://fedorapeople.org/groups/heat/kolla/fedora-21-atomic.qcow2
|
|
glance image-create --name fedora21-atomic \
|
|
--is-public True \
|
|
--disk-format qcow2 \
|
|
--container-format bare < fedora-21-atomic.qcow2
|
|
test -f ~/.ssh/id_rsa.pub || ssh-keygen
|
|
nova keypair-add --pub-key ~/.ssh/id_rsa.pub testkey
|
|
|
|
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 .
|
|
sudo mkdir -p /etc/magnum/templates
|
|
sudo cp -r etc/magnum/templates/heat-kubernetes \
|
|
/etc/magnum/templates/
|
|
|
|
Next configure Magnum::
|
|
|
|
# copy sample config and modify it as necessary
|
|
sudo cp etc/magnum/magnum.conf.sample /etc/magnum/magnum.conf
|
|
|
|
# enable debugging output
|
|
sudo sed -i "s/#debug\s*=.*/debug=true/" /etc/magnum/magnum.conf
|
|
|
|
# enable more verbose output
|
|
sudo sed -i "s/#verbose\s*=.*/verbose=true/" /etc/magnum/magnum.conf
|
|
|
|
# set RabbitMQ userid
|
|
sudo sed -i "s/#rabbit_userid\s*=.*/rabbit_userid=stackrabbit/" /etc/magnum/magnum.conf
|
|
|
|
# set RabbitMQ password
|
|
sudo sed -i "s/#rabbit_password\s*=.*/rabbit_password=password/" /etc/magnum/magnum.conf
|
|
|
|
# set SQLAlchemy connection string to connect to MySQL
|
|
sudo sed -i "s/#connection\s*=.*/connection=mysql:\/\/root:password@localhost\/magnum/" /etc/magnum/magnum.conf
|
|
|
|
# set Keystone account username
|
|
sudo sed -i "s/#admin_user\s*=.*/admin_user=admin/" /etc/magnum/magnum.conf
|
|
|
|
# set Keystone account password
|
|
sudo sed -i "s/#admin_password\s*=.*/admin_password=password/" /etc/magnum/magnum.conf
|
|
|
|
# set admin Identity API endpoint
|
|
sudo sed -i "s/#identity_uri\s*=.*/identity_uri=http:\/\/127.0.0.1:35357/" /etc/magnum/magnum.conf
|
|
|
|
# set public Identity API endpoint
|
|
sudo sed -i "s/#auth_uri\s*=.*/auth_uri=http:\/\/127.0.0.1:5000\/v2.0/" /etc/magnum/magnum.conf
|
|
|
|
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
|
|
|
|
Finally, configure the keystone endpoint::
|
|
|
|
keystone service-create --name=magnum \
|
|
--type=container \
|
|
--description="Magnum Container Service"
|
|
keystone endpoint-create --service=magnum \
|
|
--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 conductor service in a new window::
|
|
|
|
magnum-conductor
|
|
|
|
To get started, list the available commands and resources::
|
|
|
|
magnum help
|
|
|
|
First create a baymodel, which is similar in nature to a flavor. It informs
|
|
Magnum in which way to construct a bay.::
|
|
|
|
NIC_ID=$(neutron net-show public | awk '/ id /{print $4}')
|
|
magnum baymodel-create --name testbaymodel --image-id fedora21-atomic \
|
|
--keypair-id testkey \
|
|
--external-network-id $NIC_ID \
|
|
--dns-nameserver 8.8.8.8 --flavor-id m1.small
|
|
|
|
Next create a bay. Use the baymodel UUID as a template for bay creation.
|
|
This bay will result in one master kubernetes node and three minion nodes.::
|
|
|
|
BAYMODEL_UUID=$(magnum baymodel-list | awk '/ testbaymodel /{print $2}')
|
|
magnum bay-create --name testbay --baymodel-id $BAYMODEL_UUID --node-count 2
|
|
|
|
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-conductor. the -e option to
|
|
pip install will link to the location from where the source code
|
|
was installed.
|
|
|
|
Magnum uses heat to orchestrate. Heat reports CREATE_COMPLETE when it is
|
|
done orchestrating. Do not create containers, pods, services, or replication
|
|
controllers before Heat finishes orchestrating the bay. They will likely
|
|
not be created, causing Magnum to become confused.
|
|
|
|
See blueprint:
|
|
https://blueprints.launchpad.net/magnum/+spec/magnum-bay-status
|
|
|
|
|
|
heat stack-list
|
|
|
|
+--------------------------------------+------------+-----------------+----------------------+
|
|
| id | stack_name | stack_status | creation_time |
|
|
+--------------------------------------+------------+-----------------+----------------------+
|
|
| 8eb10314-e6b8-400f-8d4c-c0f5762eecea | testbay | CREATE_COMPLETE | 2015-01-17T17:06:27Z |
|
|
+--------------------------------------+------------+-----------------+----------------------+
|
|
|
|
|
|
Kubernetes provides a number of examples you can use to check that things
|
|
are working. Here's how to set up the replicated redis example. First get
|
|
the kubernetes repo::
|
|
|
|
cd ~
|
|
git clone https://github.com/GoogleCloudPlatform/kubernetes.git
|
|
|
|
Create a pod for the redis-master::
|
|
|
|
cd kubernetes/examples/redis
|
|
BAY_UUID=$(magnum bay-list | awk '/ testbay /{print $2}')
|
|
magnum pod-create --manifest ./redis-master.yaml --bay-id $BAY_UUID
|
|
|
|
Now turn up a service to provide a discoverable endpoint for the redis sentinels
|
|
in the cluster::
|
|
|
|
magnum service-create --manifest ./redis-sentinel-service.yaml --bay-id $BAY_UUID
|
|
|
|
To make it a replicated redis cluster create replication controllers for the redis
|
|
slaves and sentinels::
|
|
|
|
sed -i 's/\(replicas: \)1/\1 2/' redis-controller.yaml
|
|
magnum rc-create --manifest ./redis-controller.yaml --bay-id $BAY_UUID
|
|
|
|
sed -i 's/\(replicas: \)1/\1 2/' redis-sentinel-controller.yaml
|
|
magnum rc-create --manifest ./redis-sentinel-controller.yaml --bay-id $BAY_UUID
|
|
|
|
Full lifecycle and introspection operations for each object are supported. For
|
|
exmaple, magnum bay-create magnum baymodel-delete, magnum rc-show, magnum service-list.
|
|
|
|
In this milestone you have to use the kubernetes kubectl tool to explore the
|
|
redis cluster in detail::
|
|
|
|
export KUBERNETES_MASTER=http://$(nova list | grep kube_master | awk '{print $13}'):8080
|
|
kubectl get pod
|
|
|
|
The output of `kubectl get pod` indicates the redis-master is running on the
|
|
bay host with IP address 10.0.0.5. To access the redis master::
|
|
|
|
ssh minion@$(nova list | grep 10.0.0.5 | awk '{print $13}')
|
|
REDIS_ID=$(docker ps | grep redis:v1 | grep k8s_master | awk '{print $1}')
|
|
docker exec -i -t $REDIS_ID redis-cli
|
|
|
|
127.0.0.1:6379> set replication:test true
|
|
OK
|
|
^D
|
|
|
|
exit
|
|
|
|
Now log into one of the other container hosts and access a redis slave from there::
|
|
|
|
ssh minion@$(nova list | grep 10.0.0.4 | awk '{print $13}')
|
|
REDIS_ID=$(docker ps | grep redis:v1 | grep k8s_redis | tail -n +2 | awk '{print $1}')
|
|
docker exec -i -t $REDIS_ID redis-cli
|
|
|
|
127.0.0.1:6379> get replication:test
|
|
"true"
|
|
^D
|
|
|
|
exit
|
|
|
|
There are four redis instances, one master and three slaves, running across the bay,
|
|
replicating data between one another.
|
|
|
|
================================
|
|
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
|