o

�N�g�J�@s�dZd
dl
Z
d
dlZd
dlZd
dlZd
dlZd
dlmZ
e
�	e
�
Zdd�Zej
j�ed�Zdd�Zd	d
�Zddd�
Zd
d�Zdd�Zdd�Zej
j�ed�ZdS)a�
Execution of Salt modules from within states
============================================

.. note::

    As of the 3005 release, you no longer need to opt-in to the new style of
    calling ``module.run``. The following config can be removed from ``/etc/salt/minion``:

    .. code-block:: yaml

        use_superseded:
          - module.run

    Both 'new' and 'legacy' styles of calling ``module.run`` are supported.


With `module.run` these states allow individual execution module calls to be
made via states. Here's a contrived example, to show you how it's done:

.. code-block:: yaml

    # New Style
    test.random_hash:
      module.run:
        - test.random_hash:
          - size: 42
          - hash_type: sha256

    # Legacy Style
    test.random_hash:
      module.run:
        - size: 42
        - hash_type: sha256

In the new style, the state ID (``test.random_hash``, in this case) is
irrelevant when using ``module.run``. It could have very well been written:

.. code-block:: yaml

    Generate a random hash:
      module.run:
        - test.random_hash:
          - size: 42
          - hash_type: sha256

For a simple state like that it's not a big deal, but if the module you're
using has certain parameters, things can get cluttered, fast. Using the
contrived custom module (stuck in ``/srv/salt/_modules/foo.py``, or your
configured file_roots_):

.. code-block:: python

    def bar(name, names, fun, state, saltenv):
        return "Name: {name} Names: {names} Fun: {fun} State: {state} Saltenv: {saltenv}".format(**locals())

Your legacy state has to look like this:

.. code-block:: yaml

    # Legacy style
    Unfortunate example:
      module.run:
      - name: foo.bar
      - m_name: Some name
      - m_names:
        - Such names
        - very wow
      - m_state: Arkansas
      - m_fun: Such fun
      - m_saltenv: Salty

With the new style it's much cleaner:

.. code-block:: yaml

    # New style
    Better:
      module.run:
      - foo.bar:
        - name: Some name
        - names:
          - Such names
          - very wow
        - state: Arkansas
        - fun: Such fun
        - saltenv: Salty

The new style also allows multiple modules in one state. For instance, you can
do this:

.. code-block:: yaml

    Do many things:
      module.run:
        - test.random_hash:
          - size: 10
          - hash_type: md5
        # Note the `:` at the end
        - test.true:
        - test.arg:
          - this
          - has
          - args
          - and: kwargs
          - isn't: that neat?
        # Note the `:` at the end, too
        - test.version:
        - test.fib:
          - 4

Where in the legacy style you would have had to split your states like this:

.. code-block:: yaml

    test.random_hash:
      module.run:
        - size: 10
        - hash_type: md5

    test.nop:
      module.run

    test.arg:
      module.run:
        - args:
          - this
          - has
          - args
        - kwargs:
            and: kwargs
            isn't: that neat?

    test.version:
      module.run

Another difference is that in the legacy style, unconsumed arguments to the
``module`` state were simply passed into the module function being executed:

.. code-block:: yaml

    show off module.run with args:
      module.run:
        - name: test.random_hash
        - size: 42
        - hash_type: sha256

The new style is much more explicit, with the arguments and keyword arguments
being nested under the name of the function:

.. code-block:: yaml

    show off module.run with args:
      module.run:
        # Note the lack of `name: `, and trailing `:`
        - test.random_hash:
          - size: 42
          - hash_type: sha256

If the function takes ``*args``, they can be passed in as well:

.. code-block:: yaml

    args and kwargs:
      module.run:
        - test.arg:
          - isn't
          - this
          - fun
          - this: that
          - salt: stack

Modern Examples
---------------

Here are some other examples using the modern ``module.run``:

.. code-block:: yaml

    fetch_out_of_band:
      module.run:
        - git.fetch:
          - cwd: /path/to/my/repo
          - user: myuser
          - opts: '--all'

A more complex example:

.. code-block:: yaml

    eventsviewer:
      module.run:
        - task.create_task:
          - name: events-viewer
          - user_name: System
          - action_type: Execute
          - cmd: 'c:\netops\scripts\events_viewer.bat'
          - trigger_type: 'Daily'
          - start_date: '2017-1-20'
          - start_time: '11:59PM'

It is sometimes desirable to trigger a function call after a state is executed,
for this the :mod:`module.wait <salt.states.module.wait>` state can be used:

.. code-block:: yaml

    add example to hosts:
      file.append:
        - name: /etc/hosts
        - text: 203.0.113.13     example.com

    # New Style
    mine.send:
      module.wait:
        # Again, note the trailing `:`
        - hosts.list_hosts:
        - watch:
          - file: add example to hosts

Legacy (Default) Examples
-------------------------

