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