openstack/openstack-ansible
Code Issues Proposed changes

[Docs] Merge advanced configuration into reference

Browse Source 
The deploy guide also have appendixes pointing to the reference,
which were pointing back to the deploy guide. This is very
hard to follow. The advanced configurations and inventory should
be merged into our reference guide, to avoid duplications.

Change-Id: I2d1e653036d380c3eae6a3a4906d1db890baecb2
This commit is contained in:
Jean-Philippe Evrard 2018-02-19 11:26:55 +00:00
parent 6435ec7521
commit ba7e064ef9
6 changed files with 329 additions and 364 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
deploy-guide/source/app-advanced-config-affinity.rst
View File

@ -1,50 +0,0 @@
========
Affinity
========
When OpenStack-Ansible generates its dynamic inventory, the affinity
setting determines how many containers of a similar type are deployed on a
single physical host.
Using ``shared-infra_hosts`` as an example, consider this
``openstack_user_config.yml`` configuration:
.. code-block:: yaml
shared-infra_hosts:
infra1:
ip: 172.29.236.101
infra2:
ip: 172.29.236.102
infra3:
ip: 172.29.236.103
Three hosts are assigned to the `shared-infra_hosts` group,
OpenStack-Ansible ensures that each host runs a single database container,
a single Memcached container, and a single RabbitMQ container. Each host has
an affinity of 1 by default, which means that each host runs one of each
container type.
If you are deploying a stand-alone Object Storage (swift) environment,
you can skip the deployment of RabbitMQ. If you use this configuration,
your ``openstack_user_config.yml`` file would look as follows:
.. code-block:: yaml
shared-infra_hosts:
infra1:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.101
infra2:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.102
infra3:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.103
This configuration deploys a Memcached container and a database container
on each host, but no RabbitMQ containers.

12
deploy-guide/source/app-advanced-config-options.rst
View File

@ -1,12 +0,0 @@
==================================
Appendix I: Advanced configuration
==================================
.. TODO: include intro on what advanced configuration is, whether it’s required
or optional, and when someone should do it
.. toctree::
:maxdepth: 2
app-advanced-config-override
app-advanced-config-affinity

270
deploy-guide/source/app-advanced-config-override.rst
View File

