go-ansible

Module: forge.lthn.ai/core/go-ansible

Pure Go Ansible executor that parses and runs Ansible playbooks without requiring the Python ansible binary. Supports SSH-based remote execution, inventory parsing, Jinja2-like templating, module execution, roles, handlers, loops, blocks, and conditionals.

Architecture

File	Purpose
`types.go`	Data types: `Playbook`, `Play`, `Task`, `TaskResult`, `Inventory`, `Host`, `Facts`, `KnownModules`
`parser.go`	YAML parsing for playbooks, inventory, roles, and task files
`executor.go`	Playbook execution engine with SSH client management, templating, conditionals
`ssh.go`	`SSHClient` for remote command execution, file upload/download
`modules.go`	Ansible module implementations (shell, copy, template, file, service, etc.)

CLI registration in cmd/ansible/.

Key Types

Core Types

Executor — Runs playbooks: Run(), SetInventory(), SetVar(). Supports callbacks: OnPlayStart, OnTaskStart, OnTaskEnd, OnPlayEnd. Options: Limit, Tags, SkipTags, CheckMode, Diff, Verbose
Parser — Parses YAML: ParsePlaybook(), ParseInventory(), ParseRole(), ParseTasks()
SSHClient — SSH operations: Connect(), Run(), RunScript(), Upload(), Download(), FileExists(), Stat(), SetBecome()
SSHConfig — Connection config: Host, Port, User, Password, KeyFile, Become, BecomeUser, BecomePass, Timeout

Playbook Types

Play — Single play: Name, Hosts, Become, Vars, PreTasks, Tasks, PostTasks, Roles, Handlers
Task — Single task: Name, Module, Args, Register, When, Loop, LoopControl, Block, Rescue, Always, Notify, IncludeTasks, ImportTasks
TaskResult — Execution result: Changed, Failed, Skipped, Msg, Stdout, Stderr, RC, Results (for loops)
RoleRef — Role reference with vars and conditions

Inventory Types

Inventory — Top-level with All group
InventoryGroup — Hosts, Children, Vars
Host — Connection details: AnsibleHost, AnsiblePort, AnsibleUser, AnsibleSSHPrivateKeyFile
Facts — Gathered facts: Hostname, FQDN, OS, Distribution, Architecture, Kernel, Memory, CPUs

Usage

import "forge.lthn.ai/core/go-ansible"

executor := ansible.NewExecutor("/path/to/playbooks")
executor.SetInventory("inventory/hosts.yml")
executor.SetVar("deploy_version", "1.2.3")

executor.OnTaskStart = func(host string, task *ansible.Task) {
    fmt.Printf("[%s] %s\n", host, task.Name)
}

err := executor.Run(ctx, "deploy.yml")
defer executor.Close()

Dependencies

forge.lthn.ai/core/go-log — Structured logging and errors
golang.org/x/crypto/ssh — SSH client
golang.org/x/crypto/ssh/knownhosts — Host key verification
gopkg.in/yaml.v3 — YAML parsing