iago

README

Iago

Iago (Infrastructure As GO) is an experimental software deployment framework. Iago scripts are written in Go. This means that Iago scripts can be compiled into a simple binary with no dependencies.

Basic API

Iago executes tasks on groups of hosts. Tasks describe actions to be performed to each individual host, and how to handle errors.

  // var g iago.Group; this is a set of iago.Host instances that the task will be applied to.
  g.Run(iago.Task{
    Name: "Example Task",
    // Here we specify the iago.Func action, which is an action that executes the function that we give it.
    // The function is executed concurrently for each host in the group.
    Action: iago.Func(func(ctx context.Context, host iago.Host) error {
      log.Println(host.Name())
      return nil
    }),
    // The OnError handler decides how any errors returned by the actions should be handled.
    // Any errors are automatically wrapped in a iago.TaskError before they are given to the handler.
    OnError: iago.Panic,
  })

We currently support connecting to remote hosts via SSH, but support for other connection methods can be added by implementing the iago.Host interface.

Example

The following example downloads a file from each remote host. This example uses the iagotest package, which spawns docker containers and connects to them with SSH for testing. The iago.DialSSH or iago.NewSSHGroup can be used to connect to existing SSH servers.

func TestIago(t *testing.T) {
  dir, _ := os.Getwd()

  // The iagotest package provides a helper function that automatically
  // builds and starts docker containers with an exposed SSH port for testing.
  g := iagotest.CreateSSHGroup(t, 4)

  g.Run(iago.Task{
    Name: "Download files",
    Action: iago.Download{
      Src:  iago.P("/etc/os-release"),
      Dest: iago.P("os").RelativeTo(dir),
      Mode: 0644,
    },
    OnError: iago.Panic,
  })
}

TODO

• Improve the reading of ssh_config files
  • Should support reading the public key files (it doesn't look like the ssher package supports this fully)
• Prompt the user when verifying host keys?
• Improve logging
  • Logging for tasks as they are running
  • Progress -- how many hosts have finished a task

Documentation

Index

• Variables
• func CleanPath(path string) string
• func Expand(h Host, s string) string
• func GetIntVar(host Host, key string) int
• func GetStringVar(host Host, key string) string
• func Ignore(e error)
• func Panic(e error)
• type CmdRunner
• type Download
  • func (d Download) Apply(ctx context.Context, host Host) error
• type ErrorHandler
• type Group
  • func NewGroup(hosts []Host) Group
  • func NewSSHGroup(hostNames []string, sshConfigPath string) (g Group, err error)
  • func (g Group) Close() (err error)
  • func (g Group) Run(name string, f func(ctx context.Context, host Host) error)
• type Host
  • func DialSSH(name, addr string, cfg *ssh.ClientConfig) (Host, error)
• type Path
  • func NewPath(prefix, path string) (p Path, err error)
  • func NewPathFromAbs(path string) (p Path, err error)
  • func (p Path) String() string
• type Perm
  • func NewPerm(perm fs.FileMode) Perm
  • func (p Perm) GetDirPerm() fs.FileMode
  • func (p Perm) GetFilePerm() fs.FileMode
  • func (p *Perm) WithDirPerm(dirPerm fs.FileMode) Perm
• type Shell
  • func (sa Shell) Apply(ctx context.Context, host Host) (err error)
• type TaskError
  • func (err TaskError) Error() string
  • func (err TaskError) Unwrap() error
• type Upload
  • func (u Upload) Apply(ctx context.Context, host Host) error

Variables

var (
	// ErrNotAbsolute is returned when a path is relative, but was expected to be absolute.
	ErrNotAbsolute = errors.New("not an absolute path")
	// ErrNotRelative is returned when a path is absolute, but was expected to be relative.
	ErrNotRelative = errors.New("not a relative path")
)

var DefaultTimeout = 30 * time.Second

DefaultTimeout is the default timeout for an action.

Functions

func CleanPath

func CleanPath(path string) string

CleanPath cleans the path and converts it to slashes.

func Expand

func Expand(h Host, s string) string

Expand expands any environment variables in the string 's' using the environment of the host 'h'.

func GetIntVar

func GetIntVar(host Host, key string) int

GetIntVar gets an integer variable from the host.

func GetStringVar

func GetStringVar(host Host, key string) string

GetStringVar gets a string variable from the host.

func Ignore

func Ignore(e error)

Ignore ignores errors.

func Panic

func Panic(e error)

Panic handles errors by panicking.

Types

type CmdRunner

type CmdRunner interface {
	Run(cmd string) error
	RunContext(ctx context.Context, cmd string) error
	Start(cmd string) error
	Wait() error

	StdinPipe() (io.WriteCloser, error)
	StdoutPipe() (io.ReadCloser, error)
	StderrPipe() (io.ReadCloser, error)
}

CmdRunner defines an interface for running commands on remote hosts. This interface is based on the "exec.Cmd" struct.

type Download

type Download struct {
	Src  Path
	Dest Path
	Perm Perm
}

Download downloads a file or directory from a remote host.

func (Download) Apply

func (d Download) Apply(ctx context.Context, host Host) error

Apply performs the download.

type ErrorHandler

type ErrorHandler func(error)

ErrorHandler is a function that handles errors from actions.

type Group

type Group struct {
	Hosts        []Host
	ErrorHandler ErrorHandler
	Timeout      time.Duration
}

Group is a group of hosts.

func NewGroup

func NewGroup(hosts []Host) Group

NewGroup returns a new Group consisting of the given hosts.

func NewSSHGroup

func NewSSHGroup(hostNames []string, sshConfigPath string) (g Group, err error)

NewSSHGroup returns a new group from the given host aliases. sshConfigPath determines the ssh_config file to use. If sshConfigPath is empty, the default configuration files will be used.

func (Group) Close

func (g Group) Close() (err error)

Close closes any connections to hosts.

func (Group) Run

func (g Group) Run(name string, f func(ctx context.Context, host Host) error)

Run runs the task on all hosts in the group concurrently.

type Host

type Host interface {
	// Name returns the name of this host.
	Name() string

	// Address returns the address of the host.
	Address() string

	// GetEnv retrieves the value of the environment variable named by the key.
	// It returns the value, which will be empty if the variable is not present.
	GetEnv(key string) string

	// GetFS returns the file system of the host.
	GetFS() fs.FS

	// NewCommand returns a new command runner.
	NewCommand() (CmdRunner, error)

	// Close closes the connection to the host.
	Close() error

	// SetVar sets a host variable with the given key and value
	SetVar(key string, val interface{})

	// GetVar gets the host variable with the given key.
	// Returns (val, true) if the variable exists, (nil, false) otherwise.
	GetVar(key string) (val interface{}, ok bool)
}

Host is a connection to a remote host.

func DialSSH

func DialSSH(name, addr string, cfg *ssh.ClientConfig) (Host, error)

DialSSH connects to a remote host using ssh.

type Path

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

Path is a path to a file or directory, relative to the prefix.

func NewPath

func NewPath(prefix, path string) (p Path, err error)

NewPath returns a new Path struct. prefix must be an absolute path, and path must be relative to the prefix.

func NewPathFromAbs

func NewPathFromAbs(path string) (p Path, err error)

NewPathFromAbs returns a new Path struct from an absolute path.

func (Path) String

func (p Path) String() string

type Perm

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

Perm describes the permissions that should be used when creating files or directories. Perm can use different permissions for files and directories. By default, it uses 644 for files and 755 for directories. If a file permission is specified by using NewPerm(), the WithDirPerm() method may be called to modify the directory permissions.

func NewPerm

func NewPerm(perm fs.FileMode) Perm

NewPerm returns a Perm with the requested file permission. Note that this will also set the directory permission. If a different directory permission is desired, you must call WithDirPerm on the returned Perm also.

func (Perm) GetDirPerm

func (p Perm) GetDirPerm() fs.FileMode

GetDirPerm returns the current directory permission, or the current file permission, or 755 if no permissions were set.

func (Perm) GetFilePerm

func (p Perm) GetFilePerm() fs.FileMode

GetFilePerm returs the current file permission, or 644 if no file permission was set.

func (*Perm) WithDirPerm

func (p *Perm) WithDirPerm(dirPerm fs.FileMode) Perm

WithDirPerm sets the directory permission of the Perm. It both mutates the original perm and returns a copy of it.

type Shell

type Shell struct {
	Command string
	Stdin   io.Reader
	Stdout  io.Writer
	Stderr  io.Writer
}

Shell runs a shell command.

func (Shell) Apply

func (sa Shell) Apply(ctx context.Context, host Host) (err error)

Apply runs the shell command on the host.

type TaskError

type TaskError struct {
	TaskName string
	HostName string
	Err      error
}

TaskError is the error type returned when an error occurs while running a task.

func (TaskError) Error

func (err TaskError) Error() string

func (TaskError) Unwrap

func (err TaskError) Unwrap() error

Unwrap returns the cause of the task error.

type Upload

type Upload struct {
	Src  Path
	Dest Path
	Perm Perm
}

Upload uploads a file or directory to a remote host.

func (Upload) Apply

func (u Upload) Apply(ctx context.Context, host Host) error

Apply performs the upload.