Merge "Add doc8 test and improve rst syntax"

This commit is contained in:
Jenkins 2016-08-05 09:20:13 +00:00 committed by Gerrit Code Review
commit 1160edb5e5
15 changed files with 91 additions and 77 deletions

View File

@ -7,16 +7,16 @@ How To Contribute
Basics
======
#. Our source code is hosted on `OpenStack GitHub`_, but pull requests submitted
through GitHub will be ignored. Bugs should be filed on launchpad_,
not GitHub.
#. Our source code is hosted on `OpenStack GitHub`_, but pull requests
submitted through GitHub will be ignored. Bugs should be filed on
launchpad_, not GitHub.
#. Please follow OpenStack `Gerrit Workflow`_ to to contribute to Kolla.
#. Note the branch you're proposing changes to. ``master`` is the current focus
of development. Kolla project has a strict policy of only allowing backports
in ``stable/branch``, unless when not applicable. A bug in a ``stable/branch``
will first have to be fixed in ``master``.
in ``stable/branch``, unless when not applicable. A bug in a
``stable/branch`` will first have to be fixed in ``master``.
#. Please file a launchpad_ blueprint for any significant code change and a bug
for any significant bug fix or add a TrivialFix tag for simple changes.
@ -33,6 +33,6 @@ Development Environment
=======================
#. Please follow our `quickstart`_ to deploy your environment and test your
changes.
changes.
.. _quickstart: http://docs.openstack.org/developer/kolla/quickstart.html

View File

@ -67,7 +67,7 @@ TLS protection for the external VIP. TLS allows a client to authenticate
the OpenStack service endpoint and allows for encryption of the requests
and responses.
.. NOTE:: The kolla_internal_vip_address and kolla_external_vip_address must
.. note:: The kolla_internal_vip_address and kolla_external_vip_address must
be different to enable TLS on the external network.
The configuration variables that control TLS networking are:
@ -83,7 +83,7 @@ The default for TLS is disabled; to enable TLS networking:
kolla_external_fqdn_cert: "{{ node_config_directory }}/certificates/mycert.pem"
.. NOTE:: TLS authentication is based on certificates that have been
.. note:: TLS authentication is based on certificates that have been
signed by trusted Certificate Authorities. Examples of commercial
CAs are Comodo, Symantec, GoDaddy, and GlobalSign. Letsencrypt.org
is a CA that will provide trusted certificates at no charge. Many
@ -119,7 +119,7 @@ have settings similar to this:
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
trust CA, for example a development or internal test kolla deployment. In
@ -144,18 +144,19 @@ TODO(all) fill this section out
OpenStack Service Configuration in Kolla
========================================
.. NOTE:: As of now kolla only supports config overrides for ini based configs.
An operator can change the location where custom config files are read from by
editing ``/etc/kolla/globals.yml`` and adding the following line.
.. note:: As of now kolla only supports config overrides for ini based configs.
An operator can change the location where custom config files are read
from by editing ``/etc/kolla/globals.yml`` and adding the following
line.
::
# The directory to merge custom config files the kolla's config files
node_custom_config: "/etc/kolla/config"
Kolla allows the operator to override configuration of services. Kolla will look
for a file in ``/etc/kolla/config/<< sevice name >>/<< config file >>``. This
can be done per-project, per-service or per-service-on-specified-host.
Kolla allows the operator to override configuration of services. Kolla will
look for a file in ``/etc/kolla/config/<< sevice name >>/<< config file >>``.
This can be done per-project, per-service or per-service-on-specified-host.
For example to override scheduler_max_attempts in nova scheduler, the operator
needs to create ``/etc/kolla/config/nova/nova-scheduler.conf`` with content:
@ -173,8 +174,8 @@ on host myhost, the operator needs to create file
[DEFAULT]
ram_allocation_ratio = 5.0
The operator can make these changes after services were already deployed by using
following command:
The operator can make these changes after services were already deployed by
using following command:
::

View File