If you're using the legacy ``module.run``, due to how the state system works,
if a module function accepts an argument called, ``name``, then ``m_name`` must
be used to specify that argument, to avoid a collision with the ``name``
argument.

Here is a list of keywords hidden by the state system, which must be prefixed
with ``m_``:

* fun
* name
* names
* state
* saltenv

For example:

.. code-block:: yaml

    disable_nfs:
      module.run:
        - name: service.disable
        - m_name: nfs

Note that some modules read all or some of the arguments from a list of keyword
arguments. For example:

.. code-block:: yaml

    mine.send:
      module.run:
        - func: network.ip_addrs
        - kwargs:
            interface: eth0

.. code-block:: yaml

    cloud.create:
      module.run:
        - func: cloud.create
        - provider: test-provider
        - m_names:
          - test-vlad
        - kwargs: {
              ssh_username: 'ubuntu',
              image: 'ami-8d6d9daa',
              securitygroup: 'default',
              size: 'c3.large',
              location: 'ap-northeast-1',
              delvol_on_destroy: 'True'
          }

Other modules take the keyword arguments using this style:

.. code-block:: yaml

     mac_enable_ssh:
       module.run:
         - name: system.set_remote_login
         - enable: True

Another example that creates a recurring task that runs a batch file on a
Windows system:

.. code-block:: yaml

    eventsviewer:
      module.run:
        - name: task.create_task
        - m_name: 'events-viewer'
        - user_name: System
        - kwargs: {
              action_type: 'Execute',
              cmd: 'c:\netops\scripts\events_viewer.bat',
              trigger_type: 'Daily',
              start_date: '2017-1-20',
              start_time: '11:59PM'
        }

.. _file_roots: https://docs.saltproject.io/en/latest/ref/configuration/master.html#file-roots
�N)
�SaltInvocationErrorc
Ks|id
dd�S)a�
    Run a single module function only if the watch statement calls it

    ``name``
        The module function to execute

    ``**kwargs``
        Pass any arguments needed to execute the function

    .. note::
        Like the :mod:`cmd.run <salt.states.cmd.run>` state, this state will
        return ``True`` but not actually execute, unless one of the following
        two things happens:

        1. The state has a :ref:`watch requisite <requisites-watch>`, and
           the state which it is watching changes.

        2. Another state has a :ref:`watch_in requisite
           <requisites-watch-in>` which references this state, and the state
           wth the ``watch_in`` changes.
    T�)�name�changes�result�comment�)r�kwargsrr�F/opt/saltstack/salt/lib/python3.10/site-packages/salt/states/module.py�wait;
sr�watchcKs�d
}
t|�
}gd�
}|D]}||vr|�
|�

q|D]}|�d�
dkr%d}
q|s,|r,d}
|
r=t�dtd�
td
i|�
�
St�dtd�
td
i|�
�
S)a:
    Run a single module function or a range of module functions in a batch.
    Supersedes ``module.run`` function, which requires ``m_`` prefix to
    function-specific parameters.

    :param returner:
        Specify a common returner for the whole batch to send the return data

    :param kwargs:
        Pass any arguments needed to execute the function(s)

    .. code-block:: yaml

      some_id_of_state:
        module.run:
          - network.ip_addrs:
            - interface: eth0
          - cloud.create:
            - names:
              - test-isbm-1
              - test-isbm-2
            - ssh_username: sles
            - image: sles12sp2
            - securitygroup: default
            - size: 'c3.large'
            - location: ap-northeast-1
            - delvol_on_destroy: True


    :return:
    F)rZ__reqs__Zsfun�
.���Tz%Detected legacy module.run syntax: %sZ__id__z%Using new style module.run syntax: %sNr)�list�remove�find�log�debugZ__low__�_legacy_run�_run)r	Z
legacy_run�keysZignored_kwargs�itemrrrr
�runX
s$!




�

�




rcKs>d
|vr	|�d
�

t
|�
iddd�}
dd�|D�
}g}g}|D]}|�d�
d}|tv
r2|�|�

qtdr;|�|�

q|sHd	|
d
<d|
d<|
S|sL|r�d
�|rbdjt|�
dkpYdd�|�
p_dd�pcd|rwdjt|�
dkpndd�|�
ptdd�pxdg�
�	�|
d
<|r�d|
d<|
Sg}g}|D]}|�d�
d}zVt
||�d�
|�|�
d�}	t|	|
d�di��s�t
|	t�r�|�d�||	�d
d���

|	dur�|�d|�d|	���

n|�d�|t
|	t�r�|	�d
d�n
|	��

|	|
d|<Wq�ttf�
y
}

z|�d|�d|
���

WYd}
~
q�d}
~
w
wd�||�
|
d
<t|�
|
d<|
S)Nrr�rrrrc
Ssg|]}
d|
vr|
�qS)
r
r)�.0�funcrrr
�
<listcomp>�
sz_run.<locals>.<listcomp>�
:r
�testzNo function provided.rFr�
 z"Unavailable function{plr}: {func}.�
