urknall

README

Urknall - opinionated provisioning for clever developers

Urknall is the basic building block for creating go based tools for the administration of complex infrastructure. It provides the mechanisms to access resources and keep a cache of executed tasks. Description of tasks is done using a mix of explicit shell commands and abstractions for more complex actions being pragmatic, but readable.

• Automate provisioning: Urknall provides automated provisioning, so that resources can be set up reproducibly and easily. Thereby Urknall helps with scaling infrastructure to the required size.
• Agentless tool that only relies on common UNIX tools and provides decent caching: As Urknall works agentless on most UNIX based systems, adding new resources to the infrastructure is effortless. The caching keeps track of performed tasks and makes repeated provisioning with thoughtful changes possible.
• Template mechanism that helps at the start, but get’s out of the way later on: Urknall provides some basic templates, but lets users modify those or add new ones to solve the specific problem at hand.

urknall is developed and maintained by Dynport GmbH, the company behind the translation management software PhraseApp.

Documentation

Overview

Package urknall

See http://urknall.dynport.de for detailed documentation.

Index

• func DryRun(target Target, tpl Template) (e error)
• func OpenLogger(w io.Writer) io.Closer
• func Run(target Target, tpl Template) (e error)
• type Build
  • func (b *Build) DryRun() error
  • func (b *Build) Run() error
• type Package
• type Target
  • func NewLocalTarget() (Target, error)
  • func NewSshTarget(address string) (Target, error)
  • func NewSshTargetWithPassword(address, password string) (Target, error)
  • func NewSshTargetWithPrivateKey(address string, key []byte) (Target, error)
• type Task
  • func NewTask() Task
• type Template
• type TemplateFunc
  • func (f TemplateFunc) Render(p Package)

Examples

• Build
• OpenLogger

Functions

func DryRun

func DryRun(target Target, tpl Template) (e error)

A shortcut creating and runnign a build from the given target and template with the DryRun flag set to true. This is quite helpful to actually see which commands would be exeucted in the current setting, without actually doing anything.

func OpenLogger

func OpenLogger(w io.Writer) io.Closer

OpenLogger creates a logging facility for urknall using the given writer for output. Note that the resource must be closed!

Example

logger := OpenLogger(os.Stdout)
defer logger.Close()

// short: defer OpenLogger(os.Stdout).Close()

func Run

func Run(target Target, tpl Template) (e error)

A shortcut creating and running a build from the given target and template.

Types

type Build

type Build struct {
	Target            // Where to run the build.
	Template          // What to actually build.
	Env      []string // Environment variables in the form `KEY=VALUE`.
}

A build is the glue between a target and template.

Example

package main

import (
	"log"

	"github.com/dynport/urknall/cmd"
)

func main() {
	template := &ExampleTemplate{}
	target, e := NewLocalTarget()

	if e != nil {
		log.Fatal(e)
	}

	build := &Build{Target: target, Template: template}
	if e := build.Run(); e != nil {
		log.Fatal(e)
	}
}

// An example template function. This is helpful to render templates that don't
// need configuration like the following ExampleTemplate.
func AnExampleTemplateFunc(pkg Package) {
	pkg.AddCommands("example", Shell("echo template func"))
}

// A simple template with configuration.
type ExampleTemplate struct {
	Parameter string `urknall:"default=example"`
	Boolean   bool   `urknall:"required=true"`
}

// Templates must implement the Render function.
func (tmpl *ExampleTemplate) Render(pkg Package) {
	// Template parameters can be used in go's text/template style.
	pkg.AddCommands("base", Shell("echo {{ .Parameter }}"))
	if tmpl.Boolean { // Only add template function if Boolean value is true.
		pkg.AddTemplate("func", TemplateFunc(AnExampleTemplateFunc))
	}
}

// Need to implement a command. Those come with the default code created by the
// `urknall init` method, so in most cases this must not be done manually.
type ShellCmd struct {
	cmd string
}

func (c *ShellCmd) Shell() string {
	return c.cmd
}

// Helper function to easily create a ShellCmd.
func Shell(cmd string) cmd.Command {
	return &ShellCmd{cmd: cmd}
}

func (*Build) DryRun

func (b *Build) DryRun() error

func (*Build) Run

func (b *Build) Run() error

This will render the build's template into a package and run all its tasks.

type Package

type Package interface {
	AddTemplate(string, Template)       // Add another template, nested below the current one.
	AddCommands(string, ...cmd.Command) // Add a new task from the given commands.
	AddTask(string, Task)               // Add the given tasks to the package with the given name.
}

The package is an interface. It provides the methods used to add tasks to a package. The packages's AddTemplate and AddCommands methods will internally create tasks.

Nesting of templates provides a lot of flexibility as different configurations can be used depending on the greater context.

The first argument of all three Add methods is a string. These strings are used as identifiers for the caching mechanism. They must be unique over all tasks. For nested templates the identifiers are concatenated using ".".

type Target

type Target interface {
	Command(cmd string) (target.ExecCommand, error)
	User() string
	String() string
	Reset() error
}

The target interface is used to describe something a package can be built on.

func NewLocalTarget

func NewLocalTarget() (Target, error)

Use the local host for building.

func NewSshTarget

func NewSshTarget(address string) (Target, error)

Create an SSH target. The address is an identifier of the form `[<user>@?]<host>[:port]`. It is assumed that authentication via public key will work, i.e. the remote host has the building user's public key in its authorized_keys file.

func NewSshTargetWithPassword

func NewSshTargetWithPassword(address, password string) (Target, error)

Special SSH target that uses the given password for accessing the machine. This is required mostly for testing and shouldn't be used in production settings.

func NewSshTargetWithPrivateKey

func NewSshTargetWithPrivateKey(address string, key []byte) (Target, error)

Create a SSH target with a private access key

type Task

type Task interface {
	Add(cmds ...interface{}) Task
	Commands() ([]cmd.Command, error)
}

A task is a list of commands. Each task is cached internally, i.e. if an command has been executed already, none of the preceding tasks has changed and neither the command itself, then it won't be executed again. This enhances performance and removes the burden of writing idempotent commands.

func NewTask

func NewTask() Task

Create a task. This is available to provide maximum flexibility, but shouldn't be required very often. The resulting task can be registered to an package using the AddTask method.

type Template

type Template interface {
	Render(pkg Package)
}

A template is used to modularize the urknall setting. Templates are rendered into a package and during rendering tasks can be added.

type TemplateFunc

type TemplateFunc func(Package)

This is a short-cut usable for templates without configuration, i.e. where no separate struct is required.

func (TemplateFunc) Render

func (f TemplateFunc) Render(p Package)