openstack/kolla-ansible
Code Issues Proposed changes

Structuring the documentation

Browse Source 
Restructured the documenation to

1. Add reference at the top
2. Updated the title formatting
3. Updated the heading formatting
4. Updated the links formatting

Change-Id: Ie3786e92fee674da1fa39cf07f1bf0a3badd5b92
This commit is contained in:
Swapnil Kulkarni (coolsvap) 2016-05-16 20:37:35 +05:30
parent 460ebbe021
commit d87b4f63a2
18 changed files with 180 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/CONTRIBUTING.rst
View File

@ -1,9 +1,11 @@
.. _CONTRIBUTING:
================= =================
How To Contribute How To Contribute
================= =================
Basics Basics
~~~~~~ ======
* Our source code is hosted on `OpenStack GitHub`_, but pull requests submitted * Our source code is hosted on `OpenStack GitHub`_, but pull requests submitted
through GitHub will be ignored. Bugs should be filed on launchpad_, through GitHub will be ignored. Bugs should be filed on launchpad_,
@ -28,7 +30,7 @@ Basics
.. _here: https://wiki.openstack.org/wiki/GitCommitMessages .. _here: https://wiki.openstack.org/wiki/GitCommitMessages
Development Environment Development Environment
~~~~~~~~~~~~~~~~~~~~~~~ ========================
* Please follow our `quickstart`_ to deploy your environment and test your changes * Please follow our `quickstart`_ to deploy your environment and test your changes

32
doc/advanced-configuration.rst
View File

@ -1,8 +1,12 @@
.. _advanced-configuration:
======================
Advanced Configuration Advanced Configuration
====================== ======================
Endpoint Network Configuration Endpoint Network Configuration
------------------------------ ==============================
When an OpenStack cloud is deployed, each services' REST API is presented When an OpenStack cloud is deployed, each services' REST API is presented
as a series of endpoints. These endpoints are the admin URL, the internal as a series of endpoints. These endpoints are the admin URL, the internal
URL, and the external URL. URL, and the external URL.
@ -37,9 +41,9 @@ networks.
kolla_external_vip_address: "10.10.20.254" kolla_external_vip_address: "10.10.20.254"
kolla_external_vip_interface: "eth1" kolla_external_vip_interface: "eth1"
Fully Qualified Domain Name Configuration Fully Qualified Domain Name Configuration
----------------------------------------- =========================================
When addressing a server on the internet, it is more common to use When addressing a server on the internet, it is more common to use
a name, like www.example.net, instead of an address like 10.10.10.254. a name, like www.example.net, instead of an address like 10.10.10.254.
If you prefer to use names to address the endpoints in your kolla If you prefer to use names to address the endpoints in your kolla
@ -56,7 +60,8 @@ configured IP addresses. Using a DNS server or the /etc/hosts file are
two ways to create this mapping. two ways to create this mapping.
TLS Configuration TLS Configuration
----------------- =================
An additional endpoint configuration option is to enable or disable An additional endpoint configuration option is to enable or disable
TLS protection for the external VIP. TLS allows a client to authenticate TLS protection for the external VIP. TLS allows a client to authenticate
the OpenStack service endpoint and allows for encryption of the requests the OpenStack service endpoint and allows for encryption of the requests
@ -109,7 +114,8 @@ have settings similar to this:
export OS_IDENTITY_API_VERSION=3 export OS_IDENTITY_API_VERSION=3
Self-Signed Certificates Self-Signed Certificates
------------------------ ========================
.. NOTE:: Self-signed certificates should never be used in production. .. NOTE:: Self-signed certificates should never be used in production.
It is not always practical to get a certificate signed by a well-known It is not always practical to get a certificate signed by a well-known
@ -126,13 +132,14 @@ file.
The files haproxy.pem and haproxy-ca.pem will be generated and stored The files haproxy.pem and haproxy-ca.pem will be generated and stored
in the /etc/kolla/certificates/ directory. in the /etc/kolla/certificates/ directory.
Deployment Configuration Deployment Configuration
------------------------ ========================
TODO(all) fill this section out TODO(all) fill this section out
OpenStack Service Configuration in Kolla OpenStack Service Configuration in Kolla
---------------------------------------- ========================================
.. NOTE:: As of now kolla only supports config overrides for ini based configs. .. NOTE:: As of now kolla only supports config overrides for ini based configs.
Kolla allows deployer to override configuration of services. Kolla will look Kolla allows deployer to override configuration of services. Kolla will look
@ -148,7 +155,7 @@ need to create `/etc/kolla/config/nova/nova-scheduler.conf with content`:
scheduler_max_attempts = 100 scheduler_max_attempts = 100
If the operator wants to configure compute node ram allocation ratio If the operator wants to configure compute node ram allocation ratio
on host myhost, the operator needs to create file on host myhost, the operator needs to create file
`/etc/kolla/config/nova/myhost/nova.conf` with content: `/etc/kolla/config/nova/myhost/nova.conf` with content:
:: ::
@ -157,13 +164,14 @@ on host myhost, the operator needs to create file
ram_allocation_ratio = 5.0 ram_allocation_ratio = 5.0
The operator can make these changes after services were already deployed by using The operator can make these changes after services were already deployed by using
following command following command.
.
:: ::
kolla-ansible reconfigure kolla-ansible reconfigure
IP Address Constrained Environments IP Address Constrained Environments
----------------------------------- ===================================
If a development environment doesn't have a free IP address available for VIP If a development environment doesn't have a free IP address available for VIP
configuration, the host's IP address may be used here by disabling HAProxy by configuration, the host's IP address may be used here by disabling HAProxy by
adding: adding:

16
doc/ceph-guide.rst
View File