z, )Zplrrz$Function{plr} {func} to be executed.�returner)r!�	func_argsr�retz'{}' failed: {}z(error message N/A)�
'z': z{}: {}ZSuccessz
' failed: )�popr�split�__salt__�append�__opts__�join�format�len�strip�_call_function�get�_get_result�
isinstance�dictr�	TypeError�bool)r	r#Z	functions�missingZtestsrZfailures�successZ_func�func_ret�exrrr
r�
s�




�








�





��


����
�






�




��
�

���
�
"
��
rcCs~|d
urg}|d
uri}tj
jjt|g
|�
Ri|�
�
}|
d
u
r=tj�tt�}|
|vr=||
td||tj
j�	t�
d��

|S)aI

    Calls a function from the specified module.

    :param str name: module.function of the function to call
    :param dict returner: Returner specification to use.
    :param list func_args: List with args and dicts of kwargs (one dict per kwarg)
        to pass to the function.
    :return: Result of the function call
    N�id�r9r#�fun�jid)
�salt�utils�	functools�
call_functionr'�loader�	returnersr)r<�gen_jid)rr!r"Zfunc_kwargs�mretrBrrr
r.�
s 


 






��r.c

Ks^|id
dd�}|tv
rd|�d�|d<d|d<|St
d	r'd|�d
�|d<|Stjj�t|�
}g}i}d}d}t|jt�rCt|j�
}t|j	t
�rNt|j	�
}t|dd
d
�D]}||}	||	d
krm|j	|	||j|<qV|D]L}
|
dkr�d|
vr�|
�d�
||
<n/|
dkr�d|
vr�|
�d�
||
<n|
dkr�d|
vr�|
�d�
||
<n|
dkr�d|
vr�|
�d�
||
<|
|
vr�|
�|
�
||
<qpt
�}|jD]J}
|
dkr�d}n|
dkr�d}n|
dkr�d}n|
dkr�d}n	|
dkr�d}n|
}||
v
r�|
|v
r�|�|�

q�|
|v�
r|�||
�

q�|�|
�|�
�

q�|�
r*d}
|D]
}
|
d|
��7}
�
q|
|d<d|d<|S|j�
r�|jdk�
r7d}n'|jdk�
r@d}n|jdk�
rId}n|jdk�
rRd}n|jdk�
r[d}n|j}||
v�
r�|
�|�
}t|t��
s~d}|�|j�
|d<d|d<|S|�|�

i}|j�
r�|j|
v�
r�|
�|j�
}t|t��
s�d}|�|j�
|d<d|d<|Sz|j�
r�t||i|�
�
}nt||�}Wn!t�
y�
}
zd�||�|d<d|d<|WYd}~Sd}~w
w|du
�
s�|ik�
r�||dd<d|
v�rt
d ||tjj�t
�
d!�}tj�t
t�}|
d|v�r||
d|�

d|�d"�|d<t||d�|d<|S)#a\

    .. deprecated:: 2017.7.0
       Function name stays the same, behaviour will change.

    Run a single module function

    ``name``
        The module function to execute

    ``returner``
        Specify the returner to send the return of the module execution to

    ``kwargs``
        Pass any arguments needed to execute the function
    rNrzModule function z is not availablerFrrz is set to executer
r rrZm_namer;Zm_fun�stateZm_stateZsaltenvZ	m_saltenv�namesZm_namesz$The following arguments are missing:rz'{0}' must be a list.z'{0}' must be a dict.z4Module function {} threw an exception. Exception: {}rr#r!r9r:z	 executed)r'r)r=r>�argsZget_function_argspecr1rr,�defaults�tuple�ranger%�set�addr(�varargsr+�extend�keywordsr2�	Exceptionr<rCrArBr0)rr	r#ZaspecrGrHZarglenZdeflenZindZminus�argr5ZrargrrM�msgZnkwargsrD�
eZret_retrBrrr
rs�

















�


�


�


�




�





















































�


�
��




�



rcCs�d
}t|t
�r|�dd�dkrd}|St|t�r|}|S|
�di�}t|t
�rHt|�di�t�r8|�di�}|S|�dd�dkrDd}|St|�
}|S)NT�retcoder
Fr#r)r1r2r/r4�_get_dict_result)r7r�resZchanges_retrrr
r0�s"


�
�



	�
�r0c
CsTd
}
|��D]!\}}|dkr|durd}

|
St
|t�r't|�
}
|
dur'
|
Sq|
S)NTrF)�itemsr1r2rU)�noder#�key�valrrr
rU�s





�



�rU�	mod_watch)NNN)�__doc__�loggingZsalt.loaderr=Zsalt.utils.argsZsalt.utils.functoolsZsalt.utils.jidZsalt.exceptionsr�	getLogger�__name__rrr>r?Zalias_functionrrrr.rr0rUr[rrrr
�<module>
s(1




8
T