ferroclass 0.12.0

Hierarchical inventory management tool (reclass compatible)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

SPDX-FileCopyrightText: 2026 Michael Jansen <ferroclass@michael-jansen.biz>
SPDX-License-Identifier: MPL-2.0

Installing Salt Adapter Modules
===============================

The adapter modules in this directory provide Salt ext_pillar and
master_tops integration with ferroclass. They are thin Python shims
that delegate to the native ferroclass extension module (PyO3).

Salt discovers its plugins by scanning its extension_modules directory,
NOT via Python package paths or entry_points. You must copy or symlink
the adapter files into Salt's extension_modules subdirectories. This
matches how the Python reclass salt-formulas fork distributes its
enhanced adapters.

Quick Install
-------------

1. Find your Salt extension_modules path:

       grep extension_modules /etc/salt/master

   If not configured, the default is:

       /var/cache/salt/master/extmods

2. Create the pillar and tops subdirectories if they don't exist:

       mkdir -p /var/cache/salt/master/extmods/pillar
       mkdir -p /var/cache/salt/master/extmods/tops

3. Copy or symlink the adapter files.

   From an RPM install (ferroclass-salt-adapter package):

       ln -s /usr/share/ferroclass/contrib/pillar/ferroclass_adapter.py \
             /var/cache/salt/master/extmods/pillar/
       ln -s /usr/share/ferroclass/contrib/tops/ferroclass_adapter.py \
             /var/cache/salt/master/extmods/tops/

   From a pip install, find the adapter files using Python:

       python3 -c "import ferroclass; print(ferroclass.__file__)"

   Then look for the contrib/ directory next to the extension module,
   or download the files from the ferroclass source tree on GitHub.

4. Restart the Salt master:

       systemctl restart salt-master

5. Configure ferroclass in /etc/salt/master:

        ferroclass: &ferroclass
          storage_type: yaml_fs
          inventory_base_uri: /srv/salt
          class_mappings:
            - "* default"
            - "/^www\\d+/ webserver"

       ext_pillar:
         - ferroclass: *ferroclass

       master_tops:
         ferroclass: *ferroclass

   Note the plugin name is "ferroclass" (not "reclass"). If you are
   migrating from the Python reclass adapter, update the Salt master
   config from "reclass:" to "ferroclass:".

Background
----------

Salt still ships built-in reclass_adapter.py files for both ext_pillar
and master_tops. These built-in adapters import "reclass.adapters.salt"
and call its ext_pillar() / top() functions. However, they do not
support the allow_adapter_env_override option (saltenv/pillarenv
override), which the salt-formulas/reclass fork added.

The ferroclass adapters are similar: they are thin shims that delegate
to "import ferroclass" and call its ext_pillar() / top() functions.
Because the module name is "ferroclass" (not "reclass"), they do not
conflict with Salt's built-in reclass adapters — both can coexist.