From f20b157e80671e7354378d90272c1e2bb6a39d13 Mon Sep 17 00:00:00 2001 From: Twangboy Date: Fri, 10 Jul 2026 13:03:08 -0600 Subject: [PATCH] Warn about refreshing grains after upgrading master to 3008.x Salt 3008.0 restructured the master's minion data cache, splitting grains into a dedicated cache bank instead of a combined per-minion blob. Cached data from a pre-3008 master isn't migrated, so grain targeting (-G), mine.get, and cached pillar/grains lookups can return stale or empty results until minions re-sync. Add a warning to the general upgrade procedure telling admins to run saltutil.refresh_grains on minions after upgrading a 3006.x/3007.x master to 3008.x. --- docs/topics/upgrade.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/topics/upgrade.rst b/docs/topics/upgrade.rst index 3494d5b..087c76e 100644 --- a/docs/topics/upgrade.rst +++ b/docs/topics/upgrade.rst @@ -119,6 +119,18 @@ To upgrade Salt: #. With Salt now updated, verify your configuration is correct and restore it if necessary. + .. Warning:: + If you are upgrading a Salt master from 3006.x or 3007.x to 3008.x, + Salt 3008.0 restructured the master's minion data cache so that + grains are stored in a dedicated cache bank instead of a combined + per-minion blob. Cached grains data from a pre-3008 master is not + automatically migrated, which can cause grain-based targeting + (``-G``), ``mine.get``, and cached pillar/grains lookups to return + stale or empty results on the master. After upgrading the master, + run ``salt '*' saltutil.refresh_grains`` on minions (or wait for + their next scheduled pillar/highstate refresh) to repopulate the + master's grains cache. + If you stopped the daemon(s) prior to upgrading, you will need to restart the daemons. See `Restart and upgrade minions used in state runs`_ for more information.