From ae3c3426a0395e03aac8af04b1df1a1088688520 Mon Sep 17 00:00:00 2001
From: Ben Nemec <bnemec@redhat.com>
Date: Fri, 13 Jan 2017 10:55:31 -0600
Subject: [PATCH] Document heterogeneous deployments

---
 doc/source/deploy/deploy.rst        |  1 +
 doc/source/deploy/heterogeneous.rst | 41 ++++++++++++++++++++++++++++-
 templates/env-role.yaml.example     | 16 +++++++++++
 3 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 templates/env-role.yaml.example

diff --git a/doc/source/deploy/deploy.rst b/doc/source/deploy/deploy.rst
index e95add8..85332b9 100644
--- a/doc/source/deploy/deploy.rst
+++ b/doc/source/deploy/deploy.rst
@@ -7,3 +7,4 @@ There are two options for deploying the Heat stack.
 
    quintupleo
    baremetal
+   heterogeneous
diff --git a/doc/source/deploy/heterogeneous.rst b/doc/source/deploy/heterogeneous.rst
index c869959..882fb2b 100644
--- a/doc/source/deploy/heterogeneous.rst
+++ b/doc/source/deploy/heterogeneous.rst
@@ -1,4 +1,43 @@
 Deploying Heterogeneous Environments
 ====================================
 
-TBD
+It is possible to deploy an OVB environment with multiple "baremetal"
+node types.  The :doc:`QuintupleO <quintupleo>` deployment method must be used, so it
+would be best to start with a working configuration for that before
+moving on to heterogeneous deployments.
+
+Each node type will be identified as a ``role``.  A simple QuintupleO
+deployment can be thought of as a single-role deployment.  To deploy
+multiple roles, additional environment files describing the extra roles
+are required.  These environments are simplified versions of the
+standard environment file.  See ``templates/env-role.yaml.example``
+for a starting point when writing these role files.
+
+Steps for deploying the environment:
+
+#. Customize the environment files.  Make sure all environments have a ``role``
+   key in the ``parameter_defaults`` section.  When building nodes.json, this
+   role will be automatically assigned to the node, so it is simplest to use
+   one of the default TripleO roles (control, compute, cephstorage, etc.).
+
+#. Deploy with both roles::
+
+    bin/deploy.py --quintupleo --env env-control.yaml --role env-compute.yaml
+
+#. One Heat stack will be created for each role being deployed.  Wait for them
+   all to complete before proceeding.
+
+#. Build a nodes.json file that can be imported into Ironic::
+
+    bin/build-nodes-json --env env-control.yaml
+
+   .. note:: Only the primary environment file needs to be passed here.  The
+             resources deployed as part of the secondary roles will be named
+             such that they appear to be part of the primary environment.
+
+   .. note:: If ``--id`` was used when deploying, remember to pass the generated
+             environment file to this command instead of the original.
+
+Be aware that the extra role stacks will be connected to networks in the primary
+role stack, so the extra stacks must be deleted before the primary one or the
+neutron subnets will not delete cleanly.
diff --git a/templates/env-role.yaml.example b/templates/env-role.yaml.example
new file mode 100644
index 0000000..6fcc28a
--- /dev/null
+++ b/templates/env-role.yaml.example
@@ -0,0 +1,16 @@
+parameters:
+  baremetal_flavor: baremetal
+  key_name: default
+  node_count: 2
+
+parameter_defaults:
+  # Set a default role for the nodes in this environment.  This parameter is
+  # ignored by Heat, but used by build-nodes-json.
+  role: compute
+
+#resource_registry:
+## Uncomment to create all networks required for network-isolation.
+## parameter_defaults should be used to override default parameter values
+## in baremetal-networks-all.yaml
+#  OS::OVB::BaremetalNetworks: templates/baremetal-networks-all.yaml
+#  OS::OVB::BaremetalPorts: templates/baremetal-ports-all.yaml