openstack/tripleo-docs
Code Issues Proposed changes

Merge "Update docs around custom roles"

Browse Source
This commit is contained in:
Jenkins 2017-07-13 09:38:29 +00:00 committed by Gerrit Code Review
commit e149c9330a
2 changed files with 52 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/source/install/advanced_deployment/composable_services.rst
View File

@ -11,9 +11,12 @@ refers to the individual services or configurations e.g "Nova API").
Deploying with custom service lists
-----------------------------------
Each role defines a default list of services, which can be viewed in the
`roles_data.yaml` file (see `/usr/share/openstack-tripleo-heat-templates`, or
the tripleo-heat-templates_ git repository.)
Each role to be used in the deployment is defined in a `roles_data.yaml` file.
There is a sample file in `/usr/share/openstack-tripleo-heat-templates`, or the
tripleo-heat-templates_ git repository. Additional example roles are located in
the `/usr/share/openstack-tripleo-heat-templates/roles` directory and can be used
to create a custom `roles_data.yaml` file. See :doc:`custom_roles` for additional
usage details.
The data in `roles_data.yaml` is used to set the defaults for per-role parameters
e.g `CustomControllerServices`. These defaults can be overridden via environment

58
doc/source/install/advanced_deployment/custom_roles.rst
View File

@ -12,12 +12,30 @@ See :doc:`composable_services` if you only wish to modify the default list of
deployed services, or see below if you wish to modify the deployed roles.
Provided example roles
----------------------
TripleO offers examples roles provided in `openstack-tripleo-heat-templates`.
These roles can be listed using the `tripleoclient` by running::
openstack overcloud role list
With these provided roles, the user deploying the overcloud can generate a
`roles_data.yaml` file that contains the roles they would like to use for the
overcloud nodes. Additionally the user can manage their personal custom roles
in a similar manor by storing the individual files in a directory and using
the `tripleoclient` to generate their `roles_data.yaml`. For example, a user
can execute the following to create a `roles_data.yaml` containing only the
`Controller` and `Compute` roles::
openstack overcloud roles generate -o ~/roles_data.yaml Controller Compute
Deploying with custom roles
---------------------------
Each role is defined in the `roles_data.yaml` file (see
Each role is defined in the `roles_data.yaml` file. There is a sample file in
`/usr/share/openstack-tripleo-heat-templates`, or the tripleo-heat-templates_ git
repository.)
repository.
The data in `roles_data.yaml` is used to perform templating with jinja2_ such
that arbitrary user-defined roles may be added, and the default roles may
@ -25,25 +43,37 @@ be modified or removed.
The steps to define your custom roles configuration are:
1. Copy the default roles_data.yaml::
1. Copy the default roles provided by `tripleo-heat-templates`:
cp /usr/share/openstack-tripleo-heat-templates/roles_data.yaml ~/my_roles_data.yaml
mkdir ~/roles
cp /usr/share/openstack-tripleo-heat-templates/roles/* ~/roles
2. Edit my_roles_data.yaml to suit your requirements
The roles_data is a simple list of roles, where the only mandatory argument is
the name, and several optional additional keys are supported:
2. Create a new role file with your custom role.
Additional details about the format for the roles file can be found in the
`README.rst <http://git.openstack.org/cgit/openstack/tripleo-heat-templates/tree/roles/README.rst>`_
in the roles/ directory from `tripleo-heat-templates`. The filename should
match the name of the role. For example if adding a new role named `Galera`,
the role file name should be `Galera.yaml`. The file should at least contain
the following items:
* name: Name of the role e.g "CustomController", mandatory
* CountDefault: Default number of nodes, defaults to zero
* ServicesDefault: List of services, optional, defaults to an empty list
See the default roles_data.yaml or overcloud-resource-registry-puppet.j2.yaml
for the list of supported services. Both files can be found in the top
tripleo-heat-templates folder
* HostnameFormatDefault: Format string for hostname, optional
For example the following role would deploy a pacemaker managed galera cluster::
Additional items like the ones below should be included as well:
* CountDefault: Default number of nodes, defaults to zero
* HostnameFormatDefault: Format string for hostname, optional
* Description: A few sentences describing the role and information
pertaining to the usage of the role.
The role file format is a basic yaml structure. The expectation is that there
is a single role per file. See the roles `README.rst` for additional details. For
example the following role might be used to deploy a pacemaker managed galera
cluster::
- name: Galera
HostnameFormatDefault: '%stackname%-galera-%index%'
@ -75,8 +105,12 @@ For example the following role would deploy a pacemaker managed galera cluster::
CLI args are hardcoded to the "Control" and "Compute" role names, so they're in
fact ignored when using custom roles.
3. Create a `roles_data.yaml` file that contains the custom role in addition
to the other roles that will be deployed. For example::
3. Pass the modified roles_data on deployment as follows::
openstack overcloud roles generate --roles-path ~/roles -o ~/my_roles_data.yaml Controller Compute Galera
4. Pass the modified roles_data on deployment as follows::
openstack overcloud deploy --templates -r ~/my_roles_data.yaml