Add doc and test support

doc/topics/proxyminion/index.rst

@@ -27,6 +27,13 @@ demonstration of a working proxy minion.
 See the :doc:`Proxy Minion SSH Walkthrough </topics/proxyminion/ssh>` for an end-to-end
 demonstration of a working SSH proxy minion.
 
+
+See :doc:`Proxyminion States </topics/proxyminion/state>` to configure and
+run ``salt-proxy`` on a remote minion. Specify all your master side
+proxy (pillar) configuration and use this state to remotely configure proxies on one
+or more minions.
+
+
 New in 2015.8.2
 ---------------
 

doc/topics/proxyminion/state.rst

@@ -0,0 +1,76 @@
+.. versionadded:: 2015.8.2
+
+===================
+Proxy Minion States
+===================
+
+
+Salt proxy state can be used to deploy, configure and run
+a ``salt-proxy`` instance on your minion. Configure proxy settings
+on the master side and the state configures and runs ``salt-proxy``
+on the remote end.
+
+1. On your salt-master, ensure that pillar is configured properly.  Select an ID
+   for your proxy (in this example we will name the proxy 'p8000').
+   In your pillar topfile, place an entry for your proxy:
+
+.. code-block:: yaml
+
+   base:
+     'p8000':
+       - p8000
+
+This says that Salt's pillar should load some values for the proxy ``p8000``
+from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots)
+
+2. In the pillar root for your base environment, create this file:
+
+.. code-block:: yaml
+
+   p8000.sls
+   ---------
+
+   proxy:
+     # set proxytype for your proxymodule
+     proxytype: ssh_sample
+     host: saltyVM
+     username: salt
+     password: badpass
+
+3. Create the following state in your state tree
+   (let's name it salt_proxy.sls)
+
+.. code-block:: yaml
+
+  salt-proxy-configure:
+    salt_proxy.configure_proxy:
+      - proxyname: p8000
+      - start: True # start the process if it isn't running
+
+4. Make sure your salt-master and salt-minion are running.
+
+5. Run the state salt_proxy on the minion where you want to run ``salt-proxy``
+
+Example using ``state.sls`` to configure and run ``salt-proxy``
+
+.. code-block:: bash
+
+  # salt device_minion state.sls salt_proxy
+
+This starts salt-proxy on ``device_minion``
+
+6. Accept your proxy's key on your salt-master
+
+.. code-block:: bash
+
+   salt-key -y -a p8000
+   The following keys are going to be accepted:
+   Unaccepted Keys:
+   p8000
+   Key for minion p8000 accepted.
+
+7. Now you should be able to run commands on your proxy.
+
+.. code-block:: bash
+
+    salt p8000 pkg.list_pkgs

salt/states/salt_proxy.py

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
 '''
+    Salt proxy state
+
+    .. versionadded:: 2015.8.2
+
     State to deploy and run salt-proxy processes
     on a minion.
 
@@ -28,6 +32,9 @@ log = logging.getLogger(__name__)
 
 
 def _write_proxy_conf(proxyfile):
+    '''
+    write to file
+    '''
     msg = 'Invalid value for proxy file provided!, Supplied value = {0}' \
         .format(proxyfile)
 
@@ -35,7 +42,7 @@ def _write_proxy_conf(proxyfile):
 
     if proxyfile:
         log.debug('Writing proxy conf file')
-        with open(path, 'w') as proxy_conf:
+        with open(proxyfile, 'w') as proxy_conf:
             proxy_conf.write('master = {0}'
                              .format(__grains__['master']))
         msg = 'Wrote proxy file {0}'.format(proxyfile)
@@ -44,14 +51,21 @@ def _write_proxy_conf(proxyfile):
     return msg
 
 
-def _proxy_conf_file(proxyfile):
+def _proxy_conf_file(proxyfile, test):
+    '''
+    Check if proxy conf exists and update
+    '''
     changes_old = []
     changes_new = []
     success = True
     if not os.path.exists(proxyfile):
         try:
-            changes_new.append(_write_proxy_conf(proxyfile))
-            msg = 'Salt Proxy: Wrote proxy conf {0}'.format(proxyfile)
+            if not test:
+                changes_new.append(_write_proxy_conf(proxyfile))
+                msg = 'Salt Proxy: Wrote proxy conf {0}'.format(proxyfile)
+            else:
+                msg = 'Salt Proxy: Update required to proxy conf {0}' \
+                    .format(proxyfile)
         except (OSError, IOError) as err:
             success = False
             msg = 'Salt Proxy: Error writing proxy file {0}'.format(str(err))
@@ -66,45 +80,84 @@ def _proxy_conf_file(proxyfile):
     return success, changes_new, changes_old
 
 
-def configure_proxy(proxyname='p8000', start=True, **kwargs):
+def _is_proxy_running(proxyname):
     '''
-    Create the salt proxy file and start the proxy process
-    if required
+    Check if proxy for this name is running
     '''
-    changes_new = []
-    changes_old = []
-    status = True
+    cmd = ('ps ax | grep "salt-proxy --proxyid={0}" | grep -v grep'
+           .format(proxyname))
+    cmdout = __salt__['cmd.run_all'](
+        cmd,
+        timeout=5,
+        python_shell=True)
+    if not cmdout['stdout']:
+        return False
+    else:
+        return True
 
-    # write the proxy file if necessary
-    proxyfile = '/etc/salt/proxy'
-    status, msg_new, msg_old = _proxy_conf_file(proxyfile)
-    changes_new.extend(msg_new)
-    changes_old.extend(msg_old)
-    # start the proxy process
-    if start:
-        cmd = ('ps ax | grep "salt-proxy --proxyid={0}" | grep -v grep'
-               .format(quote(proxyname)))
-        cmdout = __salt__['cmd.run_all'](
-            cmd,
-            timeout=5,
-            python_shell=True)
-        if not cmdout['stdout']:
+
+def _proxy_process(proxyname, test):
+    '''
+    Check and execute proxy process
+    '''
+    changes_old = []
+    changes_new = []
+    if not _is_proxy_running(proxyname):
+        if not test:
             __salt__['cmd.run'](
                 'salt-proxy --proxyid={0} -l info -d'.format(proxyname),
                 timeout=5)
-            changes_new.append('Started salt proxy for {0}'.format(proxyname))
-            log.debug('Proxy started')
-        else:
-            changes_old.append('Salt proxy already running for {0}'
+            changes_new.append('Salt Proxy: Started proxy process for {0}'
                                .format(proxyname))
-            log.debug('Proxy already running')
+        else:
+            changes_new.append('Salt Proxy: process {0} will be started'
+                               .format(proxyname))
+    else:
+        changes_old.append('Salt Proxy: already running for {0}'
+                           .format(proxyname))
+    return True, changes_new, changes_old
+
+
+def configure_proxy(name, proxyname='p8000', start=True):
+    '''
+    Create the salt proxy file and start the proxy process
+    if required
+
+    Parameters:
+        name:
+            The name of this state
+        proxyname:
+            Name to be used for this proxy (should match entries in pillar)
+        start:
+            Boolean indicating if the process should be started
+    '''
+    changes_new = []
+    changes_old = []
+    status_file = True
+    test = __opts__['test']
+
+    # write the proxy file if necessary
+    proxyfile = '/etc/salt/proxy'
+    status_file, msg_new, msg_old = _proxy_conf_file(proxyfile, test)
+    changes_new.extend(msg_new)
+    changes_old.extend(msg_old)
+    status_proc = False
+
+    # start the proxy process
+    if start:
+        status_proc, msg_new, msg_old = _proxy_process(quote(proxyname), test)
+        changes_old.extend(msg_old)
+        changes_new.extend(msg_new)
+    else:
+        changes_old.append('Start is False, not starting salt-proxy process')
+        log.debug('Process not started')
 
     return {
-        'result': status,
+        'result': status_file and status_proc,
         'changes': {
             'old': '\n'.join(changes_old),
             'new': '\n'.join(changes_new),
         },
         'name': proxyname,
-        'comment': 'Proxy config messages'
+        'comment': '{0} config messages'.format(name)
     }