openstack/kolla-ansible
Code Issues Proposed changes

Add an integration guide to Kolla

Browse Source 
The best part about Kolla is using it!  In order to do that, we need to
instruct our consumers how it should be consumed.  This guide is a start
at that effort, but more work is needed.

Implements Blueprint: integration-guide

Change-Id: I64a3264a488f6dc934696307cd567e09d4817431
This commit is contained in:
Steven Dake 2015-03-16 12:27:10 -07:00
parent 4f622797ae
commit f2a3b407dc
1 changed files with 100 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
docs/integration-guide.md Normal file
View File

@ -0,0 +1,100 @@
# Integrating with Kolla
This guide describes how to integrate with Kolla. The main integration path is
via docker-compose using docker-compose YML files. Each container set has a
common YML and associated openstack.env. The openstack.env file describes the
command line environment to pass to the docker-compose yml files.
## Why integate with Kolla?
Integrating with Kolla takes a hard part of managing an OpenStack system,
specifically managing the container images, and places the burden on a third
party project. We strive to do an excellent job of providing world-class
OpenStack containers at least as a reference architecture, and possibly as what
may be desireable to deploy into live production.
## Docker Command Line Arguments
Every container set YML file includes the necessary docker CLI operations
needed to launch the container in a tidy YML file. Instead of guessing which
set of command line operations are needed per container, the docker-compose
YML file can be used directly and will pass the appropriate command line
values to the container on container start.
The parameterized docker features used by kolla are:
* --pid=host
* --net=host
* -v host:container
* --privileged
These parameterized features are not exposed to the user. Instead they are
executed via docker-compose.
## Environment Variables
Rather then document which individual containers require specific configuration
variables, Kolla integration requires passing all configuration variables to
all containers. This allows a simple method of ensuring every type of node
(controller, storage, compute) recieves the same configuration.
### Environment Variable KEY/VALUE pairs
ADMIN_TENANT_NAME=<admin> - tenant name
DB_ROOT_PASSWORD=<mysql root password> - defines the MYSQL root password
FLAT_INTERFACE=<nova or neutron networking flat interface device name>
GLANCE_API_SERVICE_HOST=<IP> - address where glance API is running>
GLANCE_DB_NAME=<glance> - DB name of glance service
GLANCE_DB_PASSWORD=<password> - <Glance DB password>
GLANCE_DB_USER=<glance> - User name of glance in the database
GLANCE_KEYSTONE_PASSWORD=<password> - Keystone DB password
GLANCE_KEYSTONE_USER=<keystone> - Glance Keystone User
GLANCE_REGISTRY_SERVICE_HOST=<glance IP> Glance registry service host
KEYSTONE_ADMIN_PASSWORD=<password>
KEYSTONE_ADMIN_SERVICE_HOST=<IP> - IP Address of Keystone Host
KEYSTONE_ADMIN_SERVICE_PORT=<5000> - Port where Keystone operates
KEYSTONE_ADMIN_TOKEN=<keystone-secret> - A token used to access Keystone
KEYSTONE_AUTH_PROTOCOL=<http> - The keystone authentication protocol
KEYSTONE_DB_PASSWORD=<password> - The password used to access Keystone in the DB
KEYSTONE_PUBLIC_SERVICE_HOST=<IP> - The IP address where Keystone is running
MARIADB_SERVICE_HOST=<IP> - The IP Address where mariadb is running
MYSQL_ROOT_PASSWORD=<password> - The MYSQL password
NETWORK_MANAGER=<nova|neutron> - Use Nova or Neutron networking
NOVA_API_SERVICE_HOST=<IP> - The IP Address where the Nova API Service is hosted
NOVA_DB_NAME=<nova> - The name of the nova entry in the database
NOVA_DB_PASSWORD=<password> - The password used to access nova
NOVA_DB_USER=<nova> - The name of the nova DB password
NOVA_EC2_API_SERVICE_HOST=<IP> - The IP Address where the Nova EC2 API is hosted
arn't these two the same?
NOVA_EC2_SERVICE_HOST=<IP> _ The IP Address wher ethe Nova EC2 service is hosted
NOVA_KEYSTONE_PASSWORD=<password> - The Nova keystone password
NOVA_KEYSTONE_USER=<nova> - The Nova keystone username
PUBLIC_INTERFACE=<eth1> - The nova public interface
PUBLIC_IP=<Host IP Address> - The IP Address of this host
RABBITMQ_PASS=<rabbit> - The rabbitmq password used to join AMQP
RABBITMQ_SERVICE_HOST=<IP> - The IP Address where the Rabbit service is running
RABBITMQ_USER=<rabbit> - The RabbitMQ user name
RABBIT_PASSWORD=<password> - The RabbitMQ password
RABBIT_USERID=<rabbit> - The RabbitMQ user id on the host
## Launching a container set
Pick out a simple container set and launch it as follows:
docker-compose -f compose/rabbitmq.yml up -d
The third party deployment engine should launch the appropriate containers for
the appropriate nodes. Note the rabbitmq.yml used in the example above expects
an openstack.env file present in the current working directory. This file will
be passed as environment data to the container and configure the container
appropriately.
# Conclusion
Integrating with Kolla is as sample as creating an openstack.env file, having
a deployment tool write the openstack.env file and .yml files to the nodes
are targeted for deployment, and running docker-compose as described in the
above documentation.