salt.renderers.stateconf

### Navigation

- index
- modules |
- next |
- previous |
- « SaltStack.org |
- Documentation home
- Full list of builtin renderer modules »

# salt.renderers.stateconf

This module provides a custom renderer that process a salt file with a specified templating engine(eg, jinja) and a chosen data renderer(eg, yaml), extract arguments for any `stateconf.set` state and provide the extracted arguments (including salt specific args, such as 'require', etc) as template context. The goal is to make writing reusable/configurable/ parameterized salt files easier and cleaner, therefore, additionally, it also:

> - Recognizes the special state function, `stateconf.set`, that configures a default list of named arguments useable within the template context of the salt file. Example:

>       sls_params:
>         stateconf.set:
>           - name1: value1
>           - name2: value2
>           - name3:
>             - value1
>             - value2
>             - value3
>           - require_in:
>             - cmd: output

>       # --- end of state config ---

>       output:
>         cmd.run:
>           - name: |
>               echo 'name1=${sls_params.name1}
>                     name2=${sls_params.name2}
>                     name3[1]=${sls_params.name3[1]}
>               '

>   This even works with `include` + `extend` so that you can override the default configured arguments by including the salt file and then extend the `stateconf.set` states that come from the included salt file.

>   Notice that the end of configuration marker(`# --- end of state config --`) is needed to separate the use of 'stateconf.set' form the rest of your salt file.

> - Adds support for relative include and exclude of .sls files. Example:

>       include:
>         - .apache
>         - .db.mysql

>       exclude:
>         - sls: .users

>   If the above is written in a salt file at salt://some/where.sls then it will include salt://some/apache.sls and salt://some/db/mysql.sls, and exclude salt://some/users.ssl. Actually, it does that by rewriting the above `include` and `exclude` into:

>       include:
>         - some.apache
>         - some.db.mysql

>       exclude:
>         - sls: some.users

> - Adds a `sls_dir` context variable that expands to the directory containing the rendering salt file. So, you can write `salt://${sls_dir}/...` to reference templates files used by your salt file.

> - Prefixes any state id(declaration or reference) that starts with a dot(`.`) to avoid duplicated state ids when the salt file is included by other salt files.

>   For example, in the salt://some/file.sls, a state id such as `.sls_params` will be turned into `some.file::sls_params`.

>   Moreover, the leading dot trick can be used with extending state ids as well, so you can include relatively and extend relatively. For example, when extending a state in salt://some/other_file.sls, eg,:

>       include:
>         - .file

>       extend:
>         .file::sls_params:
>           stateconf.set:
>             - name1: something

>   Above will be pre-processed into:

>       include:
>         - some.file

>       extend:
>         some.file::sls_params:
>           stateconf.set:
>             - name1: something

> - Optionally(disable via the -G renderer option), generates a `stateconf.set` goal state(state id named as `.goal` by default) that requires all other states in the salt file.

>   Such goal state is intended to be required by some state in an including salt file. For example, in your webapp salt file, if you include a sls file that is supposed to setup Tomcat, you might want to make sure that all states in the Tomcat sls file will be executed before some state in the webapp sls file.

> - Optionally(enable via the -o renderer option), orders the states in a sls file by adding a require` requisite to each state such that every state requires the state defined just before it. The order of the states here is the order they are defined in the sls file.

>   By enabling this feature, you are basically agreeing to author your sls files in a way that gives up the explicit(or implicit?) ordering imposed by the use of `require`, `watch`, `require_in` or `watch_in` requisites, and instead, you rely on the order of states you define in the sls files. This may or may not be a better way for you. However, if there are many states defined in a sls file, then it tends to be easier to see the order they will be executed with this feature.

>   You are still allow to use all the requisites, with a few restricitons. You cannot `require` or `watch` a state defined after the current state. Similarly, in a state, you cannot `require_in` or `watch_in` a state defined before it. Breaking any of the two restrictions above will result in a state loop. The renderer will check for such incorrect uses if this feature is enabled.

>   Additionally, `names` declarations cannot be used with this feature because the way they are compiled into low states make it impossible to guarantee the order in which they will be executed. This is also checked by the renderer.

>   Finally, with the use of this feature, it becomes possible to easily make an included sls file execute all its states after some state(say, with id `X`) in the including sls file. All you have to do is to make state, `X`, `require_in` the first state defined in the included sls file.

When writing sls files with this renderer, you should avoid using what can be defined in a `name` argument of a state as the state's id. Instead, you should define the state id and the name argument separately for each state, and the id should be something meaningful and easy to reference within a requisite, and when referencing a state from a requisite, you should reference the state's id rather than its name. The reason is that this renderer might re-write or renames state id's and their references.

class `salt.renderers.stateconf.` `Bunch`

`salt.renderers.stateconf.` `add_goal_state`(data)

`salt.renderers.stateconf.` `add_implicit_requires`(data)

`salt.renderers.stateconf.` `extract_state_confs`(data, is_extend=False)

`salt.renderers.stateconf.` `has_names_decls`(data)

`salt.renderers.stateconf.` `nvlist`(thelist, names=None)

  Given a list of items:

      - whatever
      - name1: value1
      - name2:
        - key: value
        - key: value

  return a generator that yields each (item, key, value) tuple, skipping items that are not name-value's(dictionaries) or those not in the list of matching names. The item in the returned tuple is the single-key dictionary.

`salt.renderers.stateconf.` `nvlist2`(thelist, names=None)

  Like nvlist but applied one more time to each returned value. So, given a list, args, of arguments to a state like this:

      - name: echo test
      - cwd: /
      - require:
        - file: test.sh

  nvlist2(args, ['require']) would yield the tuple, (dict_item, 'file', 'test.sh') where dict_item is the single-key dictionary of {'file': 'test.sh'}.

`salt.renderers.stateconf.` `rename_state_ids`(data, sls, is_extend=False)

`salt.renderers.stateconf.` `render`(template_file, env='', sls='', argline='', **kws)

`salt.renderers.stateconf.` `rewrite_sls_includes_excludes`(data, sls)

`salt.renderers.stateconf.` `state_name`(sname)

  Return the name of the state regardless if sname is just the state name or a state.func name.

`salt.renderers.stateconf.` `statelist`(states_dict, sid_excludes=set(['exclude', 'include']))

## Comments

comments powered by Disqus

### Navigation

- index
- modules |
- next |
- previous |
- « SaltStack.org |
- Documentation home
- Full list of builtin renderer modules »