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.

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

• type Group
• type Host
• type Inventory
  • func Load(path string) (*Inventory, error)
  • func New() *Inventory
  • func ParseINI(data []byte) (*Inventory, error)
  • func ParseYAML(data []byte) (*Inventory, error)
  • 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)

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 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) 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.