@ -1,3 +1,6 @@
.. _ceph-guide:
=============
Ceph in Kolla Ceph in Kolla
============= =============
@ -7,13 +10,13 @@ tweaks to the Ceph cluster you can deploy a "healthy" cluster with a single
host and a single block device. host and a single block device.
Requirements Requirements
------------ ============
* A minimum of 3 hosts for a vanilla deploy * A minimum of 3 hosts for a vanilla deploy
* A minimum of 1 block device per host * A minimum of 1 block device per host
Preparation and Deployment Preparation and Deployment
-------------------------- ==========================
To prepare a disk for use as a To prepare a disk for use as a
`Ceph OSD <http://docs.ceph.com/docs/master/man/8/ceph-osd/>`_ you must add a `Ceph OSD <http://docs.ceph.com/docs/master/man/8/ceph-osd/>`_ you must add a
@ -83,9 +86,8 @@ Finally deploy the Ceph-enabled OpenStack:
kolla-ansible deploy -i path/to/inventory kolla-ansible deploy -i path/to/inventory
Using a Cache Tier Using a Cache Tier
------------------ ==================
An optional An optional
`cache tier <http://docs.ceph.com/docs/hammer/rados/operations/cache-tiering/>`_ `cache tier <http://docs.ceph.com/docs/hammer/rados/operations/cache-tiering/>`_
@ -115,9 +117,8 @@ After this run the playbooks as you normally would. For example:
kolla-ansible deploy -i path/to/inventory kolla-ansible deploy -i path/to/inventory
Setting up an Erasure Coded Pool Setting up an Erasure Coded Pool
-------------------------------- ================================
`Erasure code <http://docs.ceph.com/docs/hammer/rados/operations/erasure-code/>`_ `Erasure code <http://docs.ceph.com/docs/hammer/rados/operations/erasure-code/>`_
is the new big thing from Ceph. Kolla has the ability to setup your Ceph pools is the new big thing from Ceph. Kolla has the ability to setup your Ceph pools
@ -138,9 +139,8 @@ To enable erasure coded pools add the following options to your
# Optionally, you can change the profile # Optionally, you can change the profile
#ceph_erasure_profile: "k=4 m=2 ruleset-failure-domain=host" #ceph_erasure_profile: "k=4 m=2 ruleset-failure-domain=host"
Managing Ceph Managing Ceph
------------- =============
Check the Ceph status for more diagnostic information. The sample output below Check the Ceph status for more diagnostic information. The sample output below
indicates a healthy cluster: indicates a healthy cluster:

47
doc/cinder-guide.rst
View File

@ -1,8 +1,12 @@
.. _cinder-guide:
===============
Cinder in Kolla Cinder in Kolla
=============== ===============
Overview Overview
-------- ========
Currently Kolla can deploy the cinder services: Currently Kolla can deploy the cinder services:
- cinder-api - cinder-api
@ -15,7 +19,7 @@ implementation requires a volume group be set up. This can either be
a real physical volume or a loopback mounted file for development. a real physical volume or a loopback mounted file for development.
Create a Volume Group Create a Volume Group
--------------------- =====================
Use pvcreate and vgcreate to create the volume group. For example with Use pvcreate and vgcreate to create the volume group. For example with
the devices /dev/sdb and /dev/sdc: the devices /dev/sdb and /dev/sdc:
@ -39,7 +43,7 @@ system.
vgcreate cinder-volumes /dev/loop2 vgcreate cinder-volumes /dev/loop2
Validation Validation
---------- ==========
Create a volume as follows: Create a volume as follows:
@ -77,7 +81,8 @@ If the disk stays in the available state, something went wrong during the
iSCSI mounting of the volume to the guest VM. iSCSI mounting of the volume to the guest VM.
Cinder LVM2 backend with iSCSI Cinder LVM2 backend with iSCSI
------------------------------ ==============================
As of Newton-1 milestone, Kolla supports LVM2 as cinder backend. It is As of Newton-1 milestone, Kolla supports LVM2 as cinder backend. It is
accomplished by introducing two new containers tgtd and iscsid. accomplished by introducing two new containers tgtd and iscsid.
tgtd container serves as a bridge between cinder-volume process and a server tgtd container serves as a bridge between cinder-volume process and a server
@ -85,11 +90,10 @@ hosting Logical Volume Groups (LVG). iscsid container serves as a bridge
between nova-compute process and the server hosting LVG. between nova-compute process and the server hosting LVG.
There are two methods to apply new configuration to cinder: There are two methods to apply new configuration to cinder:
1 - New deployments: create cinder.conf and place it at /etc/kolla/config - New deployments: create cinder.conf and place it at /etc/kolla/config
folder, then add below configuration lines and run kolla deloyment. folder, then add below configuration lines and run kolla deloyment.
2 - Existing cinder deployments: modify cinder.conf located at - Existing cinder deployments: modify cinder.conf located at /etc/kolla/config
/etc/kolla/config by adding below configuration lines and run kolla by adding below configuration lines and run kolla reconfigure.
reconfigure.
:: ::
@ -109,14 +113,12 @@ There are two methods to apply new configuration to cinder:
Where: Where:
- local_lvm_name is a name chosen by a user for a spefic LVM2 backend, multiple - local_lvm_name is a name chosen by a user for a spefic LVM2 backend, multiple
LVM2 backend can be confiugred and each should have a unique name. LVM2 backend can be confiugred and each should have a unique name.
- lvg_name is a name Logical Volume Group created for cinder to store volumes.
- lvg_name is a name Logical Volume Group created for cinder to store volumes. - management_ip_address_of_server_hosting_LVG is IP address of an interface
where cinder process is bound to. (Do not use VIP address here, LVG does not
- management_ip_address_of_server_hosting_LVG is IP address of an interface move from server to server as VIP address does in case of a server failure).
where cinder process is bound to. (Do not use VIP address here, LVG does not
move from server to server as VIP address does in case of a server failure).
NOTE: For Ubuntu and LVM2/iSCSI NOTE: For Ubuntu and LVM2/iSCSI
@ -126,9 +128,8 @@ file system gets mounted automatically, which is not the case on debian/ubuntu.
Since iscsid container runs on every nova compute node, the following steps must Since iscsid container runs on every nova compute node, the following steps must
be completed on every Ubuntu server targeted for nova compute role. be completed on every Ubuntu server targeted for nova compute role.
1 - Add configfs module to /etc/modules - Add configfs module to /etc/modules
2 - Rebuild initramfs using: "update-initramfs -u" command - Rebuild initramfs using: "update-initramfs -u" command
3 - Make sure configfs gets mounted during a server boot up process. There are - Make sure configfs gets mounted during a server boot up process. There are
multiple ways to accomplish it, one example is adding this command to multiple ways to accomplish it, one example is adding this command to
"mount -t configfs configfs /sys/kernel/config" to /etc/rc.local "mount -t configfs configfs /sys/kernel/config" to /etc/rc.local

