Merge branch 'master' of git@github.com:thatch45/salt

doc/ref/grains.rst

@@ -2,4 +2,37 @@
 Grains
 ======
 
-Static information that Salt derives about the system it's running on.
+Salt comes with an interface to derive information about the underlying system.
+This is called the grains interface, because it presents salt with grains of
+information.
+
+The grains interface is made available to Salt modules and components so that
+the right salt minion commands are automatically available on the right
+systems.
+
+It is important to remember that grains are bits of information loaded when
+the salt minion starts, so this information is static. This means that the
+information in grains is unchanging, therefore the nature of the data is
+static. So grains information are things like the running kernel, or the
+operating system.
+
+Writing Grains
+==============
+
+Grains are easy to write, the grains interface is derived my executing all of
+the "public" functions found in the modules located in the grains package.
+The functions in the modules of the grains must return a python dict, the keys
+in the dict are the names of the grains, the values are the values.
+
+This means that the actual grains interface is simply a python dict.
+
+Before adding a grain to salt, consider what the grain is and remember that 
+grains need to be static data.
+
+Examples of Grains
+------------------
+
+The core module in the grains package is where the main grains are loaded by
+the salt minion and the principal example of how to write grains:
+
+https://github.com/thatch45/salt/blob/master/salt/grains/core.py

doc/ref/index.rst

@@ -1,3 +1,98 @@
 ==============================
-Introduction to extending Salt
+Introduction to Extending Salt
 ==============================
+
+Salt is made to be used, and made to be extended. The primary goal of Salt is
+to provide a foundation which can be used to solve problems. And the goal of
+Salt is to not assume what those problems might be.
+
+One of the greatest benefit of developing Salt has been the vast array of ways
+in which people have wanted to use it, while the original intention was as a
+communication layer for a cloud controller Salt has been extended to facilitate
+so much more.
+
+Client API
+----------
+
+The primary interface used to extend salt, is to simply use it. Salt executions
+can be called via the Salt client api, making programming master side solutions
+with Salt is easy.
+
+Adding Loadable Plugins
+-----------------------
+
+Salt is comprised of a core platform that loads many types of easy to write
+plugins. The idea is to enable all of the breaking points in the salt processes
+to have a point of pluggable interaction. This means that all of the main
+features of Salt can be extended, modified or used.
+
+The breaking points and helping interfaces span from convenience master side
+executions to manipulating the flow of how data is handled by Salt.
+
+Minion Execution Modules
+````````````````````````
+
+The minion execution modules or just ``modules`` are the core to what salt is
+and does. These modules are found in:
+https://github.com/thatch45/salt/tree/master/salt/modules
+
+These modules are what is called by the salt command line and the salt client
+api. Adding modules is done by simply adding additional python modules to the
+modules directory and restarting the minion.
+
+Grains
+``````
+
+Salt grains, or "grains of truth" are bits of static information that are
+generated when the minion starts. This information is useful when determining
+what package manager to default to, or where certain configuration files are
+stored on the minion.
+
+The Salt grains are the interface used for auto detection and dynamic assignment
+of execution modules and types to specific salt minions.
+
+The code used to generate the Salt grains can be found here:
+https://github.com/thatch45/salt/tree/master/salt/grains
+
+States
+``````
+
+Salt supports state enforcement, this makes Salt a high speed and very efficient
+solution for system configuration management.
+
+States can be easily added to Salt by dropping a new state module in:
+https://github.com/thatch45/salt/tree/master/salt/states
+
+Renderers
+`````````
+
+Salt states are controlled by simple data structures, these structures can be
+abstracted in a number of ways. While the default is to be in a yaml file
+wrapped in a jinja template, any abstraction can be used. This means that any
+format that can be dreamed is possible, so long as a renderer is written for
+it.
+
+The existing renderers can be found here:
+https://github.com/thatch45/salt/tree/master/salt/renderers
+
+Returners
+`````````
+
+The salt commands all produce a return value, that return value is sent to the
+salt master by default, but it can be sent anywhere. The returner interface
+makes it programmatically possible for the information to be sent to anything
+from an SQL or NOSQL database, to a custom application made to use Salt.
+
+The existing returners can be found here:
+https://github.com/thatch45/salt/tree/master/salt/returners
+
+Runners
+```````
+
+Sometimes a certain application can be made to execute and run from the
+existing salt command line. This is where the salt runners come into play.
+The Salt Runners what is called by the salt-run command and are meant to
+act as a generic interface for encapsulating master side executions.
+
+Existing Salt runners are located here:
+https://github.com/thatch45/salt/tree/master/salt/runners

doc/ref/returners/index.rst

@@ -2,8 +2,17 @@
 Returners
 =========
 
-Salt returners allow the return data to be sent to arbitrary locations instead
-of the salt master.
+By default the return values of the commands sent to the salt minions are
+returned to the salt-master. But since the commands executed on the salt
+minions are detatched from the call on the salt master, there is no need for
+the minion to return the data to the salt master.
+
+This is where the returner interface comes in. Returners are modules called
+in place of returning the data to the salt master.
+
+The returner interface allows the return data to be sent to any system that
+can recieve data. This means that return data can be sent to a Redis server,
+a MongoDB server, a MySQL server, or any system!
 
 Full list of builtin returners
 ==============================
@@ -13,3 +22,41 @@ Full list of builtin returners
     :glob:
 
     *
+
+Writing a Returner
+==================
+
+A returner is a module which contains a returner function, the returner
+function must accept a single argument. this argument is the return data from
+the called minion function. So if the minion function ``test.ping`` is called
+the value of the argument will be ``True``.
+
+A simple returner is implimented here:
+
+.. code-block:: python
+
+    import redis
+    import json
+
+    def returner(ret):
+        '''
+        Return information to a redis server
+        '''
+        # Get a redis commection
+        serv = redis.Redis(
+                    host='redis-serv.example.com',
+                    port=6379,
+                    db='0')
+        serv.sadd("%(id)s:jobs" % ret, ret['jid'])
+        serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret['return']))
+        serv.sadd('jobs', ret['jid'])
+        serv.sadd(ret['jid'], ret['id'])
+
+This simple example of a returner set to send the data to a redis server
+serializes the data as json and sets it in redis.
+
+Examples
+--------
+
+The collection of builtin salt returners can be found here:
+https://github.com/thatch45/salt/tree/master/salt/returners