Advice for getting started with Salt

User Support General
1

I apologise to anyone seeing this for a second time*

Can anyone suggest some documentation source, or a heavily commented set of files which might help me to understand the concepts and terminology behind and underlying salt.

I’ve tried the salt upstream, and various other sites, but I found myself confused by a lot of the docs and guides, which seem to confound the concepts I am familiar with, like execution, state, action, etc.

Even after several attempts, I do not have an intuition about pillars, grains, salt stacks, and so on. Maybe I am looking for too much meaning in the names, and there are not really clever metaphors in there.

Maybe it’s more obvious if one comes from ansible or something similar, but I don’t… and every time I try to work out what is happening in Salt it makes me feel really stupid!

Who can help me to un-stupid myself?

* this is an edited duplicate of my unthinking hijack attempt here :

2

I am still relatively new to Qubes OS (and Salt) myself. The following community guide helped me to get started with using Salt:

It has some examples for using Salt with qubes and useful links for further reading like the Salt User Guide.

3 Likes
3
3 Likes
4

https://sanet.st/search/?q=saltstack

5

There’s a guide on the Forum.
You could also take a look at my notes which include
notes on salt with examples, which take you though from absolute basic
use up to more complex worked examples.
These are from a course I’ve run, but they should give you an idea of how
to get started with salt.

These are just terms that press the salt metaphors a little too hard.
In Qubes
pillar - system wide storage of variables and parameters, that can be
used within salt states.
grains - information derived in individual qubes/templates
salt stack - Howling Wolf can tell you more.

You can be productive with salt in Qubes within minutes. (Instead of
installing packages in templates, write states that install the packages

  • then you have a record of what you have done, and can easily
    replicate your system after backing up these states.)

You can leverage the large number of salt modules, but in truth you
can build a system using very few.

If you need specific help, just ask.

I never presume to speak for the Qubes team.
When I comment in the Forum I speak for myself.

1 Like
6

Thank you, All, for your replies.
More are welcome. I think I have looked at all the sources above, but never at the same time, and probably none to the depth they deserve.

I am beginning to understand my problem with understanding…

@unman has cleared my doubt about the “salty” metaphors. Maybe the most useful one I imagined is that “grains” are sprinkled around multiple hosts, and the “pillar” is in the master “temple” (?).

Without anyone trying to answer all my questions, I am wondering:

How much, and how, folk use different methods for managing their states and setups. :

  • Permanently enabled “tops”, and for what purposes? For updating? Others?
  • A top file is not necessary, I think, but for recording what you have done or for repeating and reimplementing, do you make them anyway? Otherwise it seems like I just need a higher level of my “big list of previous actions”. Or keep a directory per target, to keep a collection of the SLS applied to each target? Or do you rely on the system journal…?
  • Just one-off applications?
  • Other tricks for keeping track of what has been done, and where?
  • Tricks for undoing…

I suppose I am thinking of several distinct uses…

  • Re-creation of my personal setup, with salt plus backup restores. A full duplicate.
  • Duplication/provisioning a new machine, with my preferred configuration (or someone else’s).
  • Playing with e.g. sys-gui/management-vm and similar, with the possibility to scrap a set of badly set-up VMs, and start again.
  • Possibly others exist which might be interesting?
7

They retain the known state. When you have something configured through salt you can just highstate to make sure that the salt files override any other (maybe accidental) changes.

When you have everything set up using top files and state it makes it trivial to update your template VMs, which is something I’ve heard people have issues with in qubes when they modify the template manually and lose all those changes when they update.

1 Like
8

Salt is VERY good for letting you recreate your system (as others here have noted). As a result I only bother backing up about five different VMs (one of which is a “repository” that I keep copies of salt files on–and I manage two different systems with it); anything else I can recreate if there’s a hard “crash” of my system.

I end up using a combination of salt and bash, because I like to clone a vm, add software, clone that VM and add more software to the second clone. There’s no way I can find to prevent Salt from doing the second clone immediately after the first clone–i.e., before it finishes installing software on the first clone (since the cloning happens on dom0 and the installing happens in the VM).

One other thing to watch out for: If you find this section in the QubesOS documentation: Salt (management software) | Qubes OS it is titled “All Qubes Specific States” which is misleading, it doesn’t list all of them (unless someone has updated it in the last couple of years). Scroll down to the bottom of the page and there is a link labeled “Qubes Specifc Modules” (qubes-mgmt-salt-dom0-qvm/README.rst at master · QubesOS/qubes-mgmt-salt-dom0-qvm · GitHub) which IS complete (and there’s some useful stuff in there).

1 Like
9

More gold is here, from @SteveC @PolyT , adding to @solene and @dhimh (not forgetting @unman, of course) - thank you all. I think I needed a wider perspective, and this has helped a lot.

