Merge pull request #881 from coderanger/shardseed-docs

Doc changes for #877

1 files changed, 72 insertions, 0 deletions

diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index c473f9d3..02192f93 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -7,3 +7,75 @@ Description of the required change.
 -->
 
 # Ohai Doc Changes:
+
+## Shard Seed Plugin
+
+The new `shard_seed` attribute provides a uniformly distributed integer ID value
+to all nodes. This value will be between 0 and 4294967295 (0xFFFFFFFF), based
+on a consistent hash of one or more pieces of node data. A consistent hash
+means that a node with the same source inputs will always result in the same
+shard seed, but collisions are possible.
+
+The sources used to compute the seed value can be configured either in your
+Chef config file:
+
+```ruby
+Ohai::Config[:plugin][:shard_seed][:sources] = [:fqdn]
+```
+
+or your Ohai config file if you run Ohai outside of Chef:
+
+```ruby
+ohai.plugin[:shard_seed][:sources] = [:fqdn]
+```
+
+The default sources are `[:machinename, :serial, :uuid]` but this value should
+be considered experimental for the moment as it may be expanded to support
+additional platforms. Configuring a value that works for your infrastructure is
+highly recommended.
+
+### Shard Seed Sources
+
+There are multiple sources of data that can be used as inputs to the hash:
+
+* `:machinename` – Everything before the first `.` in the machine's hostname.
+* `:fqdn` – The machine's fully-qualified name. Depending on your platform and
+  configuration, it is possible that this value could be unstable during DNS
+  failures or other network outages.
+* `:hostname` – The machine's raw hostname. As with `:fqdn`, this may be unstable
+  during DNS failures or network outages.
+* `:serial` – The machine's serial number as reported by DMI, SystemProfiler, or
+  WMI.
+* `:uuid` – The machine's UUID as reported by DMI, SystemProfiler, or WMI.
+* `:machine_id` – The systemd machine ID. Only available on platforms using
+  systemd.
+
+You can configure either one source or an array of sources which will be
+concatenated together.
+
+### Using the Shard Seed
+
+Two main use cases for the seed value are slow rollouts of new features and
+computing service IDs.
+
+To do slow rollouts, you can wrap new features or options in your recipe code
+with a conditional `if` statement like:
+
+```ruby
+# Enable feature for 20% of nodes.
+if (node['shard_seed'] % 100) < 20
+  # Code goes here ...
+end
+```
+
+For creating a service ID for something like ZooKeeper or MySQL replication:
+
+```ruby
+# Write the ID to a file for safety, in case something changes.
+file '/etc/zookeeper/myid' do
+  action :create_if_missing
+  # ZooKeeper ID is 1-255.
+  content "#{(node['shard_seed'] % 255) + 1}"
+end
+```
+