vagrant

Documentation

Index

• func Build(ctx *app.Context, opts *BuildOptions) error
• func Dev(opts *DevOptions) *router.Router
• func DevDep(dst *app.Context, src *app.Context, opts *DevDepOptions) (*app.DevDep, error)
• func DevTestTeardown(c *otto.Core) error
• func Project(ctx *context.Shared) *hashitools.Project
• type BuildOptions
• type DevDepOptions
• type DevOptions
  • func (opts *DevOptions) Vagrant(ctx *app.Context) *Vagrant
• type DevTestStepGuestScript
  • func (s *DevTestStepGuestScript) Run(c *otto.Core) error
• type DevTestStepInit
  • func (s *DevTestStepInit) Run(c *otto.Core) error
• type Layer
• type Layered
  • func DevLayered(ctx *app.Context, layers []*Layer) (*Layered, error)
  • func (l *Layered) Build(ctx *context.Shared) error
  • func (l *Layered) ConfigureEnv(v *Vagrant) error
  • func (l *Layered) Graph() (*dag.AcyclicGraph, error)
  • func (l *Layered) Pending() ([]string, error)
  • func (l *Layered) Prune(ctx *context.Shared) (int, error)
  • func (l *Layered) RemoveEnv(v *Vagrant) error
  • func (l *Layered) SetEnv(v *Vagrant, state envState) error
• type Output
  • func (o *Output) GoString() string
• type OutputCallback
• type SSHCache
  • func (c *SSHCache) Cache() error
  • func (c *SSHCache) Delete() error
  • func (c *SSHCache) Exec(cacheOkay bool) error
• type Vagrant
  • func (v *Vagrant) Execute(commandRaw ...string) error
  • func (v *Vagrant) ExecuteSilent(command ...string) error

Functions

func Build

func Build(ctx *app.Context, opts *BuildOptions) error

Build can be used to use Vagrant to build something. This will handle starting Vagrant, running the script, collecting files into a list, and destroying the Vagrant environment.

func Dev

func Dev(opts *DevOptions) *router.Router

Dev can be used as an implementation of app.App.Dev to automatically handle creating a development environment and forwarding commands down to Vagrant.

func DevDep

func DevDep(dst *app.Context, src *app.Context, opts *DevDepOptions) (*app.DevDep, error)

DevDep builds a dev dependency using Vagrant.

This function uses Build to build the dev dependency. Please see the documentation of that function for more details on how that works.

This function implements app.App.DevDep.

func DevTestTeardown

func DevTestTeardown(c *otto.Core) error

DevTestTeardown implements the otto.TestTeardownFunc type and should be used with otto.TestCase to clear out development environments cleanly.

func Project

func Project(ctx *context.Shared) *hashitools.Project

Project returns the hashitools Project for this.

Types

type BuildOptions

type BuildOptions struct {
	// Dir is the directory where Vagrant will be executed for the
	// build. This should be the directory with the Vagrantfile, usually.
	Dir string

	// Script is the script to execute within the VM. This script must
	// not ask for input.
	Script string
}

type DevDepOptions

type DevDepOptions struct {
	// Dir is the directory where Vagrant will be executed.
	Dir string

	// Script is the script to run to build the dev dependency.
	Script string

	// Files are the resulting files relative to the cache directory
	// that are part of the dep. If these don't exist, an error will be
	// generated.
	Files []string
}

type DevOptions

type DevOptions struct {
	// Dir is the path to the directory with the Vagrantfile. This
	// will default to `#{ctx.Dir}/dev` if empty.
	Dir string

	// DataDir is the path to the directory where Vagrant should store its data.
	// Defaults to `#{ctx.LocalDir/vagrant}` if empty.
	DataDir string

	// Layer, if non-nil, will be the set of layers that this environment
	// builds on top of. If this is set, then the layers will be managed
	// automatically by this.
	//
	// If this is nil, then layers won't be used.
	Layer *Layered

	// Instructions are help text that is shown after creating the
	// development environment.
	Instructions string
}

DevOptions is the configuration struct used for Dev.

func (*DevOptions) Vagrant

func (opts *DevOptions) Vagrant(ctx *app.Context) *Vagrant

type DevTestStepGuestScript

type DevTestStepGuestScript struct {
	Command string
}

DevTestStepGuestScript is an otto.TestStep that runs a script in the guest and verifies it succeeds (exit code 0).

func (*DevTestStepGuestScript) Run

func (s *DevTestStepGuestScript) Run(c *otto.Core) error

type DevTestStepInit

type DevTestStepInit struct{}

DevTestStepInit is a otto.TestStep that initilizes dev testing. This should be the first test step before any others for dev.

func (*DevTestStepInit) Run

func (s *DevTestStepInit) Run(c *otto.Core) error

type Layer

type Layer struct {
	// ID is a unique ID for the layer. See the note in Layered about
	// generating a new ID for every change/iteration in the Vagrantfile.
	ID string

	// Vagrantfile is the path to the Vagrantfile to bring up for this
	// layer. The Vagrantfile should handle all provisioning. This
	// Vagrantfile will be copied to another directory, so any paths
	// in it should be relative to the Vagrantfile.
	Vagrantfile string
}