I feel there must be a solution to the problem of how to

It seems to me like that would be quite educational.

10

I would love to solve that problem…unfortunately even unman (our resident salt guru) conceded there was no way to issue one salt command to do it.

1 Like
11

As so often, I was wrong.

test/clone.sls:

# vim: set syntax=yaml ts=2 sw=2 sts=2 et :
#

test_precursor:
  qvm.template_installed:
    - name: debian-12-minimal

clone_test:
  qvm.clone:
    - name: template-test
    - source: debian-12-minimal
    - require: 
      - test_precursor

test/install.sls:

{% if grains['nodename'] != 'dom0' %}
install_orca:
  pkg.latest:
    - pkgs:
      - orca
{% endif %}

test/install2.sls:

# vim: set syntax=yaml ts=2 sw=2 sts=2 et :
#

orca_install:
  cmd.run:
    - name: 'qubesctl --skip-dom0 --targets=template-test state.apply test.install'
    - runas: root
    - require:
      - qvm: template-test

test/clone2.sls:

# vim: set syntax=yaml ts=2 sw=2 sts=2 et :
#

clone_test2:
  qvm.clone:
    - name: template-test2
    - source: template-test
    - require:
      - orca_install

test/test.top:

# vim: set syntax=yaml ts=2 sw=2 sts=2 et :

base:
  'dom0':
    - test.clone
    - test.install2
    - test.clone2

Notice the use of require statements to ensure that everything runs in
the correct order: not strictly necessary, but nice.
Then enable and run.

qubesctl top.enable test.test
qubesctl --show-output state.apply

I hope that formatting is good.

I never presume to speak for the Qubes team.
When I comment in the Forum I speak for myself.

2 Likes
12

If I understand this, the key “trick” here is to actually run the install on the first template as a command from dom0 (it’s a qubesctl command), which makes it a state run on dom0 (or in other words, make a “wrapper” around running the sls on the template), rather than what one would normally do, run the sls on the vm directly. (apologies for not using the correct salt-speak; I hope my meaning is clear anyhow).

Will give this a try sometime soon. If my understanding is correct, I can fix formatting issues (if any).

13

Right. It’s just a matter of keeping states in dom0, so that they
are run in correct order before the second clone. That accords with the
order of salting in Qubes - dom0, templates, AppVMs.
Once that is done, any other install or configuration can be done with
usual template targets.

I never presume to speak for the Qubes team.
When I comment in the Forum I speak for myself.

1 Like
14

BEWARE that salt is intolerant of capital letters in your path for enabling a top file. Neither in the path or the .top filename.

Also I invariably have to sudo every single salt command because I don’t have access to some log directory (/var/log/salt/minion). Is that actually best, or would it be OK if I just chmod that dang directory?

15

OK I give up.

I can’t get a top file to play with this.

I am set up for a “user” salt environment (so my stuff will be in /srv/user_salt).

I made a subdirectory “x” (/srv/user_salt/x). In that directory: x.top

user:
     'dom0':
        - x.clone

/srv/user_salt/x/x.clone

source_exists:
    qvm.exists:
        - name: deb12a-base

clone_test:
    qvm.clone:
        - name: X-networked
        - source: deb12a-base
        - require:
              --  source_exists

I can run x.clone directly with:
sudo qubesctl state.apply x.clone saltenv=user
no problem.

But when I try to use the top file I run into all sorts of issues.
sudo qubesctl top.enable x.x
seems to work (but note, no saltenv=user appears to be necessary. It also doesn’t seem to harm anything if it’s added to the end of that command line)

checking with sudo qubesctl top.enabled shows me:

local:
      -------------
      user:
             - /srv/salt/_tops/user/x.x.top

running sudo qubesctl state.apply first gives me a warning about multiple top files being found (even though only one is enabled).

I then get the error that state ‘qvm.exists’ was not found in SLS ‘x.clone’
Reason: ‘qvm.exists’ is not available.

And both source_id and clone_test fail, of course.

Attempting to run sudo qubectl --show-output state.apply saltenv=user basically trashes salt; I get a bunc of specified ext_pillar interface messages that qvm_features, _prefs, _tags, _features, etc. are unavailable. At that point no salt command will work, and I have to issue sudo qubesctl saltutil.sync_all to fix it.

If I do not run sudo qubesctl --show-output state.apply (immediately after fixing salt) but rather sudo qubesctl --show-output state.apply saltenv=user I instead get the error message “no Top file or master_tops data matches found. Please see master log for details”

So basically, I can’t get the top file to work for some reason. I can continue piecemeal I suppose.

16

In my previous post I referred to a file /srv/user_salt/x/x.clone; that was a typo on my part; it is actually /srv/user_salt/x/clone.sls