10
doc/deployment-philosophy.rst
View File

@ -1,8 +1,11 @@
.. _deployment-philosophy:
=============================
Kolla's Deployment Philosophy Kolla's Deployment Philosophy
============================= =============================
Overview Overview
-------- ========
Kolla has an objective to replace the inflexible, painful, resource intensive Kolla has an objective to replace the inflexible, painful, resource intensive
deployment process of OpenStack with a flexible, painless, inexpensive deployment process of OpenStack with a flexible, painless, inexpensive
@ -20,7 +23,7 @@ OpenStack services increases, Kolla offers full capability to override every
OpenStack service configuration option in the deployment. OpenStack service configuration option in the deployment.
Why not Template Customization? Why not Template Customization?
------------------------------- ===============================
The Kolla upstream community does not want to place key/value pairs in the The Kolla upstream community does not want to place key/value pairs in the
Ansible playbook configuration options that are not essential to obtaining Ansible playbook configuration options that are not essential to obtaining
@ -35,9 +38,8 @@ cycle is required in order to successfully add a new customization.
Essentially templating in configuration options is not a scalable solution Essentially templating in configuration options is not a scalable solution
and would result in an inability of the project to execute its mission. and would result in an inability of the project to execute its mission.
Kolla's Solution to Customization Kolla's Solution to Customization
--------------------------------- =================================
Rather than deal with the customization madness of templating configuration Rather than deal with the customization madness of templating configuration
options in Kolla's Ansible playbooks, Kolla eliminates all the inefficiencies options in Kolla's Ansible playbooks, Kolla eliminates all the inefficiencies

12
doc/heat-dev-env.rst
View File

@ -1,3 +1,6 @@
.. _heat-dev-env:
=================================
Development Environment with Heat Development Environment with Heat
================================= =================================
@ -33,7 +36,7 @@ correct a bug with template validation when using the "Fn::Join"
function). function).
Create the Glance Image Create the Glance Image
----------------------- =======================
After cloning the project, run the get-image.sh script from the After cloning the project, run the get-image.sh script from the
project's devenv directory: project's devenv directory:
@ -55,7 +58,7 @@ Add the image to your Glance image store:
--is-public True --progress --is-public True --progress
Create the Stack Create the Stack
---------------- ================
Copy local.yaml.example to local.yaml and edit the contents to match Copy local.yaml.example to local.yaml and edit the contents to match
your deployment environment. Here is an example of a customized your deployment environment. Here is an example of a customized
@ -100,7 +103,7 @@ And then create the stack, referencing that environment file:
$ heat stack-create -f kollacluster.yaml -e local.yaml kolla-cluster $ heat stack-create -f kollacluster.yaml -e local.yaml kolla-cluster
Access the Kolla Nodes Access the Kolla Nodes
---------------------- ======================
You can get the ip address of the Kolla nodes using the You can get the ip address of the Kolla nodes using the
``heat output-show`` command: ``heat output-show`` command:
@ -149,7 +152,7 @@ If you want to start a container set by hand use this template
$ docker-compose -f glance-api-registry.yml up -d $ docker-compose -f glance-api-registry.yml up -d
Debugging Debugging
--------- =========
All Docker commands should be run from the directory of the Docker All Docker commands should be run from the directory of the Docker
binary, by default this is ``/``. binary, by default this is ``/``.
@ -191,4 +194,3 @@ appear as follows
Trying 10.0.0.4... Trying 10.0.0.4...
Connected to 10.0.0.4. Connected to 10.0.0.4.
Escape character is '^]'. Escape character is '^]'.

32
doc/image-building.rst
View File

