all: document the shared-value role trap

[ideaship]

What

Documentation only — all/README.md. No behaviour change, no variable touched.

Why

The 2026.1 mirror re-sync shipped two regressions of the same shape, and this
file did not describe that shape:

• kolla: gate openstack_auth below 2026.1 #307 — openstack_auth lost auth_url on every release below
  2026.1; keystone registration failed on four testbed lanes.
• kolla: gate designate_backend_external #309 — designate_backend_external went from "no" to
  false; bind9 stopped being configured below 2026.1.

Both are fixed. This records what they have in common, while it is concrete.

The gap being filled

all/ is one tree serving every supported release, but each release's roles
come from its own kolla-ansible image. So when upstream changes a value and
the code that reads it in the same commit, mirroring the value alone splits the
pair — the new value meets the old consumer.

The README already said the detector cannot catch "a value that must differ by
release". It did not say why, and it did not describe the variant that is
easy to miss:

	what changed	why the usual check misses it
openstack_auth	the value's meaning — 2026.1 reads the rest from a templated clouds.yaml older releases do not have	nothing; a cross-release value comparison would have caught it
designate_backend_external	the value's type, truth value preserved ("no" → false)	both are false under | bool, so every boolean-equivalence check calls it inert — but the older role compares against the string, and false == 'no' is False. (The bare string "no" is truthy; it is the filter that makes them agree.)

So the new text states the rule: a notation change is inert only if every
consumer coerces. Search the older releases' roles for a literal comparison
against the key, and evaluate it against both values rather than stopping at
the match. Of the three keys that matched in the 2026.1 sweep, only one
inverted.

Also documented

Two things that cost real time during the investigation:

• Resolving a variable by hand needs more than the command this file
  recommends. An ad-hoc ansible … -m debug -a "var=…" has no filter
  plugins, no vault and no site inputs. Each missing piece fails differently,
  and a missing secret prints VARIABLE IS NOT DEFINED! for a key that is
  defined — the opposite of the truth. The working invocation and the three
  failure modes are now written down.
• A resolved value proves delivery, not consumption.
  om_rabbitmq_qos_prefetch_count resolves on every release and is rendered
  into no config file at all, because the template that would emit it sits
  behind a guard OSISM turns off.

Plus a worked example for gating a non-scalar value (the openstack_auth
gate from #307), including the caveat that sync-mirror's --retain cannot
verify a mapping-valued gate today — it only parses quoted scalar literals, so
such a gate takes --retain-unverified.

Scope

Guidance, not an incident write-up. The two regressions appear as one clause
each with a PR reference; the forensics stay in the PRs. Deliberately not
covered here: where to read an effective deployed value on a live cluster —
that is diagnosis workflow rather than group_vars layering, and stating it
correctly needs more caveats than it earns in this file.

Drive-by

Where a variable goes named the supported range in a parenthetical, and it
was stale — it still said 2024.1–2025.2. Rather than update it to a value that
moves every release, the parenthetical is gone: the file already states that
the range is derived, not declared (check-drift.py globs
latest/openstack-*.yml in osism/release), so this now points there, the way
the openstack_release note two sections up points at 001-common.yml.

🤖 Generated with Claude Code