From 69ef1c70367d3955bc623e3cda8208642ecd3266 Mon Sep 17 00:00:00 2001
From: Monty Taylor <mordred@inaugust.com>
Date: Fri, 4 Dec 2015 13:49:38 -0500
Subject: [PATCH] Add examples to make the disabling prose clearer

The way disabling works with puppet and openstack inventory in ansible
can be confusing at first. Some examples hopefully clarify the
situation.

Change-Id: Ib85feebce309896c6f3d139318dd5d204d9cb8ec
---
 doc/source/sysadmin.rst | 42 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/doc/source/sysadmin.rst b/doc/source/sysadmin.rst
index d0ff64b7ca..036caee87c 100644
--- a/doc/source/sysadmin.rst
+++ b/doc/source/sysadmin.rst
@@ -287,6 +287,17 @@ make changes through puppet.  However, under some circumstances, you
 may need to temporarily make a manual change to a puppet-managed
 resource on a server.
 
+OpenStack Infra uses a non-trivial combination of Dynamic and Static
+Inventory in Ansible to control execution of puppet. A full understanding
+of the concepts in
+`Ansible Inventory Introduction
+<http://docs.ansible.com/ansible/intro_inventory.html>`_
+and
+`Ansible Dynamic Inventory
+<http://docs.ansible.com/ansible/intro_dynamic_inventory.html>`_
+is essential for being able to make informed decisions about actions
+to take.
+
 In the case of needing to disable the running of puppet on a node, it's a
 simple matter of adding an entry to the ansible inventory "disabled" group.
 There are two inventory files available for this, `/etc/ansible/hosts/static`
@@ -316,6 +327,37 @@ run directly on the host, it merely prevents the puppetmaster from causing
 puppet to be run. If you choose to run puppet manually on a host, take care
 to ensure that it has not been disabled at the puppetmaster level first.
 
+Examples
+--------
+
+To disable an OpenStack instance called `amazing.openstack.org` temporarily
+without landing a puppet change, ensure the following is in
+`/etc/ansible/hosts/emergency`
+
+::
+
+  [amazing.openstack.org]
+
+  [disabled:children]
+  amazing.openstack.org
+
+To disable one of the OpenStack instances called `git.openstack.org`
+temporarily without landing a puppet change but leaving the other running,
+find its UUID via OpenStack tools and ensure it's in the emergency file.
+
+::
+
+  [disabled]
+  811c5197-dba7-4d3a-a3f6-68ca5328b9a7
+
+To disable a staticly defined host that is not an OpenStack host, such as
+the Infra cloud controller hosts.
+
+::
+
+  [disabled]
+  controller.useast.openstack.org
+
 .. _cinder:
 
 Cinder Volume Management