vars

README

vars

Ansible variable precedence engine: facts, defaults, host/group vars, extra-vars.

Part of go-ansible — a pure-Go (CGO=0), functional-parity port of Ansible.

Usage

ctx := vars.New()
ctx.Set(vars.Inventory, hostVars)
ctx.SetVar(vars.TaskVars, "retries", 3)
ctx.SetVar(vars.ExtraVars, "env", "prod") // -e / --extra-vars — always wins

merged := ctx.Merged()          // low-to-high across all ten layers
val, ok := ctx.Get("env")       // "prod"
layer, ok := ctx.Which("env")   // vars.ExtraVars

Layers() lists the ladder in precedence order (RoleDefaults lowest through ExtraVars highest); Child() derives a scoped context (e.g. per-block/per-task) that inherits its parent's merged values without mutating them.

Documentation

Overview

Package vars implements Ansible's variable precedence: a fixed ladder of named layers (role defaults, inventory, facts, play/role/block/task vars, registered vars, role params, extra vars) merged low-to-high so that a value set in a higher layer always wins.

This does not itself know about roles, plays, or tasks — playbook assigns each layer's content as it walks the play; this package only owns the merge order.

Index

• func InjectFacts(facts map[string]any) map[string]any
• type Context
  • func New() *Context
  • func (c *Context) Child() *Context
  • func (c *Context) Get(key string) (any, bool)
  • func (c *Context) Layer(l Layer) map[string]any
  • func (c *Context) Merged() map[string]any
  • func (c *Context) Set(layer Layer, vals map[string]any)
  • func (c *Context) SetVar(layer Layer, key string, value any)
  • func (c *Context) Which(key string) (Layer, bool)
• type Layer
  • func Layers() []Layer
  • func (l Layer) String() string

Functions

func InjectFacts

func InjectFacts(facts map[string]any) map[string]any

InjectFacts returns facts both nested under "ansible_facts" (the canonical form) and flattened as top-level "ansible_<name>" aliases (e.g. ansible_facts["os_family"] also becomes "ansible_os_family"), matching Ansible's fact-injection behavior so both spellings resolve in templates.

Types

type Context

type Context struct {
	// contains filtered or unexported fields
}

Context holds one host/task's variable state across every precedence layer. The zero value is not usable — use New.

func New

func New() *Context

New returns an empty Context.

func (*Context) Child

func (c *Context) Child() *Context

Child returns a copy of c suitable for a nested scope (a block inside a play, a task inside a block, one iteration of a loop): mutating the child's TaskVars/BlockVars/Registered layers never affects the parent.

func (*Context) Get

func (c *Context) Get(key string) (any, bool)

Get looks up key in the fully merged view.

func (*Context) Layer

func (c *Context) Layer(l Layer) map[string]any

Layer returns a copy of one layer's variables — for a caller (like a role's temporary variable push) that needs to save a layer's current content before overwriting it, to restore afterward.

func (*Context) Merged

func (c *Context) Merged() map[string]any

Merged flattens every layer into one map, low precedence first so higher layers overwrite lower ones on key conflict.

func (*Context) Set

func (c *Context) Set(layer Layer, vals map[string]any)

Set replaces layer's whole variable map.

func (*Context) SetVar

func (c *Context) SetVar(layer Layer, key string, value any)

SetVar sets a single variable within layer.

func (*Context) Which

func (c *Context) Which(key string) (Layer, bool)

Which reports the highest-precedence layer that currently sets key, for diagnostics ("why did this variable win?").

type Layer

type Layer int

Layer names one rung of Ansible's variable precedence ladder, lowest first. This is a simplified but order-faithful subset of the ~22 levels documented for ansible-core: it keeps every distinction that changes real-world playbook behavior and collapses the rest (e.g. vars_prompt/vars_files fold into PlayVars — they all resolve to the same play-scoped map before a task runs).

const (
	RoleDefaults Layer = iota // role defaults/main.yml — the floor
	Inventory                 // merged inventory group_vars + host_vars
	Facts                     // gathered facts (ansible_facts.*) + flattened ansible_* aliases
	PlayVars                  // play vars:, vars_files:, vars_prompt:
	RoleVars                  // role vars/main.yml
	BlockVars                 // block-level vars:
	TaskVars                  // task-level vars:, loop item vars
	Registered                // register:, set_fact
	RoleParams                // role/include_role parameters
	ExtraVars                 // -e / --extra-vars — always wins

)

func Layers

func Layers() []Layer

Layers returns the layer set in ascending precedence order, for callers that want to render the whole ladder (e.g. `ansible -e` style debugging tools).

func (Layer) String

func (l Layer) String() string