@ -1,270 +0,0 @@
===========================================
Overriding OpenStack configuration defaults
===========================================
OpenStack has many configuration options available in ``.conf`` files
(in a standard ``INI`` file format),
policy files (in a standard ``JSON`` format) and ``YAML`` files.
.. note::
``YAML`` files are only in the ceilometer project at this time.
OpenStack-Ansible enables you to reference any options in the
`OpenStack Configuration Reference`_ through the use of a simple set of
configuration entries in the ``/etc/openstack_deploy/user_variables.yml``.
This section describes how to use the configuration entries in the
``/etc/openstack_deploy/user_variables.yml`` file to override default
configuration settings. For more information, see the
:dev_docs:`Setting overrides in configuration files
<extending.html#setting-overrides-in-configuration-files>` section in the
developer documentation.
.. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/
Overriding .conf files
~~~~~~~~~~~~~~~~~~~~~~
Most often, overrides are implemented for the ``<service>.conf`` files
(for example, ``nova.conf``). These files use a standard INI file format.
For example, you might want to add the following parameters to the
``nova.conf`` file:
.. code-block:: ini
[DEFAULT]
remove_unused_original_minimum_age_seconds = 43200
[libvirt]
cpu_mode = host-model
disk_cachemodes = file=directsync,block=none
[database]
idle_timeout = 300
max_pool_size = 10
To do this, you use the following configuration entry in the
``/etc/openstack_deploy/user_variables.yml`` file:
.. code-block:: yaml
nova_nova_conf_overrides:
DEFAULT:
remove_unused_original_minimum_age_seconds: 43200
libvirt:
cpu_mode: host-model
disk_cachemodes: file=directsync,block=none
database:
idle_timeout: 300
max_pool_size: 10
.. note::
The general format for the variable names used for overrides is
``<service>_<filename>_<file extension>_overrides``. For example, the variable
name used in these examples to add parameters to the ``nova.conf`` file is
``nova_nova_conf_overrides``.
You can also apply overrides on a per-host basis with the following
configuration in the ``/etc/openstack_deploy/openstack_user_config.yml``
file:
.. code-block:: yaml
compute_hosts:
900089-compute001:
ip: 192.0.2.10
host_vars:
nova_nova_conf_overrides:
DEFAULT:
remove_unused_original_minimum_age_seconds: 43200
libvirt:
cpu_mode: host-model
disk_cachemodes: file=directsync,block=none
database:
idle_timeout: 300
max_pool_size: 10
Use this method for any files with the ``INI`` format for in OpenStack projects
deployed in OpenStack-Ansible.
Overriding .json files
~~~~~~~~~~~~~~~~~~~~~~
To implement access controls that are different from the ones in a standard
OpenStack environment, you can adjust the default policies applied by services.
Policy files are in a ``JSON`` format.
For example, you might want to add the following policy in the ``policy.json``
file for the Identity service (keystone):
.. code-block:: json
{
"identity:foo": "rule:admin_required",
"identity:bar": "rule:admin_required"
}
To do this, you use the following configuration entry in the
``/etc/openstack_deploy/user_variables.yml`` file:
.. code-block:: yaml
keystone_policy_overrides:
identity:foo: "rule:admin_required"
identity:bar: "rule:admin_required"
.. note::
The general format for the variable names used for overrides is
``<service>_policy_overrides``. For example, the variable name used in this
example to add a policy to the Identity service (keystone) ``policy.json`` file
is ``keystone_policy_overrides``.
Use this method for any files with the ``JSON`` format in OpenStack projects
deployed in OpenStack-Ansible.
To assist you in finding the appropriate variable name to use for
overrides, the general format for the variable name is
``<service>_policy_overrides``.
Overriding .yml files
~~~~~~~~~~~~~~~~~~~~~
You can override ``.yml`` file values by supplying replacement YAML content.
.. note::
All default YAML file content is completely overwritten by the overrides,
so the entire YAML source (both the existing content and your changes)
must be provided.
For example, you might want to define a meter exclusion for all hardware
items in the default content of the ``pipeline.yml`` file for the
Telemetry service (ceilometer):
.. code-block:: yaml
sources:
- name: meter_source
interval: 600
meters:
- "!hardware.*"
sinks:
- meter_sink
- name: foo_source
value: foo
To do this, you use the following configuration entry in the
``/etc/openstack_deploy/user_variables.yml`` file:
.. code-block:: yaml
ceilometer_pipeline_yaml_overrides:
sources:
- name: meter_source
interval: 600
meters:
- "!hardware.*"
sinks:
- meter_sink
- name: source_foo
value: foo
.. note::
The general format for the variable names used for overrides is
``<service>_<filename>_<file extension>_overrides``. For example, the variable
name used in this example to define a meter exclusion in the ``pipeline.yml`` file
for the Telemetry service (ceilometer) is ``ceilometer_pipeline_yaml_overrides``.
Currently available overrides
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following override variables are available.
Galera:
* galera_client_my_cnf_overrides
* galera_my_cnf_overrides
* galera_cluster_cnf_overrides
* galera_debian_cnf_overrides
Telemetry service (ceilometer):
* ceilometer_policy_overrides
* ceilometer_ceilometer_conf_overrides
* ceilometer_event_definitions_yaml_overrides
* ceilometer_event_pipeline_yaml_overrides
* ceilometer_pipeline_yaml_overrides
Block Storage (cinder):
* cinder_policy_overrides
* cinder_rootwrap_conf_overrides
* cinder_api_paste_ini_overrides
* cinder_cinder_conf_overrides
Image service (glance):
* glance_glance_api_paste_ini_overrides
* glance_glance_api_conf_overrides
* glance_glance_cache_conf_overrides
* glance_glance_manage_conf_overrides
* glance_glance_registry_paste_ini_overrides
* glance_glance_registry_conf_overrides
* glance_glance_scrubber_conf_overrides
* glance_glance_scheme_json_overrides
* glance_policy_overrides
Orchestration service (heat):
* heat_heat_conf_overrides
* heat_api_paste_ini_overrides
* heat_default_yaml_overrides
* heat_aws_rds_dbinstance_yaml_overrides
* heat_policy_overrides
Identity service (keystone):
* keystone_keystone_conf_overrides
* keystone_keystone_default_conf_overrides
* keystone_keystone_paste_ini_overrides
* keystone_policy_overrides
Networking service (neutron):
* neutron_neutron_conf_overrides
* neutron_ml2_conf_ini_overrides
* neutron_dhcp_agent_ini_overrides
* neutron_api_paste_ini_overrides
* neutron_rootwrap_conf_overrides
* neutron_policy_overrides
* neutron_dnsmasq_neutron_conf_overrides
* neutron_l3_agent_ini_overrides
* neutron_metadata_agent_ini_overrides
* neutron_metering_agent_ini_overrides
Compute service (nova):
* nova_nova_conf_overrides
* nova_rootwrap_conf_overrides
* nova_api_paste_ini_overrides
* nova_policy_overrides
Object Storage service (swift):
* swift_swift_conf_overrides
* swift_swift_dispersion_conf_overrides
* swift_proxy_server_conf_overrides
* swift_account_server_conf_overrides
* swift_account_server_replicator_conf_overrides
* swift_container_server_conf_overrides
* swift_container_server_replicator_conf_overrides
* swift_object_server_conf_overrides
* swift_object_server_replicator_conf_overrides
Tempest:
* tempest_tempest_conf_overrides
pip:
* pip_global_conf_overrides
.. note::
Possible additional overrides can be found in the "Tunable Section"
of each role's ``main.yml`` file, such as
``/etc/ansible/roles/role_name/defaults/main.yml``.

3
deploy-guide/source/app.rst
View File

@ -13,7 +13,6 @@ Appendices
app-security.rst
app-networking.rst
app-limited-connectivity.rst
app-advanced-config-sslcertificates
app-advanced-config-options.rst
app-advanced-config-sslcertificates.rst
app-ceph.rst
app-resources.rst

309
doc/source/reference/configuration/using-overrides.rst
View File

@ -1,5 +1,5 @@
Using overrides
===============
Overriding default configuration
================================
user_*.yml files
~~~~~~~~~~~~~~~~
@ -18,7 +18,7 @@ variables in files named following the ``user_*.yml`` pattern so they will be
sourced alongside those used exclusively by OpenStack-Ansible.
Ordering and precedence
~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^
``user_*.yml`` files contain YAML variables which are applied as extra-vars
when executing ``openstack-ansible`` to run playbooks. They will be sourced
@ -26,8 +26,8 @@ in alphanumeric order by ``openstack-ansible``. If duplicate variables occur
in the ``user_*.yml`` files, the variable in the last file read will take
precedence.
Adding extra python packages into the environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adding extra python packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The system will allow you to install and build any package that is a python
installable. The repository infrastructure will look for and create any
@ -64,8 +64,8 @@ Once the variables are set call the play ``repo-build.yml`` to build all of the
wheels within the repository infrastructure. When ready run the target plays to
deploy your overridden source code.
Setting overrides in configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Setting overrides in configuration files with config_template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All of the services that use YAML, JSON, or INI for configuration can receive
overrides through the use of a Ansible action plugin named ``config_template``.
@ -75,16 +75,14 @@ preset template option. All OpenStack-Ansible roles allow for this
functionality where applicable. Files available to receive overrides can be
seen in the ``defaults/main.yml`` file as standard empty dictionaries (hashes).
Practical guidance for using this feature is available in the
:deploy_guide:`Deployment Guide <app-advanced-config-override.html>`.
This module has been `rejected for inclusion`_ into Ansible Core.
.. _rejected for inclusion: https://github.com/ansible/ansible/pull/12555
This module was not accepted into Ansible Core (see `PR1`_ and `PR2`_), and
will never be.
.. _PR1: https://github.com/ansible/ansible/pull/12555
.. _PR2: https://github.com/ansible/ansible/pull/35453
config_template documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These are the options available as found within the virtual module
documentation section.
@ -135,6 +133,13 @@ documentation section.
Example task using the config_template module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this task the ``test.ini.j2`` file is a template which will be rendered and
written to disk at ``/tmp/test.ini``. The **config_overrides** entry is a
dictionary (hash) which allows a deployer to set arbitrary data as overrides to
be written into the configuration file at run time. The **config_type** entry
specifies the type of configuration file the module will be interacting with;
available options are "yaml", "json", and "ini".
.. code-block:: yaml
- name: Run config template ini
@ -145,8 +150,7 @@ Example task using the config_template module
config_type: ini
Example overrides dictionary (hash)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is an example override dictionary (hash)
.. code-block:: yaml
@ -155,8 +159,7 @@ Example overrides dictionary (hash)
new_item: 12345
Original template file ``test.ini.j2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
And here is the template file:
.. code-block:: ini
@ -164,9 +167,8 @@ Original template file ``test.ini.j2``
value1 = abc
value2 = 123
Rendered on disk file ``/tmp/test.ini``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The rendered file on disk, namely ``/tmp/test.ini`` looks like
this:
.. code-block:: ini
@ -176,14 +178,6 @@ Rendered on disk file ``/tmp/test.ini``
new_item = 12345
In this task the ``test.ini.j2`` file is a template which will be rendered and
written to disk at ``/tmp/test.ini``. The **config_overrides** entry is a
dictionary (hash) which allows a deployer to set arbitrary data as overrides to
be written into the configuration file at run time. The **config_type** entry
specifies the type of configuration file the module will be interacting with;
available options are "yaml", "json", and "ini".
Discovering available overrides
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -199,3 +193,260 @@ The list of overrides available may be found by executing:
find . -name "main.yml" -exec grep '_.*_overrides:' {} \; \
| grep -v "^#" \
| sort -u
The following override variables are currently available:
Galera:
* galera_client_my_cnf_overrides
* galera_my_cnf_overrides
* galera_cluster_cnf_overrides
* galera_debian_cnf_overrides
Telemetry service (ceilometer):
* ceilometer_policy_overrides
* ceilometer_ceilometer_conf_overrides
* ceilometer_event_definitions_yaml_overrides
* ceilometer_event_pipeline_yaml_overrides
* ceilometer_pipeline_yaml_overrides
Block Storage (cinder):
* cinder_policy_overrides
* cinder_rootwrap_conf_overrides
* cinder_api_paste_ini_overrides
* cinder_cinder_conf_overrides
Image service (glance):
* glance_glance_api_paste_ini_overrides
* glance_glance_api_conf_overrides
* glance_glance_cache_conf_overrides
* glance_glance_manage_conf_overrides
* glance_glance_registry_paste_ini_overrides
* glance_glance_registry_conf_overrides
* glance_glance_scrubber_conf_overrides
* glance_glance_scheme_json_overrides
* glance_policy_overrides
Orchestration service (heat):
* heat_heat_conf_overrides
* heat_api_paste_ini_overrides
* heat_default_yaml_overrides
* heat_aws_rds_dbinstance_yaml_overrides
* heat_policy_overrides
Identity service (keystone):
* keystone_keystone_conf_overrides
* keystone_keystone_default_conf_overrides
* keystone_keystone_paste_ini_overrides
* keystone_policy_overrides
Networking service (neutron):
* neutron_neutron_conf_overrides
* neutron_ml2_conf_ini_overrides
* neutron_dhcp_agent_ini_overrides
* neutron_api_paste_ini_overrides
* neutron_rootwrap_conf_overrides
* neutron_policy_overrides
* neutron_dnsmasq_neutron_conf_overrides
* neutron_l3_agent_ini_overrides
* neutron_metadata_agent_ini_overrides
* neutron_metering_agent_ini_overrides
Compute service (nova):
* nova_nova_conf_overrides
* nova_rootwrap_conf_overrides
* nova_api_paste_ini_overrides
* nova_policy_overrides
Object Storage service (swift):
* swift_swift_conf_overrides
* swift_swift_dispersion_conf_overrides
* swift_proxy_server_conf_overrides
* swift_account_server_conf_overrides
* swift_account_server_replicator_conf_overrides
* swift_container_server_conf_overrides
* swift_container_server_replicator_conf_overrides
* swift_object_server_conf_overrides
* swift_object_server_replicator_conf_overrides
Tempest:
* tempest_tempest_conf_overrides
pip:
* pip_global_conf_overrides
.. note::
Possible additional overrides can be found in the "Tunable Section"
of each role's ``main.yml`` file, such as
``/etc/ansible/roles/role_name/defaults/main.yml``.
Overriding OpenStack configuration defaults
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OpenStack has many configuration options available in ``.conf`` files
(in a standard ``INI`` file format),
policy files (in a standard ``JSON`` format) and ``YAML`` files, and
can therefore use the ``config_template`` module described above.
OpenStack-Ansible enables you to reference any options in the
`OpenStack Configuration Reference`_ through the use of a simple set of
configuration entries in the ``/etc/openstack_deploy/user_variables.yml``.
.. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/
Overriding .conf files
^^^^^^^^^^^^^^^^^^^^^^
Most often, overrides are implemented for the ``<service>.conf`` files
(for example, ``nova.conf``). These files use a standard INI file format.
For example, you might want to add the following parameters to the
``nova.conf`` file:
.. code-block:: ini
[DEFAULT]
remove_unused_original_minimum_age_seconds = 43200
[libvirt]
cpu_mode = host-model
disk_cachemodes = file=directsync,block=none
[database]
idle_timeout = 300
max_pool_size = 10
To do this, you use the following configuration entry in the
``/etc/openstack_deploy/user_variables.yml`` file:
.. code-block:: yaml
nova_nova_conf_overrides:
DEFAULT:
remove_unused_original_minimum_age_seconds: 43200
libvirt:
cpu_mode: host-model
disk_cachemodes: file=directsync,block=none
database:
idle_timeout: 300
max_pool_size: 10
.. note::
The general format for the variable names used for overrides is
``<service>_<filename>_<file extension>_overrides``. For example, the variable
name used in these examples to add parameters to the ``nova.conf`` file is
``nova_nova_conf_overrides``.
You can also apply overrides on a per-host basis with the following
configuration in the ``/etc/openstack_deploy/openstack_user_config.yml``
file:
.. code-block:: yaml
compute_hosts:
900089-compute001:
ip: 192.0.2.10
host_vars:
nova_nova_conf_overrides:
DEFAULT:
remove_unused_original_minimum_age_seconds: 43200
libvirt:
cpu_mode: host-model
disk_cachemodes: file=directsync,block=none
database:
idle_timeout: 300
max_pool_size: 10
Use this method for any files with the ``INI`` format for in OpenStack projects
deployed in OpenStack-Ansible.
Overriding .json files
^^^^^^^^^^^^^^^^^^^^^^
To implement access controls that are different from the ones in a standard
OpenStack environment, you can adjust the default policies applied by services.
Policy files are in a ``JSON`` format.
For example, you might want to add the following policy in the ``policy.json``
file for the Identity service (keystone):
.. code-block:: json
{
"identity:foo": "rule:admin_required",
"identity:bar": "rule:admin_required"
}
To do this, you use the following configuration entry in the
``/etc/openstack_deploy/user_variables.yml`` file:
.. code-block:: yaml
keystone_policy_overrides:
identity:foo: "rule:admin_required"
identity:bar: "rule:admin_required"
.. note::
The general format for the variable names used for overrides is
``<service>_policy_overrides``. For example, the variable name used in this
example to add a policy to the Identity service (keystone) ``policy.json`` file
is ``keystone_policy_overrides``.
Use this method for any files with the ``JSON`` format in OpenStack projects
deployed in OpenStack-Ansible.
To assist you in finding the appropriate variable name to use for
overrides, the general format for the variable name is
``<service>_policy_overrides``.
Overriding .yml files
^^^^^^^^^^^^^^^^^^^^^
You can override ``.yml`` file values by supplying replacement YAML content.
.. note::
All default YAML file content is completely overwritten by the overrides,
so the entire YAML source (both the existing content and your changes)
must be provided.
For example, you might want to define a meter exclusion for all hardware
items in the default content of the ``pipeline.yml`` file for the
Telemetry service (ceilometer):
.. code-block:: yaml
sources:
- name: meter_source
interval: 600
meters:
- "!hardware.*"
sinks:
- meter_sink
- name: foo_source
value: foo
To do this, you use the following configuration entry in the
``/etc/openstack_deploy/user_variables.yml`` file:
.. code-block:: yaml
ceilometer_pipeline_yaml_overrides:
sources:
- name: meter_source
interval: 600
meters:
- "!hardware.*"
sinks:
- meter_sink
- name: source_foo
value: foo
.. note::
The general format for the variable names used for overrides is
``<service>_<filename>_<file extension>_overrides``. For example, the variable
name used in this example to define a meter exclusion in the ``pipeline.yml`` file
for the Telemetry service (ceilometer) is ``ceilometer_pipeline_yaml_overrides``.

49
doc/source/reference/inventory/configure-inventory.rst
View File

@ -11,6 +11,54 @@ OpenStack-Ansible in the
Additional services should be defined with a YAML file in
``/etc/openstack_deploy/conf.d``, in order to manage file size.
Affinity
~~~~~~~~
When OpenStack-Ansible generates its dynamic inventory, the affinity
setting determines how many containers of a similar type are deployed on a
single physical host.
Using ``shared-infra_hosts`` as an example, consider this
``openstack_user_config.yml`` configuration:
.. code-block:: yaml
shared-infra_hosts:
infra1:
ip: 172.29.236.101
infra2:
ip: 172.29.236.102
infra3:
ip: 172.29.236.103
Three hosts are assigned to the `shared-infra_hosts` group,
OpenStack-Ansible ensures that each host runs a single database container,
a single Memcached container, and a single RabbitMQ container. Each host has
an affinity of 1 by default, which means that each host runs one of each
container type.
If you are deploying a stand-alone Object Storage (swift) environment,
you can skip the deployment of RabbitMQ. If you use this configuration,
your ``openstack_user_config.yml`` file would look as follows:
.. code-block:: yaml
shared-infra_hosts:
infra1:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.101
infra2:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.102
infra3:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.103
This configuration deploys a Memcached container and a database container
on each host, but no RabbitMQ containers.
env.d
~~~~~
@ -21,7 +69,6 @@ deployed environment, allowing a deployer to define additional group mappings.
This directory is used to extend the environment skeleton, or modify the
defaults defined in the ``inventory/env.d`` directory.
Configuration constraints
~~~~~~~~~~~~~~~~~~~~~~~~~