What Are Grains?
Grains are facts about a minion: operating system, CPU, memory, IP addresses, virtualisation, and more. The minion collects them when it starts and keeps them. You use grains to target minions and to make states adapt (for example, 'if Debian, install apache2').
Core Grains You Will Use
| Grain | Example |
|---|---|
id, host, fqdn, domain | web1, web1.example.com |
os, os_family, osrelease, osmajorrelease, oscodename | Ubuntu, Debian, 24.04, 24, noble |
kernel, kernelrelease, cpuarch | Linux, 6.8.0, x86_64 |
num_cpus, cpu_model, mem_total | 4, Intel..., 7954 (MB) |
ipv4, ipv6, ip4_interfaces, fqdn_ip4, hwaddr_interfaces | Lists and dictionaries of addresses |
virtual, virtual_subtype | kvm, physical, container |
init, pythonversion, saltversion | systemd, [3, 11, ...], 3008.2 |
selinux, shell, path | Settings |
master, server_id, productname, biosversion | Hardware and Salt information |
osfinger | Ubuntu-24.04, a unique OS string, great for matching |
ec2, gce, azure (when present) | Cloud metadata grains |
Targeting with Grains
Custom Grains: Three Ways
| Method | Where | Good for |
|---|---|---|
| Static, in the minion config | /etc/salt/minion.d/grains.conf | Roles and labels set by an admin |
| Static, in the grains file | /etc/salt/grains | Values set with grains.setval |
| Dynamic, in Python | _grains/ folder on the master | Facts you must compute (installed app version, rack location) |
1. Static Grains in the Minion Config
2. grains.setval / grains.append (The /etc/salt/grains File)
grains.setval writes to /etc/salt/grains on the minion, and the value survives restarts. Values written in the minion config are re-created from config at each start. Use one place per grain, to avoid confusion.
Grains from a State
3. Dynamic Python Grains
Put a Python file in /srv/salt/_grains/ on the master. Each function that returns a dictionary adds grains. Sync them to minions with saltutil.sync_grains (also done during state.apply and saltutil.sync_all).
Using Grains in States
Grains in the Top File: Role Assignment
A common design: a machine gets its role grain at build time (cloud-init, Terraform or a bootstrap script). The top file then maps roles to states. No hostnames in the top file.
Grains vs Pillar: Which One?
| Grains | Pillar | |
|---|---|---|
| Defined on | The minion | The master |
| Who controls the value | The minion (or the machine's admin) | The master admin |
| Trust level | Lower. A compromised minion can change its own grains | Higher. Minions cannot change pillar |
| Good for | Facts, roles for convenience, targeting | Secrets, settings, per-environment data |
| Visible to other minions | Master has them cached | Only the minion it was assigned to |
roles grain to database, it could ask for database secrets. Use grains for convenience and pillar (assigned on the master) for anything sensitive. A safer way is to assign pillar by minion id.
Grains Cache and Refresh
| Action | Command |
|---|---|
| Recompute grains now | salt '*' saltutil.refresh_grains |
| Sync custom grain files | salt '*' saltutil.sync_grains |
| Sync all custom modules | salt '*' saltutil.sync_all |
| Grains cached on the master | salt-run cache.grains tgt='*' |
| Slow grains | Disable some in the minion config: enable_fqdns_grains: False, enable_gpu_grains: False |
| Grain file | /etc/salt/grains and /var/cache/salt/minion/ |
Practice Tasks
- Set
roles: [web]andenv: devusing the minion config, restart, and read them withgrains.get - Use
grains.setvalto setdatacenterand check/etc/salt/grains - Write a Python grain that reports the contents of
/etc/app_version, sync it and target with-G - Create a role-based top file with
roles:webserverand test withstate.show_top - Explain why a grain is a poor place for a database password
Conclusion
Grains are facts about minions. Use core grains for OS and hardware logic, static grains for roles and labels, and Python grains for computed facts. Use grains for targeting and convenience, but never for secrets or security decisions.

