How does "names" work?

[Mogaba]

Hello,

I don't understand how "names" work. The docs https://docs.saltproject.io/en/latest/ref/states/highstate.html#names-declaration claims that this state:

test_files:
  file.managed:
    - names:
        - file1
        - file2

will be converted to:

file1:
  file.managed

file2:
  file.managed

But when I check the lowstate I see states with the same IDs:
$ salt test-altsp state.show_low_sls test

test-altsp:
    |_
      ----------
      __env__:
          base
      __id__:
          test_files
      __sls__:
          test
      fun:
          managed
      name:
          file1
      order:
          10000.0001
      state:
          file
    |_
      ----------
      __env__:
          base
      __id__:
          test_files
      __sls__:
          test
      fun:
          managed
      name:
          file2
      order:
          10000.0002
      state:
          file

But the docs says that you can't have two states with same IDs! So how does this work?

[lkubb]

I think you're pointing out an oversimplification in the docs.

In general, duplicate state IDs are disallowed in the highstate data structure because it's a mapping, where duplicate keys would necessarily overwrite each other (and, if defined in the same SLS, be unrepresentable).

The names parameter influences the state compiler (which compiles the highstate data structure into lowstate chunks), specifically here:

salt/salt/state.py

Lines 676 to 692 in 9233e1c

	if names:
	name_order = 1
	for entry in names:
	live = copy.deepcopy(chunk)
	if isinstance(entry, dict):
	low_name = next(iter(entry.keys()))
	live["name"] = low_name
	list(map(live.update, entry[low_name]))
	else:
	live["name"] = entry
	live["name_order"] = name_order
	name_order = name_order + 1
	for fun in funcs:
	live["fun"] = fun
	self.dependency_dag.add_chunk(live, False)
	chunks.append(live)
	break

A more accurate simplification:

For each names item, it copies the corresponding state, sets a new name (+ applies overrides if defined) and appends it to the lowstate, which is a list of individual state module calls (chunks). Since state IDs are not used to index these chunks, duplicate IDs are (somewhat) acceptable here.

This cannot be communicated properly using the YAML representation of the highstate because it's invalid:

Note: The referenced example state using pkg.installed is flawed. You almost never want to use names with pkg.installed since that causes each package to be installed separately. Use the pkgs parameter, unless you need each package to be require-able individually via - pkg: python-django etc. I'm using file.absent here instead.

unwanted-files:
  file.absent:
    - names:
      - /foo
      - /bar
      - /baz

=>

(highstate, invalid YAML/data structure)

unwanted-files:
  file.absent:
    - name: /foo
unwanted-files:
  file.absent:
    - name: /bar
unwanted-files:
  file.absent:
    - name: /baz

(simplified lowstate, valid YAML/data structure)

- id: unwanted-files
  name: /foo
  state: file
  fun: absent
- id: unwanted-files
  name: /bar
  state: file
  fun: absent
- id: unwanted-files
  name: /baz
  state: file
  fun: absent

[whytewolf]

please. never use pkg as an example for names. i know it seems the most simple way to show it. but many people who see an example won't go and read the docs and find that pkg has a pkgs option that should be used over names in its case. and when pkg uses names over pkgs it will severely slow down a state execution if you don't have aggregate turned on.

please use file or service instead. as they tend to be the more common actually use cases for names.

otherwise spot on.

[lkubb]

Agreed. Note that I was directly quoting the referenced docs example though, which should be fixed. I'll add a note above.

[Mogaba]

Thank you for the explanation!