inventory

README

inventory

Ansible-compatible inventory: INI/YAML parsers, groups, host/group vars, patterns.

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

Usage

inv, err := inventory.Load("inventory.ini") // INI or YAML, group_vars/host_vars included

hosts, err := inv.Match("webservers:&staging:!maintenance") // Ansible host-pattern syntax
vars := inv.HostVars("web1.example.com")                    // group + host var precedence applied
groups := inv.GroupsForHost("web1.example.com")              // full ancestry, not just direct membership

Merge combines a second *Inventory (e.g. a dynamic-inventory result) into an existing one.

Documentation

Overview

Package inventory parses Ansible-compatible inventories (YAML and INI), builds the group/host graph including group_vars/host_vars directories, and matches Ansible host patterns against it.

Index

• func IsScript(mode os.FileMode) bool
• type Group
• type Host
• type Inventory
  • func Load(path string) (*Inventory, error)
  • func New() *Inventory
  • func ParseINI(data []byte) (*Inventory, error)
  • func ParseScript(path string) (*Inventory, error)
  • func ParseYAML(data []byte) (*Inventory, error)
  • func (inv *Inventory) AddHost(name string, vals map[string]any, groups ...string)
  • func (inv *Inventory) AddToGroup(hostName, groupName string)
  • func (inv *Inventory) GroupsForHost(hostName string) []*Group
  • func (inv *Inventory) HostVars(hostName string) map[string]any
  • func (inv *Inventory) Match(pattern string) ([]*Host, error)
  • func (inv *Inventory) Merge(other *Inventory)

Functions

func IsScript

func IsScript(mode os.FileMode) bool

IsScript reports whether a file with this mode should be treated as a dynamic inventory script rather than a static INI/YAML file — real Ansible's own detection: any executable bit set on the file (not a directory), regardless of extension.

Types

type Group

type Group struct {
	Name     string
	Hosts    map[string]*Host
	Children map[string]*Group
	Parents  map[string]*Group
	Vars     map[string]any
}

Group is a named collection of hosts and/or child groups, plus the variables attached to the group itself.

type Host

type Host struct {
	Name string
	Vars map[string]any
}

Host is one managed node: its name (as given in the inventory) plus the variables attached to it directly (not counting group-inherited vars — see Inventory.HostVars for the merged view).

type Inventory

type Inventory struct {
	Hosts  map[string]*Host
	Groups map[string]*Group
}

Inventory is the full host/group graph for one inventory source (a single file, or a directory merging several — see Load).

func Load

func Load(path string) (*Inventory, error)

Load reads an inventory from path, which may be:

• a single YAML file (.yml/.yaml)
• a single INI file (any other extension, or none)
• a directory, in which every regular file directly inside it (except group_vars/ and host_vars/) is parsed and merged, in name order

group_vars/<name>.yml, group_vars/<name>/*.yml, host_vars/<name>.yml and host_vars/<name>/*.yml siblings of the source are then merged in, group vars before host vars, per Ansible's precedence.

func New

func New() *Inventory

New returns an empty inventory pre-seeded with the two groups every Ansible inventory implicitly has: "all" (every host) and "ungrouped" (hosts in no other group).

func ParseINI

func ParseINI(data []byte) (*Inventory, error)

ParseINI parses an Ansible INI-style inventory:

host1 ansible_host=192.0.2.1

[webservers]
web[01:02].example.com http_port=80

[webservers:vars]
ansible_user=deploy

[webservers:children]
edge

func ParseScript

func ParseScript(path string) (*Inventory, error)

ParseScript runs the dynamic inventory script at path — real Ansible's inventory-script contract: `path --list` prints one JSON document to stdout describing every group (either the shorthand `["host1","host2"]` array form or the full `{"hosts":[...], "vars":{...},"children":[...]}` form) plus an optional top-level "_meta" key holding `{"hostvars": {"host1": {...}, ...}}`.

func ParseYAML

func ParseYAML(data []byte) (*Inventory, error)

ParseYAML parses an Ansible YAML inventory (the format produced by `ansible-inventory --list` / documented as "YAML inventory"):

all:
  hosts:
    host1: {}
  vars:
    v: 1
  children:
    group1:
      hosts:
        host2:
          v: 2

func (*Inventory) AddHost

func (inv *Inventory) AddHost(name string, vals map[string]any, groups ...string)

AddHost adds a host to the inventory at runtime — Ansible's add_host module — with the given variables, as a member of every named group (created if new). With no groups it is still reachable by the "all" pattern (matchTerm's "all"/"*" case iterates every known host directly) even though it joins no group's direct membership. Hosts already matched by an in-progress play are unaffected; only plays matched after this call see the addition, matching real Ansible.

func (*Inventory) AddToGroup

func (inv *Inventory) AddToGroup(hostName, groupName string)

AddToGroup records an existing (or new) host as a member of group, creating the group if it doesn't exist — Ansible's group_by module.

func (*Inventory) GroupsForHost

func (inv *Inventory) GroupsForHost(hostName string) []*Group

GroupsForHost returns every group host belongs to (directly or via a parent group), "all" first, deepest/most-specific last — the order group vars are merged in.

func (*Inventory) HostVars

func (inv *Inventory) HostVars(hostName string) map[string]any

HostVars returns the fully merged variables for hostName: group vars (from "all" down through parent groups to the most specific group, alphabetically among siblings) followed by the host's own vars, which win on conflict — matching Ansible's group-before-host precedence.

func (*Inventory) Match

func (inv *Inventory) Match(pattern string) ([]*Host, error)

Match resolves an Ansible host pattern ("all", a group name, a glob, a numeric/alpha range, or a colon/comma-separated combination with `!` exclusion and `&` intersection, e.g. "webservers:!web3:&datacenter1") against the inventory, and returns the matching hosts sorted by name.

func (*Inventory) Merge

func (inv *Inventory) Merge(other *Inventory)

Merge folds other into inv (later sources override earlier ones on scalar var conflicts, group/host membership is unioned) — how Ansible combines multiple inventory sources.