@ -74,8 +74,8 @@ RGW requires a healthy cluster in order to be successfully deployed. On initial
start up, RGW will create several pools. The first pool should be in an
operational state to proceed with the second one, and so on. So, in the case of
an **all-in-one** deployment, it is necessary to change the default number of
copies for the pools before deployment. Modify the file ``/etc/kolla/config/ceph.conf``
and add the contents::
copies for the pools before deployment. Modify the file
``/etc/kolla/config/ceph.conf`` and add the contents::
[global]
osd pool default size = 1
@ -129,8 +129,8 @@ must make the choice to use an erasure coded pool or a replicated pool
(the default) when you initially deploy. You cannot change this without
completely removing the pool and recreating it.
To enable erasure coded pools add the following options to your ``/etc/kolla/globals.yml``
configuration file:
To enable erasure coded pools add the following options to your
``/etc/kolla/globals.yml`` configuration file:
::
@ -189,8 +189,8 @@ The default pool Ceph creates is named **rbd**. It is safe to remove this pool:
Troubleshooting
===============
Deploy fails during 'Fetching Ceph keyrings ... No JSON object could be decoded'
--------------------------------------------------------------------------------
Deploy fails with 'Fetching Ceph keyrings ... No JSON object could be decoded'
------------------------------------------------------------------------------
If an initial deploy of Ceph fails, perhaps due to improper configuration or
similar, the cluster will be partially formed and will need to be reset for a

View File

@ -25,7 +25,7 @@ a real physical volume or a loopback mounted file for development.
present is via a Ceph deployment. If community members disagree
with this decision, please report the specific use case in the
Cinder bug tracker here:
`_bug 1571211 <https://launchpad.net/bugs/1571211>`__.
`_bug 1571211 <https://launchpad.net/bugs/1571211>`__.
Create a Volume Group

View File

@ -14,7 +14,7 @@ Requirements
* An existing installation of Ceph
* Existing Ceph storage pools
* Existing credentials in Ceph for OpenStack services to connect to Ceph
(Glance, Cinder, Nova)
(Glance, Cinder, Nova)
Enabling External Ceph
======================
@ -166,7 +166,9 @@ Put ceph.conf and keyring file into ``/etc/kolla/config/nova``:
$ ls /etc/kolla/config/nova
ceph.client.nova.keyring ceph.conf
Configure nova-compute to use Ceph as the ephemeral backend by creating ``/etc/kolla/config/nova/nova-compute.conf`` and adding the following contents:
Configure nova-compute to use Ceph as the ephemeral backend by creating
``/etc/kolla/config/nova/nova-compute.conf`` and adding the following
contents:
::
@ -176,4 +178,4 @@ Configure nova-compute to use Ceph as the ephemeral backend by creating ``/etc/k
images_rbd_ceph_conf=/etc/ceph/ceph.conf
rbd_user=nova
NOTE: rbd_user might vary depending on your environment.
.. note:: ``rbd_user`` might vary depending on your environment.

View File

@ -89,12 +89,14 @@ The container\_external\_subnet\_id: is the subnet equivalent to
container\_external\_network\_id
Review the parameters section of kollacluster.yaml for a full list of
configuration options. **Note:** You must provide values for:
configuration options.
- ``ssh_key_name``
- ``external_network_id``
- ``container_external_network_id``
- ``container_external_subnet_id``
.. note:: You must provide values for:
- ``ssh_key_name``
- ``external_network_id``
- ``container_external_network_id``
- ``container_external_subnet_id``
And then create the stack, referencing that environment file:

View File

