Generating documentation for salt stack states

Question

I have a repository with salt states for provisioning my cluster of servers in the cloud. Over time, I kept on adding more states - the .sls files - into this repo. Now im starting to struggle what is what and what is where.

I am wondering if there is a there is some software utility/package that will generate documentation off my states repository, preferably as html pages, so that I can browse them and see their interdependencies.

UPDATE:

The state sls files look like this:

include:
    - states.core.pip

virtualenv:
    pip.installed:
        - require:
            - sls: states.core.pip

virtualenvwrapper:
    pip.installed:
        - require:
            - sls: states.core.pip

And another sls example:

{% set user_home = '/home/username' %}

my_executable_virtualenv:
    virtualenv.managed:
        - name: {{ user_home }}/.virtualenvs/my_executable_virtualenv
        - user: username
        - system_site_packages: False
        - pip_pkgs:
            - requests
            - numpy
        - pip_upgrade: True
        - require:
            - sls: states.core

my_executable_supervisor_entry:
    file.managed:
        - name: /etc/supervisor/conf.d/my_executable.conf
        - source: salt://files/supervisor_config/my_executable.conf
        - user: username
        - group: username
        - mode: 644
        - makedirs: False
        - require:
            - sls: states.core

@Tschallacka Yes. I have updated the question and added examples. — dopstar, Nov 14 '17 at 11:05

score 0 · Answer 1 · answered Oct 30 '17 at 12:54

0

I did some research and found that salt stack has created one. It does work as HTML pages too. According to the documentation. If you have python installed installing Sphinx is as easy as doing C:\> pip install sphinx
Salt-stacks docs on this can be found here. According to the docs making the HTML documentation is as easy as doing:

cd /path/to/salt/doc
make HTML

I hope this answer is what you were looking for!

answered Oct 30 '17 at 12:54

1

That is not what I am looking for. I am looking for something that will parse the sls files and generate docs for me. That looks like it parses the docstrings of salt modules. – dopstar Nov 07 '17 at 12:18

score 0 · Answer 2 · answered Feb 27 '18 at 09:06

0

This needs a custom plugin which needs to be written. There is no plugins directly available to render sls files.

There are some plugins available for rendering YAML files, may be you can modify the same to suite your requirement.

answered Feb 27 '18 at 09:06

Prashanth Goud B

44
5

score 0 · Answer 3 · answered Feb 02 '22 at 14:10

You can use some of the functions in the state module to list all the everything in the highstate for a minion:

# salt-call state.show_states --out=yaml
local:
- ufw.package.install
- ufw.config.file
- ufw.service.enable
- ufw.service.reload
- ufw.config.services
- ufw.config.applications
- ufw.service.running
- apt.apt_conf
- apt.unattended
- cacerts
- kerberos
- network
- editor
- mounts
- openssh
- openssh.config_ini
- openssh.known_hosts
...

And then view the compiled data for each one (also works with states not in the highstate):

# salt-call state.show_sls editor --out=yaml
local:
  vim-tiny:
    pkg:
    - installed
    - order: 10000
    __sls__: csrf.editor
    __env__: base
  editor:
    alternatives:
    - path: /usr/bin/vim.tiny
    - set
    - order: 10001
    __sls__: csrf.editor
    __env__: base

Or to get the entire highstate at once with state.show_highstate.

I'm not aware of any tools to build HTML documentation from that. You'd have to do that yourself.

To access all states (not just a particular highstate), you can use salt-run fileserver.file_list | grep '.sls$' to find every state, and salt-run state.orchestrate_show_sls to get the rendered data for each (though you may need to supply pillar data).

Generating documentation for salt stack states

3 Answers3