Add doc8 test and improve rst syntax
This will test all rst files inside the doc directory for style issues with doc8 (an opinionated style checker for rst styles of documentation). This will fix all syntax issues identified by doc8 and will improve the syntax. Change-Id: Id1b9563e07e77e306aef5a0767c98c27f87c5c0e
This commit is contained in:
parent
f4a9667767
commit
c3d8262ec5
@ -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.
|
||||
|
@ -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:
|
||||
|
||||
::
|
||||
|
||||
|
@ -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
|
||||
|
@ -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.
|
||||
|
@ -89,7 +89,9 @@ 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.
|
||||
|
||||
.. note:: You must provide values for:
|
||||
|
||||
- ``ssh_key_name``
|
||||
- ``external_network_id``
|
||||
|
@ -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,7 +223,7 @@ 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
|
||||
.. 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
|
||||
|
@ -31,7 +31,8 @@ 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
|
||||
|
||||
.. 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,7 +78,7 @@ 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*
|
||||
.. 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.
|
||||
|
||||
|
@ -24,7 +24,7 @@ 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
|
||||
.. 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
|
||||
|
@ -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.
|
||||
|
@ -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,7 +628,7 @@ 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
|
||||
.. 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.
|
||||
|
@ -47,7 +47,7 @@ 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
|
||||
.. 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``
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user