@ -19,6 +19,7 @@ Install tox and generate the build configuration. The build configuration is
designed to hold advanced customizations when building containers.
Create kolla-build.conf using the following steps.
::
pip install tox
@ -59,7 +60,7 @@ command line::
kolla-build keystone
In this case, the build script builds all images which name contains the
*keystone* string along with their dependencies.
``keystone`` string along with their dependencies.
Multiple names may be specified on the command line::
@ -85,7 +86,7 @@ command::
tox -e genconfig
Build OpenStack from Source
Build OpenStack from source
===========================
When building images, there are two methods of the OpenStack install. One is
@ -112,7 +113,7 @@ the best use of the docker cache.
[keystone]
type = git
location = https://github.com/openstack/keystone
reference = stable/kilo
reference = stable/mitaka
[heat-base]
type = local
@ -122,11 +123,13 @@ the best use of the docker cache.
type = local
location = /tmp/ironic.tar.gz
To build RHEL containers, it is necessary to use the -i (include header)
To build RHEL containers, it is necessary to use the ``-i`` (include header)
feature to include registration with RHN of the container runtime operating
system. To obtain a RHN username/password/pool id, contact Red Hat.
First create a file called rhel-include::
First create a file called ``rhel-include``:
::
RUN subscription-manager register --user=<user-name> --password=<password> \
&& subscription-manager attach --pool <pool-id>
@ -140,13 +143,13 @@ Custom Repos
The build method allows the operator to build containers from custom repos.
The repos are accepted as a list of comma separated values and can be in
the form of .repo, .rpm, or a url. See examples below.
the form of ``.repo``, ``.rpm,`` or a URL. See examples below.
Update rpm_setup_config in ``/etc/kolla/kolla-build.conf``::
Update ``rpm_setup_config`` in ``/etc/kolla/kolla-build.conf``::
rpm_setup_config = http://trunk.rdoproject.org/centos7/currrent/delorean.repo,http://trunk.rdoproject.org/centos7/delorean-deps.repo
If specifying a .repo file, each .repo file will need to exist in the
If specifying a ``.repo`` file, each ``.repo`` file will need to exist in the
same directory as the base Dockerfile (kolla/docker/base)::
rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo
@ -187,7 +190,7 @@ image, the operator would add the following block to
Known issues
============
1. Can't build base image because docker fails to install systemd or httpd.
#. Can't build base image because docker fails to install systemd or httpd.
There are some issues between docker and AUFS. The simple workaround to
avoid the issue is that add ``-s devicemapper`` or ``-s btrfs`` to
@ -195,7 +198,7 @@ Known issues
tracker <https://github.com/docker/docker/issues/6980>`_ and `how to
configure Docker with BTRFS backend <https://docs.docker.com/engine/userguide/storagedriver/btrfs-driver/#prerequisites>`_.
2. Mirrors are unreliable.
#. Mirrors are unreliable.
Some of the mirrors Kolla uses can be unreliable. As a result occasionally
some containers fail to build. To rectify build problems, the build tool
@ -220,8 +223,8 @@ Running Docker registry is easy. Just use the following command::
docker run -d -p 4000:5000 --restart=always --name registry \
-v <local_data_path>:/var/lib/registry registry
Note: ``<local_data_path>`` points to the folder where Docker registry
will store Docker images on the local host.
.. note:: ``<local_data_path>`` points to the folder where Docker registry
will store Docker images on the local host.
The default port of Docker registry is 5000. But the 5000 port is also the port
of keystone-api. To avoid conflict, use 4000 port as Docker registry port.

View File

@ -31,8 +31,9 @@ following configuration:
#. Time-field name - Timestamp
After setting parameters, one can create an index with *Create* button.
Note: This step is necessary until the default Kibana dashboard is implemented
in Kolla.
.. note:: This step is necessary until the default Kibana dashboard is implemented
in Kolla.
Search logs - Discover tab
==========================
@ -63,9 +64,9 @@ generated and previewed. In the menu on the left, metrics for a chart can
be chosen. The chart can be generated by pressing a green arrow on the top
of the left-side menu.
NOTE: After creating a visualization, it can be saved by choosing *save
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.
.. note:: After creating a visualization, it can be saved by choosing *save
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.
Organize visualizations and searches - Dashboard tab
====================================================
@ -77,9 +78,9 @@ from all saved ones. The order and size of elements can be changed directly
in this place by moving them or resizing. The color of charts can also be
changed by checking a colorful dots on the legend near each visualization.
NOTE: After creating a dashboard, it can be saved by choosing *save dashboard*
option in the menu on the right. If it is not saved, it will be lost after
leaving a page or creating another dashboard.
.. note:: After creating a dashboard, it can be saved by choosing *save dashboard*
option in the menu on the right. If it is not saved, it will be lost after
leaving a page or creating another dashboard.
If a Dashboard has already been saved, it can be opened by choosing *open
dashboard* option in the menu on the right.

View File

@ -24,8 +24,8 @@ with version greater than 2.3, do the following:
docker run -d -p 4000:5000 --restart=always --name registry registry:2
Note: Kolla looks for the Docker registry to use port 4000. (Docker default is
port 5000)
.. note:: Kolla looks for the Docker registry to use port 4000. (Docker default is
port 5000)
After starting the registry, it is necessary to instruct Docker that it will
be communicating with an insecure registry. To enable insecure registry
@ -52,7 +52,7 @@ Edit ``/etc/default/docker`` and add:
# Ubuntu
DOCKER_OPTS="--insecure-registry 192.168.1.100:4000"
If ubuntu is using systemd, additional settings needs to be configured.
If ubuntu is using systemd, additional settings needs to be configured.
Copy docker's systemd unit file to ``/etc/systemd/system/`` directory:
::
@ -60,7 +60,7 @@ Copy docker's systemd unit file to ``/etc/systemd/system/`` directory:
# cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service
Next, modify ``/etc/systemd/system/docker.service``, add ``environmentFile``
variable and add ``$DOCKER_OPTS`` to the end of ExecStart in ``[Service]``
variable and add ``$DOCKER_OPTS`` to the end of ExecStart in ``[Service]``
section:
::

View File

@ -49,16 +49,16 @@ Then run the command to upgrade::
kolla-ansible upgrade
.. NOTE:: Varying degrees of success have been reported with upgrading
.. note:: Varying degrees of success have been reported with upgrading
the libvirt container with a running virtual machine in it. The libvirt
upgrade still needs a bit more validation, but the Kolla community feels
confident this mechanism can be used with the correct Docker graph driver.
.. NOTE:: The Kolla community recommends the btrfs or aufs graph drivers for
.. note:: The Kolla community recommends the btrfs or aufs graph drivers for
storing data as sometimes the LVM graph driver loses track of its reference
counting and results in an unremovable container.
.. NOTE:: Because of system technical limitations, upgrade of a libvirt
.. note:: Because of system technical limitations, upgrade of a libvirt
container when using software emulation (``virt_driver=qemu`` in nova.conf),
does not work at all. This is acceptable because KVM is the recommended
virtualization driver to use with Nova.

View File

