diff --git a/doc/source/install/advanced_deployment/composable_services.rst b/doc/source/install/advanced_deployment/composable_services.rst index bd0e7854..596b37b8 100644 --- a/doc/source/install/advanced_deployment/composable_services.rst +++ b/doc/source/install/advanced_deployment/composable_services.rst @@ -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 diff --git a/doc/source/install/advanced_deployment/custom_roles.rst b/doc/source/install/advanced_deployment/custom_roles.rst index ebb9543c..65e17822 100644 --- a/doc/source/install/advanced_deployment/custom_roles.rst +++ b/doc/source/install/advanced_deployment/custom_roles.rst @@ -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 `_ +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