I am confused about jinja2 in saltstack

I read the state file about vim-formula on github --> Here

There is a file named salt.sls ：

{% from "vim/map.jinja" import vim with context %}
include:
  - vim
sakt_vimfiles:
  file.recurse:
    - name: {{ vim.share_dir }}
    - source: salt://vim/files/salt

But I couldn't find vim.sls which included in salt.sls in current directory.I learned the guidbook in saltstack's website,and I know the word include means to reuse a state file,right?

So I think it must be related to the jinja2 {% from "vim/map.jinja" import vim with context %}

and map.jinja :

{% set vim = salt['grains.filter_by']({
'Arch': {
    'pkg': 'vim',
    'share_dir': '/usr/share/vim/vimfiles',
    'group': 'root',
    'config_root': '/etc',
},
'Debian': {
    'pkg': 'vim',
    'share_dir': '/usr/share/vim/vimfiles',
    'group': 'root',
    'config_root': '/etc/vim',
},
'RedHat': {
    'pkg': 'vim-enhanced',
    'share_dir': '/usr/share/vim/vimfiles',
    'group': 'root',
    'config_root': '/etc',
},
'Suse': {
    'pkg': 'vim',
    'share_dir': '/usr/share/vim/site',
    'group': 'root',
    'config_root': '/etc',
},
'FreeBSD': {
    'pkg': 'vim',
    'share_dir': '/usr/local/share/vim/vimfiles',
    'group': 'wheel',
    'config_root': '/etc',
},
}, merge=salt['pillar.get']('vim:lookup')) %}

Solution

I must agree, it is insane to read Jinja. And it is even WORST if you are a newbie for salt file structure. It is all about the poor emphasize on basic inside the documentation that cause confusion. Indeed, you need to understand many basic saltstack setup structure to avoid confusion.

Now to the answer .

Imagine you copy the whole formula folder to your salt-states folder, say your (salt master configuration /etc/salt/master) files_root: are /srv/salt/states

Actually, the formula ASSUME you copy the github formula source /vim folder under the file roots. Thus you should have something like /srv/salt/states/vim.

Now come to the fun part : the files_roots is /srv/salt/states, so for salt-master file-system, anything start from the folder are consider salt:// . And since your vim folder is under it, so it will be refer as salt://vim.

Now back to your salt.sls in the /srv/salt/states/vim, it have no problem finding the include : - vim

The Saltstatck Get started is much better for beginner to start with. Just repeat the tutorial for a few time, it will help solve most of the confusion.

(more) Again another basic : How saltstack traverse folder. This also explain how the include find the correct file. If you have something like this

base:
  myserver:
    - app
    - db.myserver

So for the first app, there is two ways to write the state First way : put the state into app.sls Second way : create a folder call app , then put the state into app/init.sls

The first way is straightforward. The second way is kinda "magic" if you didn't read the basic. In fact, init.sls is the state file. You can put many .sls inside the app folder. But salt don't care about other, unless you call them explicit, i.e. , as in the example, db.server

# This is the first way, direct reference to the sls file
+--app.sls
+--/db
   +--myserver.sls 

# Second way, using init.sls as anchor inside folder.
+--/app
   +-- init.sls
+--/db
   +--/myserver
      +--init.sls

So come to Second way db.server Now this look straightforward, salt master just traverse into salt://db/ folder, look for server.sls. However, mix with the first way, you should know, You may write the state file into /db/server/init.sls, that's how salt looks for the file.

Now, go back to your vim formula folder, just read the /vim/init.sls. Now you understand the include: vim mean traverse into salt://vim/init.sls OR salt://vim.sls .

You may ask, what if mix both structure? My suggestion : Don't do it. You will confuse yourself and those who maintain your saltstack .