States

A state describes how a machine should be: "this file exists with this content", "nginx is installed and running", "this user exists". Applying a state changes only what differs, so you can apply it again any time to put things back the way they should be.

To open states: choose Automation > States.

The page has three parts: Your states, the states you can run, each with a group picker, Dry run, and Apply; Add a state, with two tabs, From the library and Write your own; and Recent runs.

Library#

Add a state > From the library has ready-made states for common jobs, grouped by Software, Services, People, Files, Security, Network, and System:

Choose an item, fill in its blanks, and choose Preview: Gardience shows the exact state it would save. Save saves it under Your states, where you dry-run it first to see what would change on each machine, then apply it to a group, or to one machine from that machine's page. Library states use only the safe state functions, so they work with command execution off, and they pass the same check as a state you write yourself. Input that could change what a state does (extra lines, shell characters, template markers) is refused before anything is saved.

Write one#

Under Add a state > Write your own, give it a name (lowercase letters, digits and underscores) and write it in YAML. For example, to keep a file in place with set content:

keep_example_file:
  file.managed:
    - name: /opt/scripts/example.txt
    - makedirs: True
    - mode: '0644'
    - contents: |
        This file is managed by Gardience.

Or ask: the Ask Gardience button writes a state from plain words ("create a state that keeps example.txt in /opt/scripts"), shows it to you, and saves it when you choose Save this state.

Saving is for admins. The state is checked on the server first (see below); if it is refused, the reason is shown under Your states.

Dry run, then apply#

For each state under Your states, choose a node group, then:

• Dry run: shows, machine by machine, what would change, and changes nothing. Dry runs are never held by change windows.
• Apply: makes the changes, through your permissions, change windows, locks and approvals, with each machine's result in the audit log.

What a state may contain#

States are plain YAML: no templates ({{ }}, {% %}) and no other renderers.

While command execution is off on the server (the default for new installs), a state can manage files, packages, services, users and groups, hosts entries, time zone, sysctl, firewalld, SELinux, mounts and Windows roles and registry, but it cannot run commands. These are refused, with the reason:

• cmd and module states;
• the options onlyif, unless and check_cmd, which run shell commands;
• for files, source and template (put the text under contents instead).

This keeps "command execution is off" true for states as well. When root turns commands on (gardience automation commands on), states may use any state function, still as plain YAML.

Keep states in Git (GitOps)#

A Git project (Automation > Projects) can hold Salt states as well as playbooks. Open the project's Salt states from Git, set the folder that holds them (for example states), and save.

1. Put each state in that folder as NAME.sls (lowercase letters, digits, and _), plain YAML as above. Subfolders work too, up to three deep: web/nginx.sls is the state web_nginx. A local project works the same way, with its states folder set already.
2. Push. With the project's push webhook, Gardience syncs at once; otherwise choose Sync now.
3. Gardience checks every state with the same rules as one saved here, and Review changes shows what publishing would do: new, changed, and removed states, each with its diff, plus anything skipped and why.
4. An admin chooses Publish. Or turn on Publish by itself after each sync, so a merge to the branch is the approval. Either way each state is checked again before it is written, and the audit log records the commit.
5. Dry-run and apply as usual. Change windows, locks, approvals, and permissions all apply.

Applying a state is checked by what is in it, wherever it was saved (here or in Git). Applying one that cannot be undone needs a second person, as described in the security model. Schedules, join rules, and work held for offline machines never apply it: Gardience checks the state again at the moment it would run, because a push to Git can change it after the schedule was saved. A dry run never needs approval.

States that come from Git are changed in Git: editing or deleting one here is refused with the project's name. A Git state never replaces one saved here or by another project (that shows as a conflict to resolve by renaming), and a state that stops passing the checks stays as last published until it is fixed in Git.

Review changes also marks what a state would do when applied. A state that cannot be undone (it formats a disk, removes or stops the Salt agent, or deletes a whole drive) is marked in red; a risky but reversible one (it stops a firewall, deletes files, or downloads and runs a script) in yellow. Publishing does not run anything, so both can be published.

How states are stored#

The web service cannot write states itself. It hands each saved state to the config keeper, a separate container with no network access, which checks it again and writes it to srv/custom/NAME.sls. The Salt master and the web service can only read that folder. States are included in backups and kept across upgrades.

The audit log records each request (state.save_requested), each decision (state.published or state.refused) and every dry run and apply.

Related#

• Command center
• AI assistant
• Change windows and locks