Understanding salt environments

Question

I would like to know what is the utility of declaring environments in /etc/salt/master ?

Example :

file_roots:
  base:
    - /srv/salt
  env1:
    - /srv/salt/env1

This is the /srv/salt tree:

.
├── base
├── env1
│   └── domain1
│       ├── init.sls
│       └── nginx.conf
└── top.sls

And the top.sls:

env1:
  '*':
    - env1.domain1

This is the init.sls inside env1/domain1/

/etc/nginx/nginx.conf:
  file.managed:
      - source: salt://env1/domain1/nginx.conf 

When executing:

salt '*' state.sls env1.domain1

everything works fine.

But with highstate:

# salt '*' state.highstate
myHost:
    Data failed to compile:
----------
    No matching sls found for 'env1.domain1' in env 'env1'

Given that the environment "env1" is declared in master config.I changed my configuration and I have put :

- source: salt://domain1/nginx.conf 

instead of:

- source: salt://env1/domain1/nginx.conf 

I had this error :

 Comment: Source file salt://domain1/nginx.conf not found

Is there a misconfiguration somewhere ? What is the utility of declaring environments in master conf, if we can't call it directly using salt://subfolder instead of salt://environment/subfolder directly ?

I can't find a good documentation about creating environments and using them !

===Edit===

This is the new configuration:

The master:

file_roots:
  base:
    - /srv/salt/base
  env1:
    - /srv/salt/env1

The /srv/salt tree

.
├── base
│   └── init.sls
├── conf_template
├── env1
│   └── domain1
│       ├── init.sls
│       └── nginx.conf
└── top.sls

top.sls:

base:
  '*':
    - init
env1:
  '*':
    - domain1

And env1/domain1/init.sls:

/etc/nginx/nginx.conf:
  file.managed:
      - source: salt://domain1/nginx.conf

and the execution result:

salt '*' state.sls env1.domain1
myHost:
    Data failed to compile:
----------
    No matching sls found for 'env1.domain1' in env 'base'

Answer 1

No matching sls found for 'env1.domain1' in env 'env1'

I believe that's because the state reference should not include the environment, i.e. you have an extra env1, it should be:

env1:
  '*':
    - domain1

The other mistake you have is that you have env1 as a sub-directoy of base which can make things really confusing as this is not how environments are supposed to be structured.

Those are the only two mistakes I can spot and after fixing them, highstate should work as well as the reference to salt://domain1/nginx.conf (which is correct this way).

Finally, I believe environments are indeed confusing, and for me, I found I could better understand them by focusing on how they are actually implemented: multiple state trees. Technically, the concept of an "environment" doesn't exist. It's just one for us to utilize that feature.