aini

README

aini

Go library for Parsing Ansible inventory files.
We are trying to follow the logic of Ansible parser as close as possible.

Documentation on ansible inventory files can be found here:
https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html

Supported features:

• Variables
• Host patterns
• Nested groups
• Load variables from group_vars and host_vars

Public API

package aini // import "github.com/relex/aini"


FUNCTIONS

func MatchGroups(groups map[string]*Group, pattern string) (map[string]*Group, error)
    MatchGroups looks for groups that match the pattern

func MatchHosts(hosts map[string]*Host, pattern string) (map[string]*Host, error)
    MatchHosts looks for hosts that match the pattern

func MatchVars(vars map[string]string, pattern string) (map[string]string, error)
    MatchVars looks for vars that match the pattern


TYPES

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

        // Has unexported fields.
}
    Group represents ansible group

func GroupMapListValues(mymap map[string]*Group) []*Group
    GroupMapListValues transforms map of Groups into Group list in lexical order

func (group *Group) MatchHosts(pattern string) (map[string]*Host, error)
    MatchHosts looks for hosts that match the pattern

func (group *Group) MatchVars(pattern string) (map[string]string, error)
    MatchVars looks for vars that match the pattern

func (group Group) String() string

type Host struct {
        Name   string
        Port   int
        Vars   map[string]string
        Groups map[string]*Group

        // Has unexported fields.
}
    Host represents ansible host

func HostMapListValues(mymap map[string]*Host) []*Host
    HostMapListValues transforms map of Hosts into Host list in lexical order

func (host *Host) MatchGroups(pattern string) (map[string]*Group, error)
    MatchGroups looks for groups that match the pattern

func (host *Host) MatchVars(pattern string) (map[string]string, error)
    MatchVars looks for vars that match the pattern

func (host Host) String() string

type InventoryData struct {
        Groups map[string]*Group
        Hosts  map[string]*Host
}
    InventoryData contains parsed inventory representation Note: Groups and
    Hosts fields contain all the groups and hosts, not only top-level

func Parse(r io.Reader) (*InventoryData, error)
    Parse using some Reader

func ParseFile(f string) (*InventoryData, error)
    ParseFile parses Inventory represented as a file

func ParseString(input string) (*InventoryData, error)
    ParseString parses Inventory represented as a string

func (inventory *InventoryData) AddVars(path string) error
    AddVars take a path that contains group_vars and host_vars directories and
    adds these variables to the InventoryData

func (inventory *InventoryData) AddVarsLowerCased(path string) error
    AddVarsLowerCased does the same as AddVars, but converts hostnames and
    groups name to lowercase. Use this function if you've executed
    `inventory.HostsToLower` or `inventory.GroupsToLower`

func (inventory *InventoryData) GroupsToLower()
    GroupsToLower transforms all group names to lowercase

func (inventory *InventoryData) HostsToLower()
    HostsToLower transforms all host names to lowercase

func (inventory *InventoryData) Match(pattern string) []*Host
    Match looks for hosts that match the pattern Deprecated: Use `MatchHosts`,
    which does proper error handling

func (inventory *InventoryData) MatchGroups(pattern string) (map[string]*Group, error)
    MatchGroups looks for groups that match the pattern

func (inventory *InventoryData) MatchHosts(pattern string) (map[string]*Host, error)
    MatchHosts looks for hosts that match the pattern

func (inventory *InventoryData) Reconcile()
    Reconcile ensures inventory basic rules, run after updates. After initial
    inventory file processing, only direct relationships are set.

    This method:

        * (re)sets Children and Parents for hosts and groups
        * ensures that mandatory groups exist
        * calculates variables for hosts and groups

Usage example

import (
    "strings"
    
    "github.com/relex/aini"
)

func main() {
    // Load from string example
    inventoryReader := strings.NewReader(`
	host1:2221
	[web]
	host2 ansible_ssh_user=root
    `)
    var inventory InventoryData = aini.Parse(inventoryReader)

    // Querying hosts
    _ = inventory.Hosts["host1"].Name == "host1"  // true
    _ = inventory.Hosts["host1"].Port == 2221     // true
    _ = inventory.Hosts["host2"].Name == "host2"] // true
    _ = inventory.Hosts["host2"].Post == 22]      // true
    
    _ = len(inventory.Hosts["host1"].Groups) == 2 // all, ungrouped
    _ = len(inventory.Hosts["host2"].Groups) == 2 // all, web
    
    _ = len(inventory.Match("host*")) == 2        // host1, host2

    _ = // Querying groups
    _ = inventory.Groups["web"].Hosts[0].Name == "host2" // true
    _ = len(inventory.Groups["all"].Hosts) == 2          // true
}

Documentation

Index

• func MatchGroups(groups map[string]*Group, pattern string) (map[string]*Group, error)
• func MatchHosts(hosts map[string]*Host, pattern string) (map[string]*Host, error)
• func MatchVars(vars map[string]string, pattern string) (map[string]string, error)
• type Group
  • func GroupMapListValues(mymap map[string]*Group) []*Group
  • func (group *Group) ListParentGroupsOrdered() []*Group
  • func (group *Group) MarshalJSON() ([]byte, error)
  • func (group *Group) MatchGroupsOrdered(pattern string) ([]*Group, error)
  • func (group *Group) MatchHosts(pattern string) (map[string]*Host, error)
  • func (group *Group) MatchVars(pattern string) (map[string]string, error)
  • func (group Group) String() string
• type Host
  • func HostMapListValues(mymap map[string]*Host) []*Host
  • func (host *Host) ListGroupsOrdered() []*Group
  • func (host *Host) MarshalJSON() ([]byte, error)
  • func (host *Host) MatchGroups(pattern string) (map[string]*Group, error)
  • func (host *Host) MatchGroupsOrdered(pattern string) ([]*Group, error)
  • func (host *Host) MatchVars(pattern string) (map[string]string, error)
  • func (host Host) String() string
• type InventoryData
  • func Parse(r io.Reader) (*InventoryData, error)
  • func ParseFile(f string) (*InventoryData, error)
  • func ParseString(input string) (*InventoryData, error)
  • func (inventory *InventoryData) AddVars(path string) error
  • func (inventory *InventoryData) AddVarsLowerCased(path string) error
  • func (inventory *InventoryData) GroupsToLower()
  • func (inventory *InventoryData) HostsToLower()
  • func (inventory *InventoryData) Match(pattern string) []*Host
  • func (inventory *InventoryData) MatchGroups(pattern string) (map[string]*Group, error)
  • func (inventory *InventoryData) MatchHosts(pattern string) (map[string]*Host, error)
  • func (inventory *InventoryData) Reconcile()
  • func (inventory *InventoryData) UnmarshalJSON(data []byte) error

Functions

func MatchGroups

func MatchGroups(groups map[string]*Group, pattern string) (map[string]*Group, error)

MatchGroups looks for groups that match the pattern

func MatchHosts

func MatchHosts(hosts map[string]*Host, pattern string) (map[string]*Host, error)

MatchHosts looks for hosts that match the pattern

func MatchVars

func MatchVars(vars map[string]string, pattern string) (map[string]string, error)

MatchVars looks for vars that match the pattern

Types

type Group

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

	DirectParents map[string]*Group
	// Vars set in inventory
	InventoryVars map[string]string
	// Vars set in group_vars
	FileVars map[string]string
	// Projection of all parent inventory variables
	AllInventoryVars map[string]string
	// Projection of all parent group_vars variables
	AllFileVars map[string]string
}

Group represents ansible group

func GroupMapListValues

func GroupMapListValues(mymap map[string]*Group) []*Group

GroupMapListValues transforms map of Groups into Group list in lexical order

func (*Group) ListParentGroupsOrdered

func (group *Group) ListParentGroupsOrdered() []*Group

ListParentGroupsOrdered returns all ancestor groups of a given group in level order

func (*Group) MarshalJSON

func (group *Group) MarshalJSON() ([]byte, error)

func (*Group) MatchGroupsOrdered

func (group *Group) MatchGroupsOrdered(pattern string) ([]*Group, error)

MatchGroupsOrdered looks for groups that match the pattern The result is a sorted array, where lower indexes corespond to more specific groups

func (*Group) MatchHosts

func (group *Group) MatchHosts(pattern string) (map[string]*Host, error)

MatchHosts looks for hosts that match the pattern

func (*Group) MatchVars

func (group *Group) MatchVars(pattern string) (map[string]string, error)

MatchVars looks for vars that match the pattern

func (Group) String

func (group Group) String() string

type Host

type Host struct {
	Name   string
	Port   int
	Vars   map[string]string
	Groups map[string]*Group

	DirectGroups map[string]*Group
	// Vars set in inventory
	InventoryVars map[string]string
	// Vars set in host_vars
	FileVars map[string]string
}

Host represents ansible host

func HostMapListValues

func HostMapListValues(mymap map[string]*Host) []*Host

HostMapListValues transforms map of Hosts into Host list in lexical order

func (*Host) ListGroupsOrdered

func (host *Host) ListGroupsOrdered() []*Group

ListGroupsOrdered returns all ancestor groups of a given host in level order

func (*Host) MarshalJSON

func (host *Host) MarshalJSON() ([]byte, error)

func (*Host) MatchGroups

func (host *Host) MatchGroups(pattern string) (map[string]*Group, error)

MatchGroups looks for groups that match the pattern

func (*Host) MatchGroupsOrdered

func (host *Host) MatchGroupsOrdered(pattern string) ([]*Group, error)

MatchGroupsOrdered looks for groups that match the pattern The result is a sorted array, where lower indexes corespond to more specific groups

func (*Host) MatchVars

func (host *Host) MatchVars(pattern string) (map[string]string, error)

MatchVars looks for vars that match the pattern

func (Host) String

func (host Host) String() string

type InventoryData

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

InventoryData contains parsed inventory representation Note: Groups and Hosts fields contain all the groups and hosts, not only top-level

func Parse

func Parse(r io.Reader) (*InventoryData, error)

Parse using some Reader

func ParseFile

func ParseFile(f string) (*InventoryData, error)

ParseFile parses Inventory represented as a file

func ParseString

func ParseString(input string) (*InventoryData, error)

ParseString parses Inventory represented as a string

func (*InventoryData) AddVars

func (inventory *InventoryData) AddVars(path string) error

AddVars take a path that contains group_vars and host_vars directories and adds these variables to the InventoryData

func (*InventoryData) AddVarsLowerCased

func (inventory *InventoryData) AddVarsLowerCased(path string) error

AddVarsLowerCased does the same as AddVars, but converts hostnames and groups name to lowercase. Use this function if you've executed `inventory.HostsToLower` or `inventory.GroupsToLower`

func (*InventoryData) GroupsToLower

func (inventory *InventoryData) GroupsToLower()

GroupsToLower transforms all group names to lowercase

func (*InventoryData) HostsToLower

func (inventory *InventoryData) HostsToLower()

HostsToLower transforms all host names to lowercase

func (*InventoryData) Match

func (inventory *InventoryData) Match(pattern string) []*Host

Match looks for hosts that match the pattern Deprecated: Use `MatchHosts`, which does proper error handling

func (*InventoryData) MatchGroups

func (inventory *InventoryData) MatchGroups(pattern string) (map[string]*Group, error)

MatchGroups looks for groups that match the pattern

func (*InventoryData) MatchHosts

func (inventory *InventoryData) MatchHosts(pattern string) (map[string]*Host, error)

MatchHosts looks for hosts that match the pattern

func (*InventoryData) Reconcile

func (inventory *InventoryData) Reconcile()

Reconcile ensures inventory basic rules, run after updates. After initial inventory file processing, only direct relationships are set.

This method:

• (re)sets Children and Parents for hosts and groups
• ensures that mandatory groups exist
• calculates variables for hosts and groups

func (*InventoryData) UnmarshalJSON

func (inventory *InventoryData) UnmarshalJSON(data []byte) error