From b2dad7920daa512a98d697a0dec05b559b777fd6 Mon Sep 17 00:00:00 2001
From: Philipp Adelt <info@philipp.adelt.net>
Date: Wed, 16 May 2012 12:58:35 +0200
Subject: [PATCH] Clarify pillar use for files managed on minions that include
 pillar key/value data

---
 doc/topics/pillar/index.rst | 57 ++++++++++++++++++++++++++++++++++---
 1 file changed, 53 insertions(+), 4 deletions(-)

diff --git a/doc/topics/pillar/index.rst b/doc/topics/pillar/index.rst
index 86a360ed4638..7be1628cd8ac 100644
--- a/doc/topics/pillar/index.rst
+++ b/doc/topics/pillar/index.rst
@@ -18,8 +18,8 @@ on environments mapping to directories. The pillar data is then mapped to
 minions based on matchers in a top file which is laid out in the same way
 as the state top file.
 
-The configuration for the pillar_roots in the master config is identical in
-behavior and function as the file_roots configuration:
+The configuration for the ``pillar_roots`` in the master config is identical in
+behavior and function as the ``file_roots`` configuration:
 
 .. code-block:: yaml
 
@@ -28,17 +28,25 @@ behavior and function as the file_roots configuration:
         - /srv/pillar
 
 This example configuration declares that the base environment will be located
-in the /srv/pillar directory. The top file used matches the name of the top file
+in the ``/srv/pillar`` directory. The top file used matches the name of the top file
 used for states, and has the same structure:
 
+``/srv/pillar/top.sls``
+
 .. code-block:: yaml
 
     base:
       '*':
         - packages
+      'someminion':
+        - someminion-specials
 
 This simple pillar top file declares that information for all minions can be
-found in the package's sls file:
+found in the ``packages.sls`` file [#nokeyvalueintop]_, while
+``someminion-specials.sls`` contains overriding or additional information just
+for one special minion.
+
+``/srv/pillar/packages.sls``
 
 .. code-block:: yaml
 
@@ -49,6 +57,13 @@ found in the package's sls file:
     apache: apache2
     git: git-core
     {% endif %}
+    somekey: globalvalue
+
+``/srv/pillar/someminion-specials.sls``
+
+.. code-block:: yaml
+
+    somekey: specialvalue
 
 Now this data can be used from within modules, renderers, state sls files and
 more via the shared pillar dict:
@@ -67,6 +82,40 @@ more via the shared pillar dict:
         - installed
         - name: {{ pillar['git'] }}
 
+To use pillar data in a file that is managed on a minion, use a file state like
+this:
+
+``/srv/salt/top.sls``
+
+.. code-block:: yaml
+
+    base:
+      '*':
+        - managed_files
+
+``/srv/salt/managed_files.sls``
+
+.. code-block:: yaml
+
+    /tmp/some-managed-file.txt:
+      file:
+        - managed
+        - template: jinja
+        - source: salt://files/some-managed-file.txt
+
+``/srv/salt/files/some-managed-file.txt``
+
+.. code-block:: yaml
+
+    This will yield 'globalvalue' on all minions but will yield 'specialvalue'
+    on 'someminion':
+    somekey has value: {{ pillar['somekey'] }}
+
+Footnotes
+---------
+
+.. [#nokeyvalueintop] Note that you cannot just list key/value-information in ``top.sls``.
+
 Refreshing Pillar Data
 ======================