Update docs around custom roles

We now have additional tools for managing and updating the custom roles
for deployments. This change updates the docs with additional details
around the provided custom roles as well as including links to the
documentation around the role format.

Change-Id: I282bed83517abec10558f10af6f121e0eac10674
Related-Blueprint: example-custom-role-environments

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

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 <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