Merge "Add doc8 test and improve rst syntax"
This commit is contained in:
commit
1160edb5e5
@ -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