Layer is a single layer of the Layered Vagrant environment.

type Layered

type Layered struct {
	// Layers are layers that are important for this run. This must include
	// all the Vagrantfiles for all the potential layers since we might need
	// to run all of them.
	Layers []*Layer

	// DataDir is the directory where Layered can write data to.
	DataDir string
}

Layered is a Vagrant environment that is created using a series of "layers". Otto manages these layers and this library automatically prunes unused layers. This library will also do the multi-process locking necessary to prevent races.

To update a layer (change it), you should create a Layer with a new ID. IDs should be considered immutable for all time. This is to prevent breaking other environments. Once a layer is safely no longer in use by anybody for a sufficient period of time, Otto will automatically prune it.

Layered itself doesn't manage the final Vagrant environment. This should be done outside of this using functions like Dev. Accounting should be done to avoid layers being pruned with `AddLeaf`, `RemoveLeaf`. If these aren't called layers underneath may be pruned which can corrupt leaves.

func DevLayered

func DevLayered(ctx *app.Context, layers []*Layer) (*Layered, error)

DevLayered returns a Layered setup for development.

This automatically prepares any layers for foundations. Your custom layers are then appended to the foundation layers. If you have no layers, no modification is necessary to the returned value. It is ready to go as-is.

func (*Layered) Build

func (l *Layered) Build(ctx *context.Shared) error

Build will build all the layers that are defined in this Layered struct. It will automatically output to the UI as needed.

This will automatically acquire a process-lock to ensure that no duplicate layers are ever built. The process lock usually assumes that Otto is being run by the same user.

func (*Layered) ConfigureEnv

func (l *Layered) ConfigureEnv(v *Vagrant) error

ConfigureEnv configures the Vagrant instance with the proper environment variables to be able to execute things.

Once the env is used, SetEnvStatus should be used to modify the env status around it. This is critical to make sure layers don't get pruned.

func (*Layered) Graph

func (l *Layered) Graph() (*dag.AcyclicGraph, error)

Graph will return the full graph that is currently encoded.

func (*Layered) Pending

func (l *Layered) Pending() ([]string, error)

Pending returns a list of layers that are pending creation. Note that between calling this and calling something like Build(), this state may be different.

func (*Layered) Prune

func (l *Layered) Prune(ctx *context.Shared) (int, error)

Prune will destroy all layers that haven't been used in a certain amount of time.

TODO: "certain amount of time" for now we just prune any orphans

func (*Layered) RemoveEnv

func (l *Layered) RemoveEnv(v *Vagrant) error

RemoveEnv will remove the environment from the tracked layers.

func (*Layered) SetEnv

func (l *Layered) SetEnv(v *Vagrant, state envState) error

SetEnv configures the status of an env, persisting that its ready or deleted which controls whether layers get pruned or not.

The Vagrant pointer given must already be configured using ConfigureEnv.

type Output

type Output struct {
	Timestamp string
	Target    string
	Type      string
	Data      []string
}

Output is a single line of machine-readable output from Vagrant.

func (*Output) GoString

func (o *Output) GoString() string

For testing

type OutputCallback

type OutputCallback func(*Output)

OutputCallback is the type that is called when there is a matching machine-readable output line for the UI.

type SSHCache

type SSHCache struct {
	// Path is the path to where the SSH cache file should go
	Path string

	// Vagrant is the Vagrant instance we'll use to execute Vagrant commands.
	Vagrant *Vagrant
}

SSHCache is a helper to cache the SSH connection info from Vagrant and use that for executing to avoid the overhead of loading Vagrant.

func (*SSHCache) Cache

func (c *SSHCache) Cache() error

Cache will execute "ssh-config" and cache the SSH info.

func (*SSHCache) Delete

func (c *SSHCache) Delete() error

Delete clears the cache.

func (*SSHCache) Exec

func (c *SSHCache) Exec(cacheOkay bool) error

Exec executes SSH and opens a console.

This will use the cached SSH info if it exists, or will otherwise drop into `vagrant ssh`. If cacheOkay is false, then it'll always go straight to `vagrant ssh`.

type Vagrant

type Vagrant struct {
	// Dir is the working directory where all Vagrant commands will
	// be executed from.
	Dir string

	// DataDir is the directory where Vagrant commands should store data.
	DataDir string

	// Env is extra environment variables to set when executing Vagrant.
	// This will be on top of the environment variables that are in this
	// process.
	Env map[string]string

	// Ui, if given, will be used to stream output from the Vagrant
	// commands. If this is nil, then the output will be logged but
	// won't be visible to the user.
	Ui ui.Ui

	// Callbacks is a mapping of callbacks that will be called for certain
	// event types within the output. These will always be serialized and
	// will block on this callback returning so it is important to make
	// this fast.
	Callbacks map[string]OutputCallback
	// contains filtered or unexported fields
}

Vagrant wraps `vagrant` execution into an easy-to-use API.

func (*Vagrant) Execute

func (v *Vagrant) Execute(commandRaw ...string) error

Execute executes a raw Vagrant command.

func (*Vagrant) ExecuteSilent

func (v *Vagrant) ExecuteSilent(command ...string) error