Data, Facts, and Templates

Three cooperating packages feed every run. facts gathers what is true about the host. hiera layers a hierarchy of data blocks into one resolved map, driven by those facts. templates renders that data into resource fields. The manager wires them together and hands the result to the apply engine.

Facts

facts.Gather (facts/facts.go:17) builds a map from the built-in families, host, network, partition, cpu, and memory, each backed by gopsutil and each skippable with a config flag. It then merges file-based facts on top: for the system config directory and then the user directory, it reads facts.json, facts.yaml, and a sorted facts.d/ directory, deep-merging each in order so later sources win.

Runtime caching lives in the manager, not the facts package. Facts() gathers once and memoizes; SystemFacts() always re-gathers with a 2-second default deadline; SetFacts and MergeFacts let callers override or overlay, which is how the agent reuses its last good facts when a gather fails.

Hiera

Resolve (hiera/resolver.go:98) starts from the data: block as the base, then walks hierarchy.order. Each level is a template like os:{{ lookup('facts.host.info.platformFamily') }}. A level counts as matched only when its embedded expression produces a non-empty value, so a level whose fact is missing is skipped. The matched string is looked up in overrides: and merged into the base.

merge: first

The default. The first matching level wins; its top-level keys replace the base, and resolution returns immediately.

merge: deep

Every matching level accumulates. Maps merge recursively and slices concatenate, in hierarchy order.

Sources

ResolveUrl dispatches by scheme: a local YAML or JSON file, an http(s) URL with basic auth, or a NATS JetStream KV document at kv://Bucket/Key.

Validation

YAML comments @require and @validate <expr> become rules. Resolution returns the rules so a multi-source caller validates once after merging.

Templates

{{ expr }} and ${ expr } are aliases. Both route through the same expr-lang evaluator, so ${ Data.package_name } and {{ Data.package_name }} are identical. A separate jet(...) renderer handles Jet templates with [[ ]] delimiters, used mainly to generate resource lists.

Field access

Inside an expression, use Go field names: Data.app_name, Facts.os, Environ.X.

lookup(key, default)

Takes a lowercased, dotted path rooted at the environment: lookup('data.nested.key'), lookup('facts.env'). It marshals the environment to JSON and queries it with gjson.

Type preservation

When the whole string is a single expression, its native typed value is returned, so a templated port stays an integer. Mixed strings are stringified and concatenated.

Deferred fields

Struct fields tagged template:"deferred", such as file content, render in a second pass after the control gate, so an unless can protect a resource from a template error.

One syntax is reserved but not implemented. The Resolve doc comment and a test reference Puppet-style env:%{env} placeholders, but only {{ }} and ${ } are recognized. A %{...} entry is treated as a literal key with no matched expression, so it is skipped. Real hierarchies use env:{{ lookup('facts.env') }}.