Summary
No page explains what a legacy fact is or how it differs from a structured fact, even though that difference is the largest single cause of trouble in a 7 to 8 upgrade. The page that should explain it, "Facts and built-in variables" (lang_facts_and_builtin_vars), is a Puppet 5.5 import that presents classic $fact_name access and the $facts hash as two equal styles and uses $osfamily as its example, with "Works in all versions of Puppet" listed as the benefit. On OpenVox 8 that example fails compilation with Unknown variable: 'osfamily'.
The word "legacy" doesn't appear on the page, and "structured" appears only in passing, so a reader searching for the concept doesn't find it.
Current coverage
| Page |
What it has |
Gap |
openvox/8.x/lang_facts_and_builtin_vars.markdown (same file in 9.x) |
"Classic $fact_name facts" and "The $facts['fact_name'] hash" sections |
Recommends the form that breaks on 8, never mentions legacy facts |
Generated openfact/latest/core_facts.html |
A "Legacy Facts Note" callout and separate "Modern Facts" and "Legacy Facts" sections |
A reference list. Says legacy facts are hidden from facter output, not that OpenVox 8 agents stop sending them |
openfact/5.x/fact_overview.md |
"Writing structured facts" |
For fact authors; about hash and array return values, not the legacy set |
openvox/8.x/upgrade_major.md (#498) |
A table of how each legacy fact reference behaves on 8, the settings, and the tooling |
Framed as an upgrade step, not as the explanation of the concept |
Proposed change
Update lang_facts_and_builtin_vars in place (no redirects exist, so no split or rename), in both the 8.x and 9.x copies, which are identical today:
- Rework "Accessing facts from Puppet code" around the two kinds of fact rather than the two syntaxes. A legacy fact is a flat, top-level name such as
osfamily or ipaddress_eth0 that duplicates a value inside a structured fact such as os.family or networking.interfaces.eth0.ip. OpenFact still computes legacy facts, but OpenVox 8 agents don't send them to the server by default (include_legacy_facts), so $osfamily, $::osfamily, and $facts['osfamily'] no longer work in manifests.
- Replace the
$osfamily example with $facts['os']['family'], and delete "Works in all versions of Puppet".
- Keep the
$::fact_name history note, but frame it as history: top-scope access still works for real variables, and for structured facts the $facts hash is the form to use.
- Link out: the legacy section of the core facts reference for the list,
include_legacy_facts in the configuration reference, and "Legacy facts are no longer sent" on the upgrade page for what happens to each reference form and how to find them.
Not in scope: the rest of the page (trusted facts, $server_facts, agent and server variables) and the "master" wording, which #409 covers.
Verified behavior to draw on
Everything the new section states was run on openvox-agent 8.29.0 for #497 and is written up in #498: $::osfamily and $osfamily fail compilation; $facts['osfamily'] is silently undef; a 7 agent still sends legacy facts to an 8 server; include_legacy_facts = true on the agent restores them.
Part of #409.
Summary
No page explains what a legacy fact is or how it differs from a structured fact, even though that difference is the largest single cause of trouble in a 7 to 8 upgrade. The page that should explain it, "Facts and built-in variables" (
lang_facts_and_builtin_vars), is a Puppet 5.5 import that presents classic$fact_nameaccess and the$factshash as two equal styles and uses$osfamilyas its example, with "Works in all versions of Puppet" listed as the benefit. On OpenVox 8 that example fails compilation withUnknown variable: 'osfamily'.The word "legacy" doesn't appear on the page, and "structured" appears only in passing, so a reader searching for the concept doesn't find it.
Current coverage
openvox/8.x/lang_facts_and_builtin_vars.markdown(same file in 9.x)$fact_namefacts" and "The$facts['fact_name']hash" sectionsopenfact/latest/core_facts.htmlfacteroutput, not that OpenVox 8 agents stop sending themopenfact/5.x/fact_overview.mdopenvox/8.x/upgrade_major.md(#498)Proposed change
Update
lang_facts_and_builtin_varsin place (no redirects exist, so no split or rename), in both the 8.x and 9.x copies, which are identical today:osfamilyoripaddress_eth0that duplicates a value inside a structured fact such asos.familyornetworking.interfaces.eth0.ip. OpenFact still computes legacy facts, but OpenVox 8 agents don't send them to the server by default (include_legacy_facts), so$osfamily,$::osfamily, and$facts['osfamily']no longer work in manifests.$osfamilyexample with$facts['os']['family'], and delete "Works in all versions of Puppet".$::fact_namehistory note, but frame it as history: top-scope access still works for real variables, and for structured facts the$factshash is the form to use.include_legacy_factsin the configuration reference, and "Legacy facts are no longer sent" on the upgrade page for what happens to each reference form and how to find them.Not in scope: the rest of the page (trusted facts,
$server_facts, agent and server variables) and the "master" wording, which #409 covers.Verified behavior to draw on
Everything the new section states was run on openvox-agent 8.29.0 for #497 and is written up in #498:
$::osfamilyand$osfamilyfail compilation;$facts['osfamily']is silentlyundef; a 7 agent still sends legacy facts to an 8 server;include_legacy_facts = trueon the agent restores them.Part of #409.