From 3d2893402c4da5f391b8a959082e9cc668430ad3 Mon Sep 17 00:00:00 2001
From: Giulio Fidente <gfidente@redhat.com>
Date: Tue, 21 Jun 2016 15:35:17 +0200
Subject: [PATCH] Describe how to provide node-specific hieradata

Adds a section in the advanced deployment chapter describing how
to provide node-specific hieradata.

Change-Id: I963bc02c469470c582c826b3484192a320143aaf
---
 .../advanced_deployment.rst                   |  1 +
 .../node_specific_hieradata.rst               | 53 +++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 doc/source/advanced_deployment/node_specific_hieradata.rst

diff --git a/doc/source/advanced_deployment/advanced_deployment.rst b/doc/source/advanced_deployment/advanced_deployment.rst
index c3b10b5d..04c41ba5 100644
--- a/doc/source/advanced_deployment/advanced_deployment.rst
+++ b/doc/source/advanced_deployment/advanced_deployment.rst
@@ -14,6 +14,7 @@ In this chapter you will find advanced deployment of various |project| areas.
    ready_state
    introspection_data
    node_config
+   node_specific_hieradata
    extra_config
    template_deploy
    network_isolation
diff --git a/doc/source/advanced_deployment/node_specific_hieradata.rst b/doc/source/advanced_deployment/node_specific_hieradata.rst
new file mode 100644
index 00000000..ea2715c7
--- /dev/null
+++ b/doc/source/advanced_deployment/node_specific_hieradata.rst
@@ -0,0 +1,53 @@
+Provisioning of node-specific Hieradata
+=======================================
+
+This guide assumes that your undercloud is already installed and ready to
+deploy an overcloud.
+
+It is possible to provide some node-specific hieradata via Heat environment
+files and as such customize one or more settings for a specific node,
+regardless of the Heat `ResourceGroup` to which it belongs.
+
+As a sample use case, we will distribute a node-specific disks configuration
+for a particular CephStorage node, which by default runs the `ceph-osd` service.
+
+Collecting the node UUID
+------------------------
+
+The node-specific hieradata is provisioned based on the node UUID, which is
+hardware dependent and immutable across reboots/reinstalls.
+
+First make sure the introspection data is available for the target node, if it
+isn't one can run introspection for a particular node as described in:
+:doc:`introspect_single_node`.
+
+Then extract the machine unique UUID for the target node with a command like::
+
+  openstack baremetal introspection data save NODE-ID | jq .extra.system.product.uuid
+
+where `NODE-ID` is the target node Ironic UUID. The value returned by the above
+command will be a unique and immutable machine UUID which isn't related to the
+Ironic node UUID. For the next step, we'll assume the output was
+`32E87B4C-C4A7-418E-865B-191684A6883B`.
+
+Creating the Heat environment file
+----------------------------------
+
+Assuming we want to use `/dev/sdc` as data disk for `ceph-osd` on our target
+node, we'll create a yaml file looking like the following
+(eg. `my-node-settings.yaml`)::
+
+  resource_registry:
+    OS::TripleO::CephStorageExtraConfigPre: /path/to/tripleo-heat-templates/puppet/extraconfig/pre_deploy/per_node.yaml
+
+  parameter_defaults:
+    NodeDataLookup: |
+      {"32E87B4C-C4A7-418E-865B-191684A6883B": {"ceph::profile::params::osds": {"/dev/sdc": {}}}}
+
+In the above example we're customizing only a single key for a single node, but
+the structure is that of a UUID-mapped hash so it is possible to customize
+multiple and different keys for multiple nodes.
+
+Finally, add such an environment file to the deploy commandline::
+
+  openstack overcloud deploy [other overcloud deploy options] -e ~/my-node-settings.yaml