Merge "Update docs around custom roles"

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
+Each role to be used in the deployment is defined in a `roles_data.yaml` file.
-`roles_data.yaml` file (see `/usr/share/openstack-tripleo-heat-templates`, or
+There is a sample file in `/usr/share/openstack-tripleo-heat-templates`, or the
-the tripleo-heat-templates_ git repository.)
+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
+2. Create a new role file with your custom role.
-
-The roles_data is a simple list of roles, where the only mandatory argument is
-the name, and several optional additional keys are supported:
 
+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