@ -1,3 +1,6 @@
.. _image-building:
=========================
Building Container Images Building Container Images
========================= =========================
@ -5,7 +8,7 @@ The ``tools/build.py`` script in this repository is
responsible for building docker images. responsible for building docker images.
Generating kolla-build.conf Generating kolla-build.conf
--------------------------- ===========================
Install tox and generate the build configuration. The build Install tox and generate the build configuration. The build
configuration is designed to hold advanced customizations when building configuration is designed to hold advanced customizations when building
@ -21,9 +24,8 @@ The location of the generated configuration file is ``etc/kolla/kolla-build.conf
You can also copy it to ``/etc/kolla``. The default location is one of You can also copy it to ``/etc/kolla``. The default location is one of
``/etc/kolla/kolla-build.conf`` or ``etc/kolla/kolla-build.conf``. ``/etc/kolla/kolla-build.conf`` or ``etc/kolla/kolla-build.conf``.
Guide Guide
----- =====
In general, you will build images like this: In general, you will build images like this:
@ -94,9 +96,8 @@ command:
tox -e genconfig tox -e genconfig
Build OpenStack from Source Build OpenStack from Source
--------------------------- ===========================
When building images, there are two methods of the OpenStack install. When building images, there are two methods of the OpenStack install.
One is ``binary``. Another is ``source``. One is ``binary``. Another is ``source``.
@ -154,9 +155,8 @@ Then build RHEL containers:
build -b rhel -i ./rhel-include build -b rhel -i ./rhel-include
Custom Repos Custom Repos
------------ ============
The build method allows you to build your containers from custom repos. The build method allows you to build your containers from custom repos.
The repos are accepted as a list of comma separated values and can be in The repos are accepted as a list of comma separated values and can be in
@ -173,9 +173,8 @@ same directory as the base Dockerfile (kolla/docker/base).
rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo
Plugin Functionality Plugin Functionality
-------------------- ====================
.. note:: .. note::
@ -210,10 +209,8 @@ image, one would add the following block to ``/etc/kolla/kolla-build.conf``:
location = https://github.com/openstack/networking-cisco location = https://github.com/openstack/networking-cisco
reference = master reference = master
Known issues Known issues
------------ ============
1. Can't build base image because docker fails to install systemd. 1. Can't build base image because docker fails to install systemd.
@ -222,9 +219,8 @@ Known issues
to avoid the issue is that add ``-s devicemapper`` to ``DOCKER_OPTS``. to avoid the issue is that add ``-s devicemapper`` to ``DOCKER_OPTS``.
Get more information about the issue from DockerBug_. Get more information about the issue from DockerBug_.
Docker Local Registry Docker Local Registry
--------------------- =====================
It is recommended to set up local registry for Kolla developers It is recommended to set up local registry for Kolla developers
or deploying multinode. The reason using a local registry is or deploying multinode. The reason using a local registry is
@ -235,7 +231,7 @@ If there is no local registry, nodes pull images from Docker Hub
when images are not found in local caches. when images are not found in local caches.
Setting up Docker Local Registry Setting up Docker Local Registry
++++++++++++++++++++++++++++++++ --------------------------------
Running Docker registry is easy. Just use the following command: Running Docker registry is easy. Just use the following command:
@ -250,7 +246,7 @@ To avoid conflict, use 4000 port as Docker registry port.
Now the Docker registry service is running. Now the Docker registry service is running.
Docker Insecure Registry Config Docker Insecure Registry Config
+++++++++++++++++++++++++++++++ -------------------------------
For docker to pull images, it is necessary to For docker to pull images, it is necessary to
modify the Docker configuration. The guide assumes that modify the Docker configuration. The guide assumes that
@ -271,7 +267,7 @@ To build and push images to local registry, use the following command:
tools/build.py --registry 172.22.2.81:4000 --push tools/build.py --registry 172.22.2.81:4000 --push
Kolla-ansible with Local Registry Kolla-ansible with Local Registry
+++++++++++++++++++++++++++++++++ ---------------------------------
To make kolla-ansible pull images from local registry, set To make kolla-ansible pull images from local registry, set
``"docker_registry"`` to ``"172.22.2.81:4000"`` in ``"docker_registry"`` to ``"172.22.2.81:4000"`` in
@ -281,7 +277,7 @@ images from insecure registry. See
Building behind a proxy Building behind a proxy
+++++++++++++++++++++++ -----------------------
The build script supports augmenting the Dockerfiles under build via so called The build script supports augmenting the Dockerfiles under build via so called
`header` and `footer` files. Statements in the `header` file are included at `header` and `footer` files. Statements in the `header` file are included at

9
doc/ironic-guide.rst
View File

