# salt.states.loop

Loop state

Allows for looping over execution modules.

Added in version 2017.7.0.

In both examples below, the execution module function `boto_elb.get_instance_health` returns a list of dicts. The condition checks the `state`-key of the first dict in the returned list and compares its value to the string InService.

    wait_for_service_to_be_healthy:
      loop.until:
        - name: boto_elb.get_instance_health
        - condition: m_ret[0]['state'] == 'InService'
        - period: 5
        - timeout: 20
        - m_args:
          - {{ elb }}
        - m_kwargs:
            keyid: {{ access_key }}
            key: {{ secret_key }}
            instances: "{{ instance }}"

Warning

This state allows arbitrary python code to be executed through the condition parameter which is literally evaluated within the state. Please use caution.

Changed in version 3000.

A version that does not use eval is now available. It uses either the python `operator` to compare the result of the function called in `name`, which can be one of the following: lt, le, eq (default), ne, ge, gt. Alternatively, compare_operator can be filled with a function from an execution module in `__salt__` or `__utils__` like the example below. The function `data.subdict_match` checks if the `expected` expression matches the data returned by calling the `name` function (with passed `args` and `kwargs`).

    Wait for service to be healthy:
      loop.until_no_eval:
        - name: boto_elb.get_instance_health
        - expected: '0:state:InService'
        - compare_operator: data.subdict_match
        - period: 5
        - timeout: 20
        - args:
          - {{ elb }}
        - kwargs:
            keyid: {{ access_key }}
            key: {{ secret_key }}
            instances: "{{ instance }}"

salt.states.loop.until(name, m_args=None, m_kwargs=None, condition=None, period=1, timeout=60)

  Loop over an execution module until a condition is met.

  Parameters:

    - name (str) -- The name of the execution module

    - m_args (list) -- The execution module's positional arguments

    - m_kwargs (dict) -- The execution module's keyword arguments

    - condition (str) -- The condition which must be met for the loop to break. This should contain `m_ret` which is the return from the execution module.

    - period (int or float) -- The number of seconds to wait between executions

    - timeout (int or float) -- The timeout in seconds

salt.states.loop.until_no_eval(name, expected, compare_operator='eq', timeout=60, period=1, init_wait=0, args=None, kwargs=None)

  Generic waiter state that waits for a specific salt function to produce an expected result. The state fails if the function does not exist or raises an exception, or does not produce the expected result within the allotted retries.

  Parameters:

    - name (str) -- Name of the module.function to call

    - expected -- Expected return value. This can be almost anything.

    - compare_operator (str) -- Operator to use to compare the result of the module.function call with the expected value. This can be anything present in __salt__ or __utils__. Will be called with 2 args: result, expected.

    - timeout (int or float) -- Abort after this amount of seconds (excluding init_wait).

    - period (int or float) -- Time (in seconds) to wait between attempts.

    - init_wait (int or float) -- Time (in seconds) to wait before trying anything.

    - args (list) -- args to pass to the salt module.function.

    - kwargs (dict) -- kwargs to pass to the salt module.function.

  Added in version 3000.