Upgrade the rst convention of the Admin Guide
We upgrade the rst convention by following Documentation Contributor Guide[1]. [1] https://docs.openstack.org/doc-contrib-guide Change-Id: I89e437b83b0e6a7c1bbfbf4a02a530be072eca91 Partially-Implements: blueprint optimize-the-documentation-format
This commit is contained in:
chenxing
parent
b66ebff65e
commit
73f2bce552
@ -5,91 +5,106 @@ Advanced Configuration
|
||||
======================
|
||||
|
||||
Endpoint Network Configuration
|
||||
==============================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When an OpenStack cloud is deployed, the REST API of each service is presented
|
||||
as a series of endpoints. These endpoints are the admin URL, the internal
|
||||
URL, and the external URL.
|
||||
|
||||
Kolla offers two options for assigning these endpoints to network addresses:
|
||||
- Combined - Where all three endpoints share the same IP address
|
||||
- Separate - Where the external URL is assigned to an IP address that is
|
||||
different than the IP address shared by the internal and admin URLs
|
||||
- Combined - Where all three endpoints share the same IP address
|
||||
- Separate - Where the external URL is assigned to an IP address that is
|
||||
different than the IP address shared by the internal and admin URLs
|
||||
|
||||
The configuration parameters related to these options are:
|
||||
- kolla_internal_vip_address
|
||||
- network_interface
|
||||
- kolla_external_vip_address
|
||||
- kolla_external_vip_interface
|
||||
- kolla_internal_vip_address
|
||||
- network_interface
|
||||
- kolla_external_vip_address
|
||||
- kolla_external_vip_interface
|
||||
|
||||
For the combined option, set the two variables below, while allowing the
|
||||
other two to accept their default values. In this configuration all REST
|
||||
API requests, internal and external, will flow over the same network. ::
|
||||
API requests, internal and external, will flow over the same network.
|
||||
|
||||
kolla_internal_vip_address: "10.10.10.254"
|
||||
network_interface: "eth0"
|
||||
.. code-block:: none
|
||||
|
||||
kolla_internal_vip_address: "10.10.10.254"
|
||||
network_interface: "eth0"
|
||||
|
||||
.. end
|
||||
|
||||
For the separate option, set these four variables. In this configuration
|
||||
the internal and external REST API requests can flow over separate
|
||||
networks. ::
|
||||
networks.
|
||||
|
||||
kolla_internal_vip_address: "10.10.10.254"
|
||||
network_interface: "eth0"
|
||||
kolla_external_vip_address: "10.10.20.254"
|
||||
kolla_external_vip_interface: "eth1"
|
||||
.. code-block:: none
|
||||
|
||||
kolla_internal_vip_address: "10.10.10.254"
|
||||
network_interface: "eth0"
|
||||
kolla_external_vip_address: "10.10.20.254"
|
||||
kolla_external_vip_interface: "eth1"
|
||||
|
||||
.. end
|
||||
|
||||
Fully Qualified Domain Name Configuration
|
||||
=========================================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
If you prefer to use names to address the endpoints in your kolla
|
||||
deployment use the variables:
|
||||
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 deployment use the variables:
|
||||
|
||||
- kolla_internal_fqdn
|
||||
- kolla_external_fqdn
|
||||
- kolla_internal_fqdn
|
||||
- kolla_external_fqdn
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
kolla_internal_fqdn: inside.mykolla.example.net
|
||||
kolla_external_fqdn: mykolla.example.net
|
||||
kolla_internal_fqdn: inside.mykolla.example.net
|
||||
kolla_external_fqdn: mykolla.example.net
|
||||
|
||||
.. end
|
||||
|
||||
Provisions must be taken outside of kolla for these names to map to the
|
||||
configured IP addresses. Using a DNS server or the /etc/hosts file are
|
||||
two ways to create this mapping.
|
||||
configured IP addresses. Using a DNS server or the ``/etc/hosts`` file
|
||||
are two ways to create this mapping.
|
||||
|
||||
RabbitMQ Hostname Resolution
|
||||
============================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
RabbitMQ doesn't work with IP address, hence the IP address of api_interface
|
||||
should be resolvable by hostnames to make sure that all RabbitMQ Cluster hosts
|
||||
can resolve each others hostname beforehand.
|
||||
RabbitMQ doesn't work with IP address, hence the IP address of
|
||||
``api_interface`` should be resolvable by hostnames to make sure that
|
||||
all RabbitMQ Cluster hosts can resolve each others hostname beforehand.
|
||||
|
||||
TLS Configuration
|
||||
=================
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
An additional endpoint configuration option is to enable or disable
|
||||
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:
|
||||
|
||||
- kolla_enable_tls_external
|
||||
- kolla_external_fqdn_cert
|
||||
- kolla_enable_tls_external
|
||||
- kolla_external_fqdn_cert
|
||||
|
||||
The default for TLS is disabled; to enable TLS networking:
|
||||
The default for TLS is disabled, to enable TLS networking:
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
kolla_enable_tls_external: "yes"
|
||||
kolla_external_fqdn_cert: "{{ node_config_directory }}/certificates/mycert.pem"
|
||||
kolla_enable_tls_external: "yes"
|
||||
kolla_external_fqdn_cert: "{{ node_config_directory }}/certificates/mycert.pem"
|
||||
|
||||
.. end
|
||||
|
||||
.. 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
|
||||
@ -97,8 +112,9 @@ The default for TLS is disabled; to enable TLS networking:
|
||||
company's domain. If using a trusted CA is not possible for your
|
||||
situation, you can use OpenSSL to create your own or see the section
|
||||
company's domain. If using a trusted CA is not possible for your
|
||||
situation, you can use `OpenSSL`_ to create your own or see the section
|
||||
below about kolla generated self-signed certificates.
|
||||
situation, you can use `OpenSSL <https://www.openssl.org>`__
|
||||
to create your own or see the section below about kolla
|
||||
generated self-signed certificates.
|
||||
|
||||
Two certificate files are required to use TLS securely with authentication.
|
||||
These two files will be provided by your Certificate Authority. These
|
||||
@ -112,24 +128,26 @@ need to be distributed to the client.
|
||||
When using TLS to connect to a public endpoint, an OpenStack client will
|
||||
have settings similar to this:
|
||||
|
||||
::
|
||||
.. code-block:: shell
|
||||
|
||||
export OS_PROJECT_DOMAIN_ID=default
|
||||
export OS_USER_DOMAIN_ID=default
|
||||
export OS_PROJECT_NAME=demo
|
||||
export OS_USERNAME=demo
|
||||
export OS_PASSWORD=demo-password
|
||||
export OS_AUTH_URL=https://mykolla.example.net:5000
|
||||
# os_cacert is optional for trusted certificates
|
||||
export OS_CACERT=/etc/pki/mykolla-cacert.crt
|
||||
export OS_IDENTITY_API_VERSION=3
|
||||
export OS_PROJECT_DOMAIN_ID=default
|
||||
export OS_USER_DOMAIN_ID=default
|
||||
export OS_PROJECT_NAME=demo
|
||||
export OS_USERNAME=demo
|
||||
export OS_PASSWORD=demo-password
|
||||
export OS_AUTH_URL=https://mykolla.example.net:5000
|
||||
# os_cacert is optional for trusted certificates
|
||||
export OS_CACERT=/etc/pki/mykolla-cacert.crt
|
||||
export OS_IDENTITY_API_VERSION=3
|
||||
|
||||
.. _OpenSSL: https://www.openssl.org/
|
||||
.. end
|
||||
|
||||
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
|
||||
@ -139,9 +157,9 @@ For convenience, the ``kolla-ansible`` command will generate the necessary
|
||||
certificate files based on the information in the ``globals.yml``
|
||||
configuration file:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
kolla-ansible certificates
|
||||
kolla-ansible certificates
|
||||
|
||||
The files haproxy.pem and haproxy-ca.pem will be generated and stored
|
||||
in the ``/etc/kolla/certificates/`` directory.
|
||||
@ -149,14 +167,16 @@ in the ``/etc/kolla/certificates/`` directory.
|
||||
.. _service-config:
|
||||
|
||||
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.
|
||||
|
||||
An operator can change the location where custom config files are read from by
|
||||
editing ``/etc/kolla/globals.yml`` and adding the following line.
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
# The directory to merge custom config files the kolla's config files
|
||||
node_custom_config: "/etc/kolla/config"
|
||||
@ -167,32 +187,41 @@ 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:
|
||||
|
||||
::
|
||||
.. path /etc/kolla/config/nova/nova-scheduler.conf
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
scheduler_max_attempts = 100
|
||||
|
||||
.. end
|
||||
|
||||
If the operator wants to configure compute node cpu and ram allocation ratio
|
||||
on host myhost, the operator needs to create file
|
||||
``/etc/kolla/config/nova/myhost/nova.conf`` with content:
|
||||
|
||||
::
|
||||
.. path /etc/kolla/config/nova/myhost/nova.conf
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
cpu_allocation_ratio = 16.0
|
||||
ram_allocation_ratio = 5.0
|
||||
|
||||
.. end
|
||||
|
||||
Kolla allows the operator to override configuration globally for all services.
|
||||
It will look for a file called ``/etc/kolla/config/global.conf``.
|
||||
|
||||
For example to modify database pool size connection for all services, the
|
||||
operator needs to create ``/etc/kolla/config/global.conf`` with content:
|
||||
|
||||
::
|
||||
.. path /etc/kolla/config/global.conf
|
||||
.. code-block:: ini
|
||||
|
||||
[database]
|
||||
max_pool_size = 100
|
||||
|
||||
.. end
|
||||
|
||||
In case the operators want to customize ``policy.json`` file, they should
|
||||
create a full policy file for specific project in the same directory like above
|
||||
and Kolla will overwrite default policy file with it. Be aware, with some
|
||||
@ -204,72 +233,87 @@ For example to overwrite ``policy.json`` file of Neutron project, the operator
|
||||
needs to grab ``policy.json`` from Neutron project source code, update rules
|
||||
and then put it to ``/etc/kolla/config/neutron/policy.json``.
|
||||
|
||||
.. note:: Currently kolla-ansible only support JSON format for policy file.
|
||||
.. note::
|
||||
|
||||
Currently kolla-ansible only support JSON format for policy file.
|
||||
|
||||
The operator can make these changes after services were already deployed by
|
||||
using following command:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
kolla-ansible reconfigure
|
||||
kolla-ansible reconfigure
|
||||
|
||||
.. end
|
||||
|
||||
IP Address Constrained Environments
|
||||
===================================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
adding:
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
enable_haproxy: "no"
|
||||
enable_haproxy: "no"
|
||||
|
||||
.. end
|
||||
|
||||
Note this method is not recommended and generally not tested by the
|
||||
Kolla community, but included since sometimes a free IP is not available
|
||||
in a testing environment.
|
||||
|
||||
External Elasticsearch/Kibana environment
|
||||
=========================================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
It is possible to use an external Elasticsearch/Kibana environment. To do this
|
||||
first disable the deployment of the central logging.
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
enable_central_logging: "no"
|
||||
enable_central_logging: "no"
|
||||
|
||||
.. end
|
||||
|
||||
Now you can use the parameter ``elasticsearch_address`` to configure the
|
||||
address of the external Elasticsearch environment.
|
||||
|
||||
Non-default <service> port
|
||||
==========================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
It is sometimes required to use a different than default port
|
||||
for service(s) in Kolla. It is possible with setting <service>_port
|
||||
in ``globals.yml`` file.
|
||||
For example:
|
||||
::
|
||||
for service(s) in Kolla. It is possible with setting
|
||||
``<service>_port`` in ``globals.yml`` file. For example:
|
||||
|
||||
database_port: 3307
|
||||
.. code-block:: none
|
||||
|
||||
As <service>_port value is saved in different services' configuration so
|
||||
database_port: 3307
|
||||
|
||||
.. end
|
||||
|
||||
As ``<service>_port`` value is saved in different services' configuration so
|
||||
it's advised to make above change before deploying.
|
||||
|
||||
Use an external Syslog server
|
||||
=============================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default, Fluentd is used as a syslog server to collect Swift and HAProxy
|
||||
logs. When Fluentd is disabled or you want to use an external syslog server,
|
||||
You can set syslog parameters in ``globals.yml`` file.
|
||||
For example:
|
||||
::
|
||||
You can set syslog parameters in ``globals.yml`` file. For example:
|
||||
|
||||
syslog_server: "172.29.9.145"
|
||||
syslog_udp_port: "514"
|
||||
.. code-block:: none
|
||||
|
||||
You can also set syslog facility names for Swift and HAProxy logs. By default,
|
||||
Swift and HAProxy use ``local0`` and ``local1``, respectively.
|
||||
::
|
||||
syslog_server: "172.29.9.145"
|
||||
syslog_udp_port: "514"
|
||||
|
||||
syslog_swift_facility: "local0"
|
||||
syslog_haproxy_facility: "local1"
|
||||
.. end
|
||||
|
||||
You can also set syslog facility names for Swift and HAProxy logs.
|
||||
By default, Swift and HAProxy use ``local0`` and ``local1``, respectively.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
syslog_swift_facility: "local0"
|
||||
syslog_haproxy_facility: "local1"
|
||||
|
||||
.. end
|
||||
|
||||
@ -5,7 +5,7 @@ Kolla's Deployment Philosophy
|
||||
=============================
|
||||
|
||||
Overview
|
||||
========
|
||||
~~~~~~~~
|
||||
|
||||
Kolla has an objective to replace the inflexible, painful, resource-intensive
|
||||
deployment process of OpenStack with a flexible, painless, inexpensive
|
||||
@ -23,7 +23,7 @@ OpenStack services increases, Kolla offers full capability to override every
|
||||
OpenStack service configuration option in the deployment.
|
||||
|
||||
Why not Template Customization?
|
||||
===============================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Kolla upstream community does not want to place key/value pairs in the
|
||||
Ansible playbook configuration options that are not essential to obtaining
|
||||
@ -39,7 +39,7 @@ Essentially templating in configuration options is not a scalable solution
|
||||
and would result in an inability of the project to execute its mission.
|
||||
|
||||
Kolla's Solution to Customization
|
||||
=================================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Rather than deal with the customization madness of templating configuration
|
||||
options in Kolla's Ansible playbooks, Kolla eliminates all the inefficiencies
|
||||
@ -56,11 +56,16 @@ configuration options documentation is extremely mature and well-formulated.
|
||||
As an example, consider running Kolla in a virtual machine. In order to
|
||||
launch virtual machines from Nova in a virtual environment, it is necessary
|
||||
to use the QEMU hypervisor, rather than the KVM hypervisor. To achieve this
|
||||
result, simply `mkdir -p /etc/kolla/config` and modify the file
|
||||
`/etc/kolla/config/nova.conf` with the contents::
|
||||
result, simply :command:`mkdir -p /etc/kolla/config` and modify the file
|
||||
`/etc/kolla/config/nova.conf` with the contents
|
||||
|
||||
[libvirt]
|
||||
virt_type=qemu
|
||||
.. path /etc/kolla/config/nova.conf
|
||||
.. code-block:: ini
|
||||
|
||||
[libvirt]
|
||||
virt_type=qemu
|
||||
|
||||
.. end
|
||||
|
||||
After this change Kolla will use an emulated hypervisor with lower performance.
|
||||
Kolla could have templated this commonly modified configuration option. If
|
||||
|
||||
@ -1,8 +1,9 @@
|
||||
============
|
||||
Admin Guides
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
advanced-configuration
|
||||
production-architecture-guide
|
||||
|
||||
@ -9,7 +9,7 @@ meant to answer some questions regarding basic configuration options that Kolla
|
||||
requires. This document also contains other useful pointers.
|
||||
|
||||
Node types and services running on them
|
||||
=======================================
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A basic Kolla inventory consists of several types of nodes, known in Ansible as
|
||||
``groups``.
|
||||
@ -30,12 +30,12 @@ A basic Kolla inventory consists of several types of nodes, known in Ansible as
|
||||
* Monitoring - Monitor nodes which host monitoring services.
|
||||
|
||||
Network configuration
|
||||
=====================
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. _interface-configuration:
|
||||
|
||||
Interface configuration
|
||||
***********************
|
||||
-----------------------
|
||||
|
||||
In Kolla operators should configure following network interfaces:
|
||||
|
||||
@ -80,21 +80,21 @@ In Kolla operators should configure following network interfaces:
|
||||
with the bare metal cloud hosts in order to provide DHCP leases with
|
||||
PXE boot options. Defaults to ``network_interface``.
|
||||
|
||||
.. WARNING::
|
||||
.. warning::
|
||||
|
||||
Ansible facts does not recognize interface names containing dashes,
|
||||
in example ``br-ex`` or ``bond-0`` cannot be used because ansible will read
|
||||
them as ``br_ex`` and ``bond_0`` respectively.
|
||||
|
||||
Docker configuration
|
||||
====================
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Because Docker is core dependency of Kolla, proper configuration of Docker can
|
||||
change the experience of Kolla significantly. Following section will highlight
|
||||
several Docker configuration details relevant to Kolla operators.
|
||||
|
||||
Storage driver
|
||||
**************
|
||||
--------------
|
||||
|
||||
In certain distributions Docker storage driver defaults to devicemapper, which
|
||||
can heavily hit performance of builds and deploys. We suggest to use btrfs or
|
||||
@ -102,14 +102,11 @@ aufs as driver. More details on which storage driver to use in
|
||||
`Docker documentation <https://docs.docker.com/engine/userguide/storagedriver/selectadriver/>`_.
|
||||
|
||||
Volumes
|
||||
*******
|
||||
-------
|
||||
|
||||
Kolla puts nearly all of persistent data in Docker volumes. These volumes are
|
||||
created in Docker working directory, which defaults to
|
||||
|
||||
::
|
||||
|
||||
/var/lib/docker
|
||||
created in Docker working directory, which defaults to ``/var/lib/docker``
|
||||
directory.
|
||||
|
||||
We recommend to ensure that this directory has enough space and is placed on
|
||||
fast disk as it will affect performance of builds, deploys as well as database
|
||||
|
||||
Loading…
Reference in New Issue
Block a user