@ -1,8 +1,11 @@
.. _ironic-guide:
===============
Ironic in Kolla Ironic in Kolla
=============== ===============
Overview Overview
-------- ========
Currently Kolla can deploy the Ironic services: Currently Kolla can deploy the Ironic services:
- ironic-api - ironic-api
@ -12,13 +15,13 @@ Currently Kolla can deploy the Ironic services:
As well as a required PXE service, deployed as ironic-pxe. As well as a required PXE service, deployed as ironic-pxe.
Current status Current status
-------------- ==============
The Ironic implementation is "tech preview", so currently instances can only be The Ironic implementation is "tech preview", so currently instances can only be
deployed on baremetal. Further work will be done to allow scheduling for both deployed on baremetal. Further work will be done to allow scheduling for both
virtualized and baremetal deployments. virtualized and baremetal deployments.
Post-deployment configuration Post-deployment configuration
----------------------------- =============================
Configuration based off upstream documentation_. Configuration based off upstream documentation_.
Again, remember that enabling Ironic reconfigures nova compute (driver and Again, remember that enabling Ironic reconfigures nova compute (driver and

14
doc/kibana-guide.rst
View File

@ -1,8 +1,11 @@
.. _kibana-guide:
===============
Kibana in Kolla Kibana in Kolla
=============== ===============
Default index pattern Default index pattern
--------------------- =====================
After successful Kibana deployment, it can be accessed on After successful Kibana deployment, it can be accessed on
<kolla_internal_vip_address>:<kibana_server_port> <kolla_internal_vip_address>:<kibana_server_port>
@ -32,7 +35,7 @@ Note: This step is necessary until the default Kibana dashboard is implemented
in Kolla. in Kolla.
Search logs - Discover tab Search logs - Discover tab
-------------------------- ===========================
Logs search is available under Discover tab. In the menu on the left side, Logs search is available under Discover tab. In the menu on the left side,
one can choose any field that will be included in a new search. To do this, one can choose any field that will be included in a new search. To do this,
@ -45,7 +48,7 @@ Current search can be saved by using 'Save search' option in the menu on the
right. right.
Visualize data - Visualize tab Visualize data - Visualize tab
------------------------------ ==============================
In the visualization tab a wide range of charts is available. If any In the visualization tab a wide range of charts is available. If any
visualization has not been saved yet, after choosing this tab 'Create a new visualization has not been saved yet, after choosing this tab 'Create a new
@ -65,7 +68,7 @@ visualization' option in the menu on the right. If it is not saved, it will
be lost after leaving a page or creating another visualization. be lost after leaving a page or creating another visualization.
Organize visualizations and searches - Dashboard tab Organize visualizations and searches - Dashboard tab
---------------------------------------------------- ====================================================
In the Dashboard tab all of saved visualizations and searches can be In the Dashboard tab all of saved visualizations and searches can be
organized in one Dashboard. To add visualization or search, one can choose organized in one Dashboard. To add visualization or search, one can choose
@ -82,7 +85,7 @@ If a Dashboard has already been saved, it can be opened by choosing 'open
dashboard' option in the menu on the right. dashboard' option in the menu on the right.
Exporting and importing created items - Settings tab Exporting and importing created items - Settings tab
------------------------------------------------------------ =====================================================
Once visualizations, searches or dashboards are created, they can be exported Once visualizations, searches or dashboards are created, they can be exported
to a json format by choosing Settings tab and then Objects tab. Each of the to a json format by choosing Settings tab and then Objects tab. Each of the
@ -90,4 +93,3 @@ item can be exported separately by selecting it in the menu. All of the items
can also be exported at once by choosing 'export everything' option. can also be exported at once by choosing 'export everything' option.
In the same tab (Settings - Objects) one can also import saved items by In the same tab (Settings - Objects) one can also import saved items by
choosing 'import' option. choosing 'import' option.

11
doc/liberty-deployment-warning.rst
View File

@ -1,14 +1,17 @@
.. _liberty-deployment-warning:
================================
Liberty 1.0.0 Deployment Warning Liberty 1.0.0 Deployment Warning
================================ ================================
Warning Overview Warning Overview
---------------- ================
Please use Liberty 1.1.0 tag or later when using Kolla. No data loss Please use Liberty 1.1.0 tag or later when using Kolla. No data loss
occurs with this version. stable/liberty is also fully functional and occurs with this version. stable/liberty is also fully functional and
suffers no data loss. suffers no data loss.
Data loss with 1.0.0 Data loss with 1.0.0
-------------------- ====================
The Kolla community discovered in the of middle Mitaka development that it The Kolla community discovered in the of middle Mitaka development that it
was possible for data loss to occur if the data container is rebuilt. In was possible for data loss to occur if the data container is rebuilt. In
this scenario, Docker pulls a new container, and the new container doesn't this scenario, Docker pulls a new container, and the new container doesn't
@ -17,7 +20,7 @@ contain the data from the old container. Kolla stable/liberty and Kolla
problems*. problems*.
Resolution Resolution
---------- ==========
To rectify this problem, the OpenStack release and infrastructure teams To rectify this problem, the OpenStack release and infrastructure teams
in coordination with the Kolla team executed the following actions: in coordination with the Kolla team executed the following actions:
@ -29,7 +32,7 @@ in coordination with the Kolla team executed the following actions:
* Released Kolla 1.1.0 from the newly created stable/liberty branch. * Released Kolla 1.1.0 from the newly created stable/liberty branch.
End Result End Result
---------- ==========
A fully functional Liberty OpenStack deployment based upon the two years of A fully functional Liberty OpenStack deployment based upon the two years of
testing that went into the development that went into stable/mitaka. testing that went into the development that went into stable/mitaka.

22
doc/manila-guide.rst
View File

@ -1,8 +1,11 @@
.. _manila-guide:
===============
Manila in Kolla Manila in Kolla
=============== ===============
Overview Overview
-------- ========
Currently, Kolla can deploy following manila services: Currently, Kolla can deploy following manila services:
* manila-api * manila-api
@ -16,7 +19,7 @@ management of share types as well as share snapshots if a driver supports
them. them.
Important Important
--------- =========
For simplicity, this guide describes configuring the Shared File Systems For simplicity, this guide describes configuring the Shared File Systems
service to use the ``generic`` back end with the driver handles share service to use the ``generic`` back end with the driver handles share
@ -29,7 +32,7 @@ Before you proceed, ensure that Compute, Networking and Block storage
services are properly working. services are properly working.
Preparation and Deployment Preparation and Deployment
-------------------------- ==========================
Cinder and Ceph are required, enable it in /etc/kolla/globals.yml: Cinder and Ceph are required, enable it in /etc/kolla/globals.yml:
@ -57,8 +60,8 @@ Create or modify the file /etc/kolla/config/manila.conf and add the contents:
[generic] [generic]
service_instance_flavor_id = 2 service_instance_flavor_id = 2
Verify operation Verify Operation
---------------- ================
Verify operation of the Shared File Systems service. List service components Verify operation of the Shared File Systems service. List service components
to verify successful launch of each process: to verify successful launch of each process:
@ -74,7 +77,7 @@ to verify successful launch of each process:
+------------------+----------------+------+---------+-------+----------------------------+-----------------+ +------------------+----------------+------+---------+-------+----------------------------+-----------------+
Launch an Instance Launch an Instance
------------------ ==================
Before being able to create a share, the manila with the generic driver and Before being able to create a share, the manila with the generic driver and
the DHSS mode enabled requires the definition of at least an image, the DHSS mode enabled requires the definition of at least an image,
@ -83,7 +86,7 @@ For that back end configuration, the share server is an instance where
NFS/CIFS shares are served. NFS/CIFS shares are served.
Determine the configuration of the share server Determine the configuration of the share server
----------------------------------------------- ===============================================
Create a default share type before running manila-share service: Create a default share type before running manila-share service:
@ -171,7 +174,7 @@ Create a flavor (Required if you not defined manila_instance_flavor_id in
# nova flavor-create manila-service-flavor 100 128 0 1 # nova flavor-create manila-service-flavor 100 128 0 1
Create a share Create a share
-------------- ==============
Create a NFS share using the share network: Create a NFS share using the share network:
@ -225,7 +228,7 @@ network:
# manila access-allow demo-share1 ip INSTANCE_PRIVATE_NETWORK_IP # manila access-allow demo-share1 ip INSTANCE_PRIVATE_NETWORK_IP
Mount the share from an instance Mount the share from an instance
-------------------------------- ================================
Get export location from share Get export location from share
@ -284,4 +287,3 @@ Mount the NFS share in the instance using the export location of the share:
For more information about how to manage shares, see the For more information about how to manage shares, see the
`OpenStack User Guide `OpenStack User Guide
<http://docs.openstack.org/user-guide/index.html>`__. <http://docs.openstack.org/user-guide/index.html>`__.

13
doc/multinode.rst
View File

@ -1,8 +1,11 @@
.. _multinode:
=============================
Multinode Deployment of Kolla Multinode Deployment of Kolla
============================= =============================
Deploy a registry (required for multinode) Deploy a registry (required for multinode)
------------------------------------------ ==========================================
A Docker registry is a locally hosted registry that replaces the need A Docker registry is a locally hosted registry that replaces the need
to pull from the Docker Hub to get images. Kolla can function with to pull from the Docker Hub to get images. Kolla can function with
@ -72,7 +75,7 @@ And restart docker by executing the following commands:
sudo service docker restart sudo service docker restart
Edit the Inventory File Edit the Inventory File
----------------------- =======================
The ansible inventory file contains all the information needed to determine The ansible inventory file contains all the information needed to determine
what services will land on which hosts. Edit the inventory file in the kolla what services will land on which hosts. Edit the inventory file in the kolla
@ -108,7 +111,7 @@ and changing these around can break your deployment:
network network
Deploying Kolla Deploying Kolla
--------------- ===============
First, check that the deployment targets are in a state where Kolla may deploy First, check that the deployment targets are in a state where Kolla may deploy
to them: to them:
@ -117,12 +120,10 @@ to them:
kolla-ansible prechecks -i <path/to/multinode/inventory/file> kolla-ansible prechecks -i <path/to/multinode/inventory/file>
For additional environment setup see the `quickstart guide`_. For additional environment setup see the :ref:`deploying-kolla`.
Run the deployment: Run the deployment:
:: ::
kolla-ansible deploy -i <path/to/multinode/inventory/file> kolla-ansible deploy -i <path/to/multinode/inventory/file>
.. _quickstart guide: ./quickstart.rst#deploying-kolla

5
doc/nova-fake-driver.rst
View File

@ -1,3 +1,6 @@
.. nova-fake-driver:
================
Nova Fake Driver Nova Fake Driver
================ ================
@ -13,7 +16,7 @@ we can create 100 nova-compute containers on a real host to simulate the
100-hypervisor workload to the nova-conductor and the messaging queue. 100-hypervisor workload to the nova-conductor and the messaging queue.
Use nova-fake driver Use nova-fake driver
--------------------- ====================
Nova fake driver can not work with all-in-one deployment. This is because the Nova fake driver can not work with all-in-one deployment. This is because the
fake neutron-openvswitch-agent for the fake nova-compute container conflicts fake neutron-openvswitch-agent for the fake nova-compute container conflicts

13
doc/operating-kolla.rst
View File

@ -1,24 +1,27 @@
.. _operating-kolla:
===============
Operating Kolla Operating Kolla
=============== ===============
Upgrading Upgrading
--------- =========
TODO(all) fill this section out TODO(all) fill this section out
Diagnostics Diagnostics
----------- ===========
TODO(all) fill this section out TODO(all) fill this section out
Failure Recovery Failure Recovery
---------------- ================
TODO(all) fill this section out TODO(all) fill this section out
Reconfiguration of an existing environment Reconfiguration of an existing environment
------------------------------------------ ==========================================
TODO(all) fill this section out TODO(all) fill this section out
Tips and Tricks Tips and Tricks
--------------- ===============
Kolla ships with several utilities intended to facilitate ease of operation. Kolla ships with several utilities intended to facilitate ease of operation.
``tools/cleanup-containers`` can be used to remove deployed containers from ``tools/cleanup-containers`` can be used to remove deployed containers from

49
doc/quickstart.rst
View File

@ -1,8 +1,11 @@
.. quickstart:
====================================================
Deployment of Kolla on Bare Metal or Virtual Machine Deployment of Kolla on Bare Metal or Virtual Machine
==================================================== ====================================================
Host machine requirements Host machine requirements
------------------------- =========================
The recommended deployment target requirements: The recommended deployment target requirements:
@ -13,18 +16,15 @@ The recommended deployment target requirements:
.. NOTE:: Some commands below may require root permissions (e.g. pip, apt-get). .. NOTE:: Some commands below may require root permissions (e.g. pip, apt-get).
Recommended Environment Recommended Environment
----------------------- =======================
If developing or evaluating Kolla, the community strongly recommends using bare If developing or evaluating Kolla, the community strongly recommends using bare
metal or a virtual machine. Follow the instructions in this document to get metal or a virtual machine. Follow the instructions in this document to get
started with deploying OpenStack on bare metal or a virtual machine with Kolla. started with deploying OpenStack on bare metal or a virtual machine with Kolla.
There are other deployment environments referenced below in `Additional Environments`_.
.. NOTE:: There are other deployment environments referenced below in
`Additional Environments`_.
Install Dependencies Install Dependencies
----------------------- ====================
Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container
OS platforms and bare metal deployment targets. OS platforms and bare metal deployment targets.
@ -244,9 +244,8 @@ to /etc:
cd kolla cd kolla
cp -r etc/kolla /etc/ cp -r etc/kolla /etc/
Install Python Clients Install Python Clients
---------------------- ======================
On the system where the OpenStack CLI/Python code is run, the Kolla community On the system where the OpenStack CLI/Python code is run, the Kolla community
recommends installing the OpenStack python clients if they are not installed. recommends installing the OpenStack python clients if they are not installed.
@ -273,27 +272,26 @@ To install the clients use:
pip install -U python-openstackclient python-neutronclient pip install -U python-openstackclient python-neutronclient
Local Registry Local Registry
-------------- ==============
A local registry is not required for an all-in-one installation. Check out the A local registry is not required for an all-in-one installation. Check out the
`multinode doc`_ for more information on using a local registry. Otherwise, the :doc:`multinode` for more information on using a local registry. Otherwise, the
`dockerhub image registry https://hub.docker.com/u/kollaglue/`__ contains all images from each of Kolla's major releases. The latest release tag is `Docker Hub Image Registry`_ contains all images from each of Kolla's major releases. The latest release tag is
2.0.0 for Mitaka. 2.0.0 for Mitaka.
Additional Environments Additional Environments
----------------------- =======================
Two virtualized development environment options are available for Kolla. Two virtualized development environment options are available for Kolla.
These options permit the development of Kolla without disrupting the host These options permit the development of Kolla without disrupting the host
operating system. operating system.
If developing Kolla on an OpenStack cloud environment that supports Heat, If developing Kolla on an OpenStack cloud environment that supports Heat,
follow the `Heat developer environment guide <heat-dev-env>`__. follow the :doc:`heat-dev-env`.
If developing Kolla on a system that provides VirtualBox or Libvirt in If developing Kolla on a system that provides VirtualBox or Libvirt in
addition to Vagrant, use the Vagrant virtual environment documented in addition to Vagrant, use the Vagrant virtual environment documented in
`Vagrant developer environment guide <vagrant-dev-env>`__. :doc:`vagrant-dev-env`.
Currently the Heat development environment is entirely non-functional. Currently the Heat development environment is entirely non-functional.
The Kolla core reviewers have debated removing it from the repository The Kolla core reviewers have debated removing it from the repository
@ -305,9 +303,8 @@ bare metal, or a manually setup virtual machine.
For more information refer to For more information refer to
`_bug 1562334 <https://bugs.launchpad.net/kolla/+bug/1562334>`__. `_bug 1562334 <https://bugs.launchpad.net/kolla/+bug/1562334>`__.
Building Container Images Building Container Images
------------------------- ==========================
The Kolla community does not currently generate new images for each commit The Kolla community does not currently generate new images for each commit
to the repository. The push time for a full image build to the docker registry to the repository. The push time for a full image build to the docker registry
@ -317,7 +314,7 @@ using the Docker Hub registry with the current OpenStack CI/CD systems.
The Kolla community builds and pushes tested images for each tagged release of The Kolla community builds and pushes tested images for each tagged release of
Kolla, but if running from master, it is recommended to build images locally. Kolla, but if running from master, it is recommended to build images locally.
Checkout the `image-building doc`_ for more advanced build configuration. Checkout the :doc:`image-building` for more advanced build configuration.
Before running the below instructions, ensure the docker daemon is running Before running the below instructions, ensure the docker daemon is running
or the build process will fail. To build images using default parameters run: or the build process will fail. To build images using default parameters run:
@ -365,9 +362,10 @@ In order to see all available parameters, run:
kolla-build -h kolla-build -h
.. _deploying-kolla:
Deploying Kolla Deploying Kolla
--------------- ===============
The Kolla community provides two example methods of Kolla The Kolla community provides two example methods of Kolla
deploy: *all-in-one* and *multinode*. The "all-in-one" deploy is similar deploy: *all-in-one* and *multinode*. The "all-in-one" deploy is similar
@ -375,7 +373,7 @@ to `devstack <http://docs.openstack.org/developer/devstack/>`__ deploy which
installs all OpenStack services on a single host. In the "multinode" deploy, installs all OpenStack services on a single host. In the "multinode" deploy,
OpenStack services can be run on specific hosts. This documentation only OpenStack services can be run on specific hosts. This documentation only
describes deploying *all-in-one* method as most simple one. To setup multinode describes deploying *all-in-one* method as most simple one. To setup multinode
see the `multinode doc`_. see the :doc:`multinode`.
Each method is represented as an Ansible inventory file. More information on Each method is represented as an Ansible inventory file. More information on
the Ansible inventory file can be found in the Ansible `inventory introduction the Ansible inventory file can be found in the Ansible `inventory introduction
@ -525,7 +523,7 @@ environment with a glance image and neutron networks:
kolla/tools/init-runonce kolla/tools/init-runonce
Failures Failures
-------- ========
Nearly always when Kolla fails, it is caused by a CTRL-C during the Nearly always when Kolla fails, it is caused by a CTRL-C during the
deployment process or a problem in the globals.yml configuration. deployment process or a problem in the globals.yml configuration.
@ -572,7 +570,7 @@ can occur. To refresh the docker cache from the local Docker registry:
kolla-ansible pull kolla-ansible pull
Debugging Kolla Debugging Kolla
--------------- ===============
The container's status can be determined on the deployment targets by The container's status can be determined on the deployment targets by
executing: executing:
@ -626,7 +624,4 @@ prompted to create an index. Please create an index using the name ``log-*``.
This step is necessary until the default Kibana dashboard is implemented in This step is necessary until the default Kibana dashboard is implemented in
Kolla. Kolla.
.. _Additional Environments: ./quickstart.rst#additional-environments .. _Docker Hub Image Registry: https://hub.docker.com/u/kollaglue/
.. _multinode doc: ./multinode.rst
.. _dockerhub image: https://hub.docker.com/u/kollaglue/
.. _image-building doc: ./image-building.rst

7
doc/selinux.rst
View File

@ -1,13 +1,16 @@
.. _selinux:
================
SELinux in Kolla SELinux in Kolla
================ ================
Overview Overview
-------- ========
The state of SELinux in Kolla is a work in progress. The short answer is you The state of SELinux in Kolla is a work in progress. The short answer is you
must disable it until selinux polices are written for the Docker containers. must disable it until selinux polices are written for the Docker containers.
The Long Answer The Long Answer
--------------- ===============
To understand why Kolla needs to set certain selinux policies for services that To understand why Kolla needs to set certain selinux policies for services that
you wouldn't expect to need them (rabbitmq, mariadb, glance, etc.) we must take you wouldn't expect to need them (rabbitmq, mariadb, glance, etc.) we must take
a step back and talk about Docker. a step back and talk about Docker.

17
doc/swift-guide.rst
View File

@ -1,18 +1,21 @@
.. _swift-guide:
==============
Swift in Kolla Swift in Kolla
============== ==============
Overview Overview
-------- ========
Kolla can deploy a full working Swift setup in either a AIO or multi node setup. Kolla can deploy a full working Swift setup in either a AIO or multi node setup.
Prerequisites Prerequisites
------------- =============
Before running Swift we need to generate "rings", which are binary compressed Before running Swift we need to generate "rings", which are binary compressed
files that at a high level let the various Swift services know where data is in files that at a high level let the various Swift services know where data is in
the cluster. We hope to automate this process in a future release. the cluster. We hope to automate this process in a future release.
Disks with a partition table (recommended) Disks with a partition table (recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ==========================================
Swift also expects block devices to be available for storage. To prepare a disk Swift also expects block devices to be available for storage. To prepare a disk
for use as Swift storage device, a special partition name and filesystem label for use as Swift storage device, a special partition name and filesystem label
@ -45,7 +48,7 @@ For evaluation, loopback devices can be used in lieu of real disks:
done done
Disks without a partition table Disks without a partition table
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ===============================
Kolla also supports unpartitioned disk (filesystem on /dev/sdc instead of Kolla also supports unpartitioned disk (filesystem on /dev/sdc instead of
/dev/sdc1) detection purely based on filesystem label. This is generally not a /dev/sdc1) detection purely based on filesystem label. This is generally not a
@ -61,7 +64,7 @@ ansible/roles/swift/defaults/main.yml
swift_devices_name: "swd" swift_devices_name: "swd"
Rings Rings
~~~~~ =====
Run following commands locally to generate Rings for AIO demo setup. The Run following commands locally to generate Rings for AIO demo setup. The
commands work with "disks with partition table" example listed above. Please commands work with "disks with partition table" example listed above. Please
@ -126,7 +129,7 @@ For more info, see
http://docs.openstack.org/kilo/install-guide/install/apt/content/swift-initial-rings.html http://docs.openstack.org/kilo/install-guide/install/apt/content/swift-initial-rings.html
Deploying Deploying
--------- =========
Enable Swift in /etc/kolla/globals.yml: Enable Swift in /etc/kolla/globals.yml:
:: ::
@ -146,7 +149,7 @@ is the minimal command to bring up Swift AIO, and it's dependencies:
--tags=rabbitmq,mariadb,keystone,swift --tags=rabbitmq,mariadb,keystone,swift
Validation Validation
---------- ==========
A very basic smoke test: A very basic smoke test:
:: ::

17
doc/vagrant-dev-env.rst
View File

@ -1,3 +1,6 @@
.. vagrant-dev-env:
====================================
Development Environment with Vagrant Development Environment with Vagrant
==================================== ====================================
@ -9,7 +12,7 @@ takes care of setting up CentOS-based VMs for Kolla development, each with
proper hardware like memory amount and number of network interfaces. proper hardware like memory amount and number of network interfaces.
Getting Started Getting Started
--------------- ===============
The Vagrant script implements All-in-One (AIO) or multi-node deployments. AIO The Vagrant script implements All-in-One (AIO) or multi-node deployments. AIO
is the default. is the default.
@ -91,7 +94,7 @@ The command ``vagrant status`` provides a quick overview of the VMs composing
the environment. the environment.
Vagrant Up Vagrant Up
---------- ==========
Once Vagrant has completed deploying all nodes, the next step is to launch Once Vagrant has completed deploying all nodes, the next step is to launch
Kolla. First, connect with the *operator* node:: Kolla. First, connect with the *operator* node::
@ -110,9 +113,8 @@ a different docker binary to the cluster. The shared folder is also used to
store the docker-registry files, so they are save from destructive operations store the docker-registry files, so they are save from destructive operations
like ``vagrant destroy``. like ``vagrant destroy``.
Building images Building images
^^^^^^^^^^^^^^^ ---------------
Once logged on the *operator* VM call the ``kolla-build`` utility:: Once logged on the *operator* VM call the ``kolla-build`` utility::
@ -122,10 +124,8 @@ Once logged on the *operator* VM call the ``kolla-build`` utility::
builds Docker images and pushes them to the local registry if the *push* builds Docker images and pushes them to the local registry if the *push*
option is enabled (in Vagrant this is the default behaviour). option is enabled (in Vagrant this is the default behaviour).
Deploying OpenStack with Kolla Deploying OpenStack with Kolla
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ------------------------------
Deploy AIO with:: Deploy AIO with::
@ -143,9 +143,8 @@ Validate OpenStack is operational::
Or navigate to http://10.10.10.254/ with a web browser. Or navigate to http://10.10.10.254/ with a web browser.
Further Reading Further Reading
--------------- ===============
All Vagrant documentation can be found at All Vagrant documentation can be found at
`docs.vagrantup.com <http://docs.vagrantup.com>`__. `docs.vagrantup.com <http://docs.vagrantup.com>`__.