@ -16,7 +16,7 @@ The recommended deployment target requirements:
- At least 8gb main memory
- At least 40gb disk space.
.. 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
=======================
@ -24,7 +24,8 @@ Recommended Environment
If developing or evaluating Kolla, the community strongly recommends using bare
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.
There are other deployment environments referenced below in `Additional Environments`_.
There are other deployment environments referenced below in
`Additional Environments`_.
Install Dependencies
====================
@ -48,7 +49,7 @@ and OverlayFS. In order to update kernel in Ubuntu 14.04 LTS to 4.2, run:
apt-get -y install linux-image-generic-lts-wily
.. NOTE:: Install is *very* sensitive about version of components. Please
.. note:: Install is *very* sensitive about version of components. Please
review carefully because default Operating System repos are likely out of
date.
@ -61,7 +62,8 @@ Docker Python 1.6.0 none On target nodes
Python Jinja2 2.8.0 none On deployment host
===================== =========== =========== =========================
Make sure the ``pip`` package manager is installed and upgraded to latest before proceeding:
Make sure the ``pip`` package manager is installed and upgraded to latest
before proceeding:
::
@ -124,17 +126,17 @@ For Ubuntu 14.04 which uses upstart instead of systemd, run the following:
mount --make-shared /run
.. NOTE:: If centos/fedora/oraclelinux container images are built on an Ubuntu
.. note:: If centos/fedora/oraclelinux container images are built on an Ubuntu
host, the backend storage driver must not be AUFS (see the known issues in
:doc:`image-building`).
.. NOTE:: On ubuntu 16.04, please uninstall ``lxd`` and ``lxc`` packages. (issue
.. note:: On ubuntu 16.04, please uninstall ``lxd`` and ``lxc`` packages. (issue
with cgroup mounts, mounts exponentially increasing when restarting container).
On the target hosts you also need an updated version of the Docker python
libraries:
.. NOTE:: The old docker-python is obsoleted by python-docker-py.
.. note:: The old docker-python is obsoleted by python-docker-py.
::
@ -402,8 +404,8 @@ deployment. Optionally, the passwords may be populate in the file by hand.
Start by editing ``/etc/kolla/globals.yml``. Check and edit, if needed, these
parameters: ``kolla_base_distro``, ``kolla_install_type``. These parameters
should match what you used in the ``kolla-build`` command line. The default for
``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is ``binary``.
If you want to use ubuntu with source type, then you should make
``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is
``binary``. If you want to use ubuntu with source type, then you should make
sure ``globals.yml`` has the following entries:
::
@ -479,7 +481,7 @@ In order to see all available parameters, run:
kolla-ansible -h
.. NOTE:: In case of deploying using the _nested_ environment (*eg*.
.. note:: In case of deploying using the _nested_ environment (*eg*.
Using Virtualbox VM's, KVM VM's), if your compute node supports
hardware acceleration for virtual machines.
@ -626,10 +628,10 @@ The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``
values are overridden, in ``/etc/kolla/globals.yml``. The value of
``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.
Note: When you log in to Kibana web interface for the first time, you are
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
Kolla.
.. note:: When you log in to Kibana web interface for the first time, you are
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
Kolla.
.. _Docker Hub Image Registry: https://hub.docker.com/u/kolla/
.. _launchpad bug: https://bugs.launchpad.net/kolla/+filebug

View File

@ -34,7 +34,7 @@ Another solution to the persistent data issue is to use a host bind mount which
involves making, for sake of example, host directory ``var/lib/mysql``
available inside the container at ``var/lib/mysql``. This absolutely solves the
problem of persistent data, but it introduces another security issue,
permissions. With this host bind mount solution the data in ``var/lib/mysql``
permissions. With this host bind mount solution the data in ``var/lib/mysql``
will be owned by the mysql user in the container. Unfortunately, that mysql
user in the container could have any UID/GID and thats who will own the data
outside the container introducing a potential security risk. Additionally, this

View File

@ -47,8 +47,8 @@ On Ubuntu 14.04 it is as easy as::
sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt libvirt-dev nfs-kernel-server
**Note:** Many distros ship outdated versions of Vagrant by default. When in
doubt, always install the latest from the downloads page above.
.. note:: Many distros ship outdated versions of Vagrant by default. When in
doubt, always install the latest from the downloads page above.
Next install the hostmanager plugin so all hosts are recorded in ``/etc/hosts``
(inside each vm)::

View File

@ -3,6 +3,7 @@
# process, which may cause wedges in the gate later.
bandit>=1.0.1 # Apache-2.0
bashate>=0.2 # Apache-2.0
doc8 # Apache-2.0
hacking>=0.10.0
oslo.log>=1.14.0 # Apache-2.0
oslotest>=1.10.0 # Apache-2.0

View File

@ -32,7 +32,9 @@ commands = bandit -r ansible/library dev docker kolla tests tools
commands = {posargs}
[testenv:docs]
commands = python setup.py build_sphinx
commands =
doc8 doc
python setup.py build_sphinx
[testenv:setupenv]
commands =