vagrant

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 22, 2018 License: MIT Imports: 11 Imported by: 6

README

Release Build Status codecov.io GoDoc

go-vagrant

A golang wrapper around the Vagrant command-line utility.

Installation

go-vagrant can be installed with go get:

go get github.com/bmatcuk/go-vagrant

Import it in your code:

import "github.com/bmatcuk/go-vagrant"

The package name will be vagrant.

Basic Usage

First, you'll need to instantiate a VagrantClient object using NewVagrantClient. The function takes one argument: the path to the directory where the Vagrantfile lives. This instantiation will check that the vagrant command exists and that the Vagrantfile can be read.

From there, every vagrant action follows the same pattern: call the appropriate method on the client object to retrieve a command object. The command object has fields for any optional arguments. Then either call the command's Run() method, or call Start() and then Wait() on it later. Any output from the command, including errors, will be fields on the command object.

For example:

package main

import "github.com/bmatcuk/go-vagrant"

func main() {
  client, err := vagrant.NewVagrantClient(".")
  if err != nil {
    ...
  }

  upcmd := client.Up()
  upcmd.Verbose = true
  if err := upcmd.Run(); err != nil {
    ...
  }
  if upcmd.Error != nil {
    ...
  }

  // TODO: vagrant VMs are up!
}

Available Actions

Destroy

Stop and delete all traces of the vagrant machines.

func (*VagrantClient) Destroy() *DestroyCommand

Options:

  • Force (default: true) - Destroy without confirmation. Defaults to true because, when it's false, vagrant will try to ask for confirmation but complain that there's no attached TTY.
  • Parallel (default: false) - Enable or disable parallelism if provider supports it (automatically enables Force).

Response:

  • Error - Set if an error occurred.
Halt

Stops the vagrant machine.

func (*VagrantClient) Halt() *HaltCommand

Options:

  • Force (default: false) - Force shutdown (equivalent to pulling the power of the VM)

Response:

  • Error - Set if an error occurred.
Port

Get information about guest port forwarded mappings.

func (*VagrantClient) Port() *PortCommand

Response:

  • ForwardedPorts - a map of vagrant machine names to ForwardedPort objects. Each ForwardedPort has a Guest and a Host port, representing a mapping from the host port to the guest.
  • Error - Set if an error occurred.
Provision

Provision the vagrant machine.

func (*VagrantClient) Provision() *ProvisionCommand

Options:

  • Provisioners (default: nil) - Enable only certain provisioners, by type or name as an array of strings.

Response:

  • Error - Set if an error occurred.
Reload

Restarts the vagrant machine and loads any new Vagrantfile configuration.

func (*VagrantClient) Reload() *ReloadCommand

Options:

  • Provisioning (default: DefaultProvisioning) - By default will only run provisioners if they haven't been run already. If set to ForceProvisioning then provisioners will be forced to run; if set to DisableProvisioning then provisioners will be disabled.
  • Provisioners (default: nil) - Enable only certain provisioners, by type or name as an array of strings. Implies ForceProvisioning.

Response:

  • Error - Set if an error occurred.
Resume

Resume a suspended vagrant machine

func (*VagrantClient) Resume() *ResumeCommand

Options:

  • Provisioning (default: DefaultProvisioning) - By default will only run provisioners if they haven't been run already. If set to ForceProvisioning then provisioners will be forced to run; if set to DisableProvisioning then provisioners will be disabled.
  • Provisioners (default: nil) - Enable only certain provisioners, by type or name as an array of strings. Implies ForceProvisioning.

Response:

  • Error - Set if an error occurred.
SSHConfig

Get SSH configuration information for the vagrant machine.

func (*VagrantClient) SSHConfig() *SSHConfigCommand

Options:

  • Host (default: "") - Name the host for the config

Response:

  • Configs - a map of vagrant machine names to SSHConfig objects. Each SSHConfig has several fields including Host, User, Port, etc. You can see full field list in the godocs for SSHConfig.
Status

Get the status of the vagrant machine.

func (*VagrantClient) Status() *StatusCommand

Response:

  • Status - a map of vagrant machine names to a string describing the status of the VM.
  • Error - Set if an error occurred.
Suspend

Suspends the vagrant machine.

func (*VagrantClient) Suspend() *SuspendCommand

Response:

  • Error - Set if an error occurred.
Up

Starts and provisions the vagrant machine.

func (*VagrantClient) Up() *UpCommand

Options:

  • Provisioning (default: DefaultProvisioning) - By default will only run provisioners if they haven't been run already. If set to ForceProvisioning then provisioners will be forced to run; if set to DisableProvisioning then provisioners will be disabled.
  • Provisioners (default: nil) - Enable only certain provisioners, by type or name as an array of strings. Implies ForceProvisioning.
  • DestroyOnError (default: true) - Destroy machine if any fatal error happens.
  • Parallel (default: true) - Enable or disable parallelism if provider supports it.
  • Provider (default: "") - Back the machine with a specific provider.
  • InstallProvider (default: true) - If possible, install the provider if it isn't installed.

Response:

  • VMInfo - a map of vagrant machine names to VMInfo objects. Each VMInfo describes the Name of the machine and Provider.
  • Error - Set if an error occurred.
Version

Get the current and latest vagrant version.

func (*VagrantClient) Version() *VersionCommand

Response:

  • InstalledVersion - the version of vagrant installed
  • LatestVersion - the latest version available
  • Error - Set if an error occurred.

Documentation

Overview

go-vagrant is a golang wrapper around the vagrant command-line utility. Full documentation can be found in the README on github: 

https://github.com/bmatcuk/go-vagrant
Example 
client, err := NewVagrantClient("example")
if err != nil {
	fmt.Println("Got error while creating client:", err)
	os.Exit(-1)
}

// Let's start bringing up the vm
upcmd := client.Up()
upcmd.Verbose = true
fmt.Println("Bringing up the vm")
if err := upcmd.Start(); err != nil {
	fmt.Println("Error bringing up vm:", err)
	os.Exit(-1)
}

// while we're waiting, let's get version info
vercmd := client.Version()
if err := vercmd.Run(); err != nil {
	fmt.Println("Error retrieving version info:", err)
}

// now wait for up to finish
if err := upcmd.Wait(); err != nil {
	fmt.Println("Error waiting for up:", err)
	os.Exit(-1)
}

fmt.Println("\n\nInstalled Vagrant version:", vercmd.InstalledVersion)

// Get vm status
statuscmd := client.Status()
if err := statuscmd.Run(); err != nil {
	fmt.Println("Error getting status:", err)
} else {
	for vm, status := range statuscmd.Status {
		fmt.Printf("%v: %v\n", vm, status)
	}
}

// Destroy vm
if err := client.Destroy().Run(); err != nil {
	fmt.Println("Error destroying vm:", err)
	os.Exit(-1)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BaseCommand 

type BaseCommand struct {
	OutputParser

	// Context for the running command - nil means none
	Context context.Context

	// Additional arguments to pass to the command. go-vagrant attempts to define
	// each argument as a field on the struct, but future versions of vagrant may
	// add options that didn't exist at the time of authoring. You can use this
	// to pass options to vagrant that go-vagrant doesn't know about.
	AdditionalArgs []string

	// Env is merged with the current process's environment and passed to the
	// vagrant command. Each entry is a "key=value" pair with later keys taking
	// precedence in the case of duplicates (keys here will take precedence over
	// keys in the current environment, too).
	Env []string

	// The underlying process, once it has been started with Run() or Start()
	Process *os.Process

	// ProcessState contains information about the process after it has exited.
	// Available after Run() or Wait().
	ProcessState *os.ProcessState
	// contains filtered or unexported fields
}

Base functionality and fields for all commands constructed from the VagrantClient.

func (*BaseCommand) Run 

func (b *BaseCommand) Run() error

Run the command.

func (*BaseCommand) Start 

func (b *BaseCommand) Start() error

Start the command. You must call Wait() to complete execution.

func (*BaseCommand) Wait 

func (b *BaseCommand) Wait() error

If execution was started with Start(), you must Wait() for it to finish.

type DestroyCommand 

type DestroyCommand struct {
	BaseCommand
	ErrorResponse

	// Destroy without confirmation (defaults to true because, when false,
	// vagrant will try to ask for confirmation, but can't because it's running
	// without a TTY so it errors).
	Force bool

	// Enable parallelism if the provider supports it (automatically enables
	// force, default: false)
	Parallel bool
}

A DestroyCommand specifies the options and output of vagrant destroy.

func (*DestroyCommand) Run 

func (cmd *DestroyCommand) Run() error

Run the command

func (*DestroyCommand) Start 

func (cmd *DestroyCommand) Start() error

Start the command. You must call Wait() to complete execution.

type ErrorResponse added in v1.1.0 

type ErrorResponse struct {
	// If set, there was an error while running the vagrant command.
	Error error
}

type ForwardedPort 

type ForwardedPort struct {
	// Port on the guest OS
	Guest int

	// Port on the host which forwards to the guest
	Host int
}

type HaltCommand 

type HaltCommand struct {
	BaseCommand
	ErrorResponse

	// Force shutdown (equivalent to pulling the power from the machine, default:
	// false)
	Force bool
}

A HaltCommand specifies the options and output of vagrant halt.

func (*HaltCommand) Run 

func (cmd *HaltCommand) Run() error

Run the command

func (*HaltCommand) Start 

func (cmd *HaltCommand) Start() error

Start the command. You must call Wait() to complete execution.

type OutputParser 

type OutputParser struct {
	// If true, vagrant output will be echoed to stdout. Default: false
	Verbose bool
}

type PortCommand 

type PortCommand struct {
	BaseCommand
	PortResponse
}

PortCommand specifies the options and output of vagrant port.

func (*PortCommand) Run 

func (cmd *PortCommand) Run() error

Run the command

func (*PortCommand) Start 

func (cmd *PortCommand) Start() error

Start the command. You must call Wait() to complete execution.

type PortResponse 

type PortResponse struct {
	ErrorResponse

	// List of forwarded ports by VM. The keys of the may are Vagrant VM names
	// (ex: default) and the values are arrays of ForwardedPort structs.
	ForwardedPorts map[string][]ForwardedPort
}

type ProvisionCommand 

type ProvisionCommand struct {
	BaseCommand
	ErrorResponse
	ProvisionersArgument
}

ProvisionCommand specifies the options and output of vagrant provision

func (*ProvisionCommand) Run 

func (cmd *ProvisionCommand) Run() error

Run the command

func (*ProvisionCommand) Start 

func (cmd *ProvisionCommand) Start() error

Start the command. You must call Wait() to complete execution.

type ProvisionersArgument added in v1.1.0 

type ProvisionersArgument struct {
	// Enabled provisioners by type or name (default: blank which means they're
	// all enable or disabled depending on the Provisioning flag)
	Provisioners []string
}

Adds a Provisioners argument to a command

type ProvisioningArgument added in v1.1.0 

type ProvisioningArgument struct {
	ProvisionersArgument

	// Enable or disable provisioning
	Provisioning ProvisioningOption
}

Adds Provisioning and Provisioners arguments to a Command

type ProvisioningOption added in v1.1.0 

type ProvisioningOption uint8
const (
	// By default, provisioning will only run if it hasn't run already. "always"
	// provisioners will always run, however.
	DefaultProvisioning ProvisioningOption = iota

	// Force provisioning, even if it has already run.
	ForceProvisioning

	// Disable provisioning
	DisableProvisioning
)

type ReloadCommand 

type ReloadCommand struct {
	BaseCommand
	ErrorResponse
	ProvisioningArgument
}

ReloadCommand specifies the options and output of vagrant reload

func (*ReloadCommand) Run 

func (cmd *ReloadCommand) Run() error

Run the command

func (*ReloadCommand) Start 

func (cmd *ReloadCommand) Start() error

Start the command. You must call Wait() to complete execution.

type ResumeCommand added in v1.1.0 

type ResumeCommand struct {
	BaseCommand
	ErrorResponse
	ProvisioningArgument
}

A ResumeCommand specifies the options and output of vagrant resume.

func (*ResumeCommand) Run added in v1.1.0 

func (cmd *ResumeCommand) Run() error

Run the command

func (*ResumeCommand) Start added in v1.1.0 

func (cmd *ResumeCommand) Start() error

Start the command. You must call Wait() to complete execution.

type SSHConfig 

type SSHConfig struct {
	AdditionalFields       map[string]string
	ForwardAgent           string
	Host                   string
	HostName               string
	IdentitiesOnly         string
	IdentityFile           string
	LogLevel               string
	PasswordAuthentication string
	Port                   int
	StrictHostKeyChecking  string
	User                   string
	UserKnownHostsFile     string
}

type SSHConfigCommand 

type SSHConfigCommand struct {
	BaseCommand
	SSHConfigResponse

	// Name of a specific host to get SSH config info for. If not set, info for
	// all VMs will be pulled.
	Host string
}

SSHConfigCommand specifies options and output from vagrant ssh-config

func (*SSHConfigCommand) Run 

func (cmd *SSHConfigCommand) Run() error

Run the command

func (*SSHConfigCommand) Start 

func (cmd *SSHConfigCommand) Start() error

Start the command. You must call Wait() to complete execution.

type SSHConfigResponse 

type SSHConfigResponse struct {
	ErrorResponse

	// SSH Configs per VM. Map keys match vagrant VM names (ex: default) and
	// the values are configs.
	Configs map[string]SSHConfig
}

type StatusCommand 

type StatusCommand struct {
	BaseCommand
	StatusResponse
}

StatusCommand specifies options and output from vagrant status

func (*StatusCommand) Run 

func (cmd *StatusCommand) Run() error

Run the command

func (*StatusCommand) Start 

func (cmd *StatusCommand) Start() error

Start the command. You must call Wait() to complete execution.

type StatusResponse 

type StatusResponse struct {
	ErrorResponse

	// Status per Vagrant VM. Keys are Vagrant VM names (ex: default) and values
	// are the status of the VM.
	Status map[string]string
}

type SuspendCommand 

type SuspendCommand struct {
	BaseCommand
	ErrorResponse
}

SuspendCommand specifies options and output from vagrant suspend

func (*SuspendCommand) Run 

func (cmd *SuspendCommand) Run() error

Run the command

func (*SuspendCommand) Start 

func (cmd *SuspendCommand) Start() error

Start the command. You must call Wait() to complete execution.

type UpCommand 

type UpCommand struct {
	BaseCommand
	UpResponse
	ProvisioningArgument

	// Destroy on error (default: true)
	DestroyOnError bool

	// Enable parallel execution if the provider supports it (default: true)
	Parallel bool

	// Provider to use (default: blank which means vagrant will use the default
	// provider)
	Provider string

	// Install the provider if it isn't installed, if possible (default: false)
	InstallProvider bool
}

UpCommand specifies options and output from vagrant up.

func (*UpCommand) Run 

func (cmd *UpCommand) Run() error

Run the command

func (*UpCommand) Start 

func (cmd *UpCommand) Start() error

Start the command. You must call Wait() to complete execution.

type UpResponse 

type UpResponse struct {
	ErrorResponse

	// Info about all of the VMs constructed by the Vagrantfile. The map keys are
	// vagrant VM names (ex: default) and the values are VMInfo's.
	VMInfo map[string]*VMInfo
}

type VMInfo 

type VMInfo struct {
	// Name of the VM set by vagrant (ex: mydir_default_1534347044260_6006)
	Name string

	// The VM provider (ex: virtualbox)
	Provider string
}

type VagrantClient 

type VagrantClient struct {
	// Directory where the Vagrantfile can be found.
	//
	// Normally this would be set by NewVagrantClient() and shouldn't
	// be changed afterward.
	VagrantfileDir string
	// contains filtered or unexported fields
}

Library users should construct a new VagrantClient using NewVagrantClient(). From the client, vagrant commands can be constructed such as: client.Up().

func NewVagrantClient 

func NewVagrantClient(vagrantfileDir string) (*VagrantClient, error)

Create a new VagrantClient.

vagrantfileDir should be the path to a directory where the Vagrantfile exists.

func (*VagrantClient) Destroy 

func (client *VagrantClient) Destroy() *DestroyCommand

Run vagrant destroy. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Errors will be recorded in Error.

func (*VagrantClient) Halt 

func (client *VagrantClient) Halt() *HaltCommand

Run vagrant halt. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Errors will be recorded in Error.

func (*VagrantClient) Port 

func (client *VagrantClient) Port() *PortCommand

Run vagrant port. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Output will be in ForwardedPorts with any error in Error.

func (*VagrantClient) Provision 

func (client *VagrantClient) Provision() *ProvisionCommand

Run vagrant provision. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Errors will be recorded in Error.

func (*VagrantClient) Reload 

func (client *VagrantClient) Reload() *ReloadCommand

Run vagrant reload. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Errors will be recorded in Error.

func (*VagrantClient) Resume added in v1.1.0 

func (client *VagrantClient) Resume() *ResumeCommand

Run vagrant resume. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Errors will be recorded in Error.

func (*VagrantClient) SSHConfig 

func (client *VagrantClient) SSHConfig() *SSHConfigCommand

Run vagrant ssh-config. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Output will be in Configs and any error will be in Error.

func (*VagrantClient) Status 

func (client *VagrantClient) Status() *StatusCommand

Run vagrant status. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Output will be in Status and any error will be in Error.

func (*VagrantClient) Suspend 

func (client *VagrantClient) Suspend() *SuspendCommand

Run vagrant suspend. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Errors will be recorded in Error.

func (*VagrantClient) Up 

func (client *VagrantClient) Up() *UpCommand

Run vagrant up. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Output will be in VMInfo or Error.

func (*VagrantClient) Version 

func (client *VagrantClient) Version() *VersionCommand

Run vagrant version. After setting options as appropriate, you must call Run() or Start() followed by Wait() to execute. Output will be in InstalledVersion and LatestVersion and any error will be in Error.

type VersionCommand 

type VersionCommand struct {
	BaseCommand
	VersionResponse
}

VersionCommand specifies options and output from vagrant version

func (*VersionCommand) Run 

func (cmd *VersionCommand) Run() error

Run the command

func (*VersionCommand) Start 

func (cmd *VersionCommand) Start() error

Start the command. You must call Wait() to complete execution.

type VersionResponse 

type VersionResponse struct {
	ErrorResponse

	// The current version
	InstalledVersion string

	// The latest version
	LatestVersion string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.