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_configfiles- Should support reading the public key files (it doesn't look like the
ssherpackage supports this fully)
- Should support reading the public key files (it doesn't look like the
- 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
- type ErrorHandler
- type Group
- type Host
- type Path
- type Perm
- type Shell
- type TaskError
- type Upload
Constants ¶
This section is empty.
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 Expand ¶
Expand expands any environment variables in the string 's' using the environment of the host 'h'.
func GetStringVar ¶
GetStringVar gets a string variable from the host.
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 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 NewSSHGroup ¶
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.
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.
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 ¶
NewPath returns a new Path struct. prefix must be an absolute path, and path must be relative to the prefix.
func NewPathFromAbs ¶
NewPathFromAbs returns a new Path struct from an absolute path.
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 ¶
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 ¶
GetDirPerm returns the current directory permission, or the current file permission, or 755 if no permissions were set.
func (Perm) GetFilePerm ¶
GetFilePerm returs the current file permission, or 644 if no file permission was set.
Source Files
Directories