Salt Resources reference#

New in version 3008.0.

Autodoc reference for the resource-framework modules and the resource types shipped in core Salt. For the user-facing guide see Salt Resources.

Resource types#

Framework#

The resource registry — the master-side index of which minion manages which resource:

Resource Registry — mmap-backed system of record for Salt Resources.

The registry is the master-side authority for which minions manage which resources. It powers the T@ and M@ targeting engines, the salt '*' wildcard augmentation, and any runner/API that needs to walk the set of resources a minion owns.

Architecture (Strategy 1 of mmap-compaction-design.md §"Secondaries"):

  • Primary index (by_id) is a MmapCache file on disk keyed by composite SRN ("type:id") with a small JSON payload ({"m": <minion_id>, "t": <resource_type>}). Reads and writes are O(1) linear-probing hash lookups; compaction uses sorted placement (pack_sorted) and completes in ~1 s for 1M entries.

  • Secondary indexes (by_type and by_minion) are derived views. They live in-process only and are (re)materialised on first access after the primary file is observed to have been atomically swapped (inode change). Each master worker carries its own derived snapshot.

  • Read consistency during compaction: master worker processes that handle _register_resources can all write (Salt's MWorker pool). Cross-process visibility is provided by two signals:

    • st_ino — changes on _ResourceIndexStore.compact()'s atomic os.replace. Triggers readers to close stale mmap handles.

    • st_mtime_ns — bumped by every put/delete via MmapCache._touch_mtime(). Triggers readers to rebuild derived views from the (updated in place) primary mmap.

    Together they form the content_version tuple watched by _ResourceIndexStore._current_version(). Readers with an open mmap keep pointing at the pre-swap inode until the next staleness check, so they never see a torn file.

Cache-bank layout (complementary to this on-disk mmap index) is documented in resources-registry-design.md and consists of three salt.cache banks (grains, pillar, resources) keyed by bare resource ID.

The resource_grains cache bank#

Independent of the on-disk mmap registry above, the master also maintains a resource_grains salt.cache bank (default driver: localfs) that backs grain-based targeting of resources (salt -G, salt -P, salt -C 'G@…').

Schema:

  • Bank name: "resource_grains".

  • Key: composite SRN of the form "<resource_type>:<resource_id>" — same shape produced by resource_index_srn_key() and used by the primary mmap index. Composite keying lets two resources share a bare id across types without colliding (e.g. "dummy:web-01" and "ssh:web-01" are distinct entries).

  • Value: the per-resource grain dict returned by resource_funcs[f"{type}.grains"]() on the managing minion — collected by salt.minion.Minion._collect_resource_grains() and shipped to the master as part of the _register_resources payload.

Lifecycle:

  • Write: master _register_resources handler stores entries on every registration (intra-process visibility immediate, cross-process via the filesystem-backed cache).

  • Flush: when a minion re-registers with a smaller resource set, SRNs that disappear from the payload are flushed only if the registry shows they're no longer owned by anyone. Multi-minion safe by design.

  • Match: salt.utils.minions.CkMinions._augment_grain_match_with_resource_grains() walks the bank for every grain/grain-pcre check and appends matched bare resource ids to the response wait set.

Freshness: the bank is refreshed only when the minion calls _register_resources_with_master. Triggers for that are minion start, the resource_refresh event, and saltutil.refresh_pillar. A per-resource <type>.grains_refresh() invocation does not auto-propagate to the master; the operator-level recipe is to fire resource_refresh on the minion event bus.

Operator runner:

Per-resource grains module: