diff --git a/doc/source/configuration/kayobe.rst b/doc/source/configuration/kayobe.rst new file mode 100644 index 000000000..ece70f1c4 --- /dev/null +++ b/doc/source/configuration/kayobe.rst @@ -0,0 +1,116 @@ +============= +Configuration +============= + +This section covers configuration of Kayobe. As an Ansible-based project, +Kayobe is for the most part configured using YAML files. + +Configuration Location +====================== + +Kayobe configuration is by default located in ``/etc/kayobe`` on the Ansible +control host. This location can be overridden to a different location to avoid +touching the system configuration directory by setting the environment variable +``KAYOBE_CONFIG_PATH``. Similarly, kolla configuration on the Ansible control +host will by default be located in ``/etc/kolla`` and can be overridden via +``KOLLA_CONFIG_PATH``. + +Configuration Directory Layout +============================== + +The Kayobe configuration directory contains Ansible ``extra-vars`` files and +the Ansible inventory. An example of the directory structure is as follows:: + + extra-vars1.yml + extra-vars2.yml + inventory/ + group_vars/ + group1-vars + group2-vars + groups + host_vars/ + host1-vars + host2-vars + hosts + +Configuration Patterns +====================== + +Ansible's variable precedence rules are `fairly well documented +`_ +and provide a mechanism we can use for providing site localisation and +customisation of OpenStack in combination with some reasonable default values. +For global configuration options, Kayobe typically uses the following patterns: + +- Playbook group variables for the *all* group in + ``/ansible/group_vars/all/*`` set **global defaults**. These + files should not be modified. +- Playbook group variables for other groups in + ``/ansible/group_vars//*`` set **defaults for some subsets + of hosts**. These files should not be modified. +- Extra-vars files in ``${KAYOBE_CONFIG_PATH}/*.yml`` set **custom values + for global variables** and should be used to apply global site localisation + and customisation. By default these variables are commented out. + +Additionally, variables can be set on a per-host basis using inventory host +variables files in ``${KAYOBE_CONFIG_PATH}/inventory/host_vars/*``. It should +be noted that variables set in extra-vars files take precedence over per-host +variables. + +Configuring Kayobe +================== + +The `kayobe-config `_ git repository +contains a Kayobe configuration directory structure and unmodified +configuration files. This repository can be used as a mechanism for version +controlling Kayobe configuration. As Kayobe is updated, the configuration +should be merged to incorporate any upstream changes with local modifications. + +Alternatively, the baseline Kayobe configuration may be copied from a checkout +of the Kayobe repository to the Kayobe configuration path:: + + $ cp -r etc/ ${KAYOBE_CONFIG_PATH:-/etc/kayobe} + +Once in place, each of the YAML and inventory files should be manually +inspected and configured as required. + +Inventory +---------- + +The inventory should contain the following hosts: + +Control host + This should be localhost and should be a member of the ``config-mgmt`` + group. +Seed hypervisor + If provisioning a seed VM, a host should exist for the hypervisor that + will run the VM, and should be a member of the ``seed-hypervisor`` group. +Seed + The seed host, whether provisioned as a VM by Kayobe or externally managed, + should exist in the ``seed`` group. + +Cloud hosts and bare metal compute hosts are not required to exist in the +inventory if discovery of the control plane hardware is planned, although +entries for groups may still be required. + +Use of advanced control planes with multiple server roles and customised +service placement across those servers is covered in +:ref:`control-plane-service-placement`. + +Site Localisation and Customisation +----------------------------------- + +Site localisation and customisation is applied using Ansible extra-vars files +in ``${KAYOBE_CONFIG_PATH}/*.yml``. + +Encryption of Secrets +--------------------- + +Kayobe supports the use of `Ansible vault +`_ to encrypt sensitive +information in its configuration. The ``ansible-vault`` tool should be used to +manage individual files for which encryption is required. Any of the +configuration files may be encrypted. Since encryption can make working with +Kayobe difficult, it is recommended to follow `best practice +`_, +adding a layer of indirection and using encryption only where necessary. diff --git a/doc/source/configuration.rst b/doc/source/configuration/network.rst similarity index 66% rename from doc/source/configuration.rst rename to doc/source/configuration/network.rst index d079c9950..a7eb9e1bf 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration/network.rst @@ -1,122 +1,6 @@ -============= -Configuration -============= - -This section covers configuration of Kayobe. As an Ansible-based project, -Kayobe is for the most part configured using YAML files. - -Configuration Location -====================== - -Kayobe configuration is by default located in ``/etc/kayobe`` on the Ansible -control host. This location can be overridden to a different location to avoid -touching the system configuration directory by setting the environment variable -``KAYOBE_CONFIG_PATH``. Similarly, kolla configuration on the Ansible control -host will by default be located in ``/etc/kolla`` and can be overridden via -``KOLLA_CONFIG_PATH``. - -Configuration Directory Layout -============================== - -The Kayobe configuration directory contains Ansible ``extra-vars`` files and -the Ansible inventory. An example of the directory structure is as follows:: - - extra-vars1.yml - extra-vars2.yml - inventory/ - group_vars/ - group1-vars - group2-vars - groups - host_vars/ - host1-vars - host2-vars - hosts - -Configuration Patterns -====================== - -Ansible's variable precedence rules are `fairly well documented -`_ -and provide a mechanism we can use for providing site localisation and -customisation of OpenStack in combination with some reasonable default values. -For global configuration options, Kayobe typically uses the following patterns: - -- Playbook group variables for the *all* group in - ``/ansible/group_vars/all/*`` set **global defaults**. These - files should not be modified. -- Playbook group variables for other groups in - ``/ansible/group_vars//*`` set **defaults for some subsets - of hosts**. These files should not be modified. -- Extra-vars files in ``${KAYOBE_CONFIG_PATH}/*.yml`` set **custom values - for global variables** and should be used to apply global site localisation - and customisation. By default these variables are commented out. - -Additionally, variables can be set on a per-host basis using inventory host -variables files in ``${KAYOBE_CONFIG_PATH}/inventory/host_vars/*``. It should -be noted that variables set in extra-vars files take precedence over per-host -variables. - -Configuring Kayobe -================== - -The `kayobe-config `_ git repository -contains a Kayobe configuration directory structure and unmodified -configuration files. This repository can be used as a mechanism for version -controlling Kayobe configuration. As Kayobe is updated, the configuration -should be merged to incorporate any upstream changes with local modifications. - -Alternatively, the baseline Kayobe configuration may be copied from a checkout -of the Kayobe repository to the Kayobe configuration path:: - - $ cp -r etc/ ${KAYOBE_CONFIG_PATH:-/etc/kayobe} - -Once in place, each of the YAML and inventory files should be manually -inspected and configured as required. - -Inventory ----------- - -The inventory should contain the following hosts: - -Control host - This should be localhost and should be a member of the ``config-mgmt`` - group. -Seed hypervisor - If provisioning a seed VM, a host should exist for the hypervisor that - will run the VM, and should be a member of the ``seed-hypervisor`` group. -Seed - The seed host, whether provisioned as a VM by Kayobe or externally managed, - should exist in the ``seed`` group. - -Cloud hosts and bare metal compute hosts are not required to exist in the -inventory if discovery of the control plane hardware is planned, although -entries for groups may still be required. - -Use of advanced control planes with multiple server roles and customised -service placement across those servers is covered in -:ref:`control-plane-service-placement`. - -Site Localisation and Customisation ------------------------------------ - -Site localisation and customisation is applied using Ansible extra-vars files -in ``${KAYOBE_CONFIG_PATH}/*.yml``. - -Encryption of Secrets ---------------------- - -Kayobe supports the use of `Ansible vault -`_ to encrypt sensitive -information in its configuration. The ``ansible-vault`` tool should be used to -manage individual files for which encryption is required. Any of the -configuration files may be encrypted. Since encryption can make working with -Kayobe difficult, it is recommended to follow `best practice -`_, -adding a layer of indirection and using encryption only where necessary. - +===================== Network Configuration ---------------------- +===================== Kayobe provides a flexible mechanism for configuring the networks in a system. Kayobe networks are assigned a name which is used as a prefix for variables @@ -229,7 +113,7 @@ in ``${KAYOBE_CONFIG_PATH}/seed.yml`` and ``${KAYOBE_CONFIG_PATH}/controllers.yml`` respectively. Example -^^^^^^^ +======= In our example cloud we have three networks: ``management``, ``cloud`` and ``external``: diff --git a/doc/source/index.rst b/doc/source/index.rst index 244ac55ed..a34cd9b26 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -23,7 +23,8 @@ Documentation architecture installation usage - configuration + configuration/kayobe + configuration/network deployment upgrading administration