diff --git a/doc/topics/master_tops/index.rst b/doc/topics/master_tops/index.rst index a078eb9c30..34e8e1c240 100644 --- a/doc/topics/master_tops/index.rst +++ b/doc/topics/master_tops/index.rst @@ -8,10 +8,9 @@ In 0.10.4 the `external_nodes` system was upgraded to allow for modular subsystems to be used to generate the top file data for a :ref:`highstate ` run on the master. -The old `external_nodes` option has been removed. -The master tops system contains a number of subsystems that -are loaded via the Salt loader interfaces like modules, states, returners, -runners, etc. +The old `external_nodes` option has been removed. The master tops system +provides a pluggable and extendable replacement for it, allowing for multiple +different subsystems to provide top file data. Using the new `master_tops` option is simple: @@ -38,24 +37,25 @@ for :mod:`Reclass `. for :mod:`Varstack `. -It's also possible to create custom master_tops modules. These modules must go -in a subdirectory called `tops` in the `extension_modules` directory. -The `extension_modules` directory is not defined by default (the -default `/srv/salt/_modules` will NOT work as of this release) +It's also possible to create custom master_tops modules. Simply place them into +``salt://_tops`` in the Salt fileserver and use the +:py:func:`saltutil.sync_tops ` runner to sync +them. If this runner function is not available, they can manually be placed +into ``extmods/tops``, relative to the master cachedir (in most cases the full +path will be ``/var/cache/salt/master/extmods/tops``). Custom tops modules are written like any other execution module, see the source -for the two modules above for examples of fully functional ones. Below is -a degenerate example: +for the two modules above for examples of fully functional ones. Below is a +bare-bones example: -/etc/salt/master: +**/etc/salt/master:** .. code-block:: yaml - extension_modules: /srv/salt/modules master_tops: customtop: True -/srv/salt/modules/tops/customtop.py: +**customtop.py:** (custom master_tops module) .. code-block:: python @@ -66,6 +66,7 @@ a degenerate example: log = logging.getLogger(__name__) + def __virtual__(): return __virtualname__ @@ -84,3 +85,10 @@ a degenerate example: ---------- base: - test + +.. note:: + If a master_tops module returns :ref:`top file ` data for a + given minion, it will be added to the states configured in the top file. It + will *not* replace it altogether. The Nitrogen release adds additional + functionality allowing a minion to treat master_tops as the single source + of truth, irrespective of the top file. diff --git a/salt/runners/saltutil.py b/salt/runners/saltutil.py index 5e6a43b480..75abfcf9f7 100644 --- a/salt/runners/saltutil.py +++ b/salt/runners/saltutil.py @@ -44,6 +44,7 @@ def sync_all(saltenv='base'): ret['queues'] = sync_queues(saltenv=saltenv) ret['pillar'] = sync_pillar(saltenv=saltenv) ret['utils'] = sync_utils(saltenv=saltenv) + ret['tops'] = sync_tops(saltenv=saltenv) return ret @@ -268,3 +269,22 @@ def sync_utils(saltenv='base'): salt-run saltutil.sync_utils ''' return salt.utils.extmods.sync(__opts__, 'utils', saltenv=saltenv)[0] + + +def sync_tops(saltenv='base'): + ''' + .. versionadded:: 2016.3.7,2016.11.4,Nitrogen + + Sync master_tops modules from ``salt://_tops`` to the master + + saltenv : base + The fileserver environment from which to sync. To sync from more than + one environment, pass a comma-separated list. + + CLI Example: + + .. code-block:: bash + + salt-run saltutil.sync_tops + ''' + return salt.utils.extmods.sync(__opts__, 'tops', saltenv=saltenv)[0]