packer

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2013 License: MPL-2.0 Imports: 20 Imported by: 0

Documentation

Overview

The packer package contains the core components of Packer.

Index

Constants

View Source 
const (
	// This is the key in configurations that is set to the name of the
	// build.
	BuildNameConfigKey = "packer_build_name"

	// This is the key in the configuration that is set to the type
	// of the builder that is run. This is useful for provisioners and
	// such who want to make use of this.
	BuilderTypeConfigKey = "packer_builder_type"

	// This is the key in configurations that is set to "true" when Packer
	// debugging is enabled.
	DebugConfigKey = "packer_debug"

	// This is the key in configurations that is set to "true" when Packer
	// force build is enabled.
	ForceConfigKey = "packer_force"

	// This key contains a map[string]string of the user variables for
	// template processing.
	UserVariablesConfigKey = "packer_user_variables"
)
View Source 
const (
	UiColorRed     UiColor = 31
	UiColorGreen           = 32
	UiColorYellow          = 33
	UiColorBlue            = 34
	UiColorMagenta         = 35
	UiColorCyan            = 36
)
View Source 
const HookProvision = "packer_provision"

This is the hook that should be fired for provisioners to run.

View Source 
const Version = "0.3.0"

The version of packer.

View Source 
const VersionPrerelease = ""

Any pre-release marker for the version. If this is "" (empty string), then it means that it is a final release. Otherwise, this is the pre-release marker.

Variables

View Source 
var GitCommit string

The git commit that is being compiled. This will be filled in by the compiler for source builds.

Functions

This section is empty.

Types

type Artifact 

type Artifact interface {
	// Returns the ID of the builder that was used to create this artifact.
	// This is the internal ID of the builder and should be unique to every
	// builder. This can be used to identify what the contents of the
	// artifact actually are.
	BuilderId() string

	// Returns the set of files that comprise this artifact. If an
	// artifact is not made up of files, then this will be empty.
	Files() []string

	// The ID for the artifact, if it has one. This is not guaranteed to
	// be unique every run (like a GUID), but simply provide an identifier
	// for the artifact that may be meaningful in some way. For example,
	// for Amazon EC2, this value might be the AMI ID.
	Id() string

	// Returns human-readable output that describes the artifact created.
	// This is used for UI output. It can be multiple lines.
	String() string

	// Destroy deletes the artifact. Packer calls this for various reasons,
	// such as if a post-processor has processed this artifact and it is
	// no longer needed.
	Destroy() error
}

An Artifact is the result of a build, and is the metadata that documents what a builder actually created. The exact meaning of the contents is specific to each builder, but this interface is used to communicate back to the user the result of a build.

type BasicUi added in v0.3.0 

type BasicUi struct {
	Reader io.Reader
	Writer io.Writer
	// contains filtered or unexported fields
}

The BasicUI is a UI that reads and writes from a standard Go reader and writer. It is safe to be called from multiple goroutines. Machine readable output is simply logged for this UI.

func (*BasicUi) Ask added in v0.3.0 

func (rw *BasicUi) Ask(query string) (string, error)

func (*BasicUi) Error added in v0.3.0 

func (rw *BasicUi) Error(message string)

func (*BasicUi) Machine added in v0.3.0 

func (rw *BasicUi) Machine(t string, args ...string)

func (*BasicUi) Message added in v0.3.0 

func (rw *BasicUi) Message(message string)

func (*BasicUi) Say added in v0.3.0 

func (rw *BasicUi) Say(message string)

type Build 

type Build interface {
	// Name is the name of the build. This is unique across a single template,
	// but not absolutely unique. This is meant more to describe to the user
	// what is being built rather than being a unique identifier.
	Name() string

	// Prepare configures the various components of this build and reports
	// any errors in doing so (such as syntax errors, validation errors, etc.)
	Prepare(v map[string]string) error

	// Run runs the actual builder, returning an artifact implementation
	// of what is built. If anything goes wrong, an error is returned.
	Run(Ui, Cache) ([]Artifact, error)

	// Cancel will cancel a running build. This will block until the build
	// is actually completely cancelled.
	Cancel()

	// SetDebug will enable/disable debug mode. Debug mode is always
	// enabled by adding the additional key "packer_debug" to boolean
	// true in the configuration of the various components. This must
	// be called prior to Prepare.
	//
	// When SetDebug is set to true, parallelism between builds is
	// strictly prohibited.
	SetDebug(bool)

	// SetForce will enable/disable forcing a build when artifacts exist.
	//
	// When SetForce is set to true, existing artifacts from the build are
	// deleted prior to the build.
	SetForce(bool)
}

A Build represents a single job within Packer that is responsible for building some machine image artifact. Builds are meant to be parallelized.

type Builder 

type Builder interface {
	// Prepare is responsible for configuring the builder and validating
	// that configuration. Any setup should be done in this method. Note that
	// NO side effects should take place in prepare, it is meant as a state
	// setup only. Calling Prepare is not necessarilly followed by a Run.
	//
	// The parameters to Prepare are a set of interface{} values of the
	// configuration. These are almost always `map[string]interface{}`
	// parsed from a template, but no guarantee is made.
	//
	// Each of the configuration values should merge into the final
	// configuration.
	Prepare(...interface{}) error

	// Run is where the actual build should take place. It takes a Build and a Ui.
	Run(ui Ui, hook Hook, cache Cache) (Artifact, error)

	// Cancel cancels a possibly running Builder. This should block until
	// the builder actually cancels and cleans up after itself.
	Cancel()
}

Implementers of Builder are responsible for actually building images on some platform given some configuration.

In addition to the documentation on Prepare above: Prepare is sometimes configured with a `map[string]interface{}` that has a key "packer_debug". This is a boolean value. If it is set to true, then the builder should enable a debug mode which allows builder developers and advanced users to introspect what is going on during a build. During debug builds, parallelism is strictly disabled, so it is safe to request input from stdin and so on.

type BuilderFunc 

type BuilderFunc func(name string) (Builder, error)

The function type used to lookup Builder implementations.

type Cache 

type Cache interface {
	// Lock takes a key and returns the path where the file can be written to.
	// Packer guarantees that no other process will write to this file while
	// the lock is held.
	//
	// If the key has an extension (e.g., file.ext), the resulting path
	// will have that extension as well.
	//
	// The cache will block and wait for the lock.
	Lock(string) string

	// Unlock will unlock a certain cache key. Be very careful that this
	// is only called once per lock obtained.
	Unlock(string)

	// RLock returns the path to a key in the cache and locks it for reading.
	// The second return parameter is whether the key existed or not.
	// This will block if any locks are held for writing. No lock will be
	// held if the key doesn't exist.
	RLock(string) (string, bool)

	// RUnlock will unlock a key for reading.
	RUnlock(string)
}

Cache implements a caching interface where files can be stored for re-use between multiple runs.

type ColoredUi 

type ColoredUi struct {
	Color      UiColor
	ErrorColor UiColor
	Ui         Ui
}

ColoredUi is a UI that is colored using terminal colors.

func (*ColoredUi) Ask 

func (u *ColoredUi) Ask(query string) (string, error)

func (*ColoredUi) Error 

func (u *ColoredUi) Error(message string)

func (*ColoredUi) Machine added in v0.3.0 

func (u *ColoredUi) Machine(t string, args ...string)

func (*ColoredUi) Message 

func (u *ColoredUi) Message(message string)

func (*ColoredUi) Say 

func (u *ColoredUi) Say(message string)

type Command 

type Command interface {
	// Help should return long-form help text that includes the command-line
	// usage, a brief few sentences explaining the function of the command,
	// and the complete list of flags the command accepts.
	Help() string

	// Run should run the actual command with the given environmet and
	// command-line arguments. It should return the exit status when it is
	// finished.
	Run(env Environment, args []string) int

	// Synopsis should return a one-line, short synopsis of the command.
	// This should be less than 50 characters ideally.
	Synopsis() string
}

A command is a runnable sub-command of the `packer` application. When `packer` is called with the proper subcommand, this will be called.

The mapping of command names to command interfaces is in the Environment struct.

type CommandFunc 

type CommandFunc func(name string) (Command, error)

The function type used to lookup Command implementations.

type Communicator 

type Communicator interface {
	// Start takes a RemoteCmd and starts it. The RemoteCmd must not be
	// modified after being used with Start, and it must not be used with
	// Start again. The Start method returns immediately once the command
	// is started. It does not wait for the command to complete. The
	// RemoteCmd.Exited field should be used for this.
	Start(*RemoteCmd) error

	// Upload uploads a file to the machine to the given path with the
	// contents coming from the given reader. This method will block until
	// it completes.
	Upload(string, io.Reader) error

	// Download downloads a file from the machine from the given remote path
	// with the contents writing to the given writer. This method will
	// block until it completes.
	Download(string, io.Writer) error
}

A Communicator is the interface used to communicate with the machine that exists that will eventually be packaged into an image. Communicators allow you to execute remote commands, upload files, etc.

Communicators must be safe for concurrency, meaning multiple calls to Start or any other method may be called at the same time.

type ComponentFinder 

type ComponentFinder struct {
	Builder       BuilderFunc
	Command       CommandFunc
	Hook          HookFunc
	PostProcessor PostProcessorFunc
	Provisioner   ProvisionerFunc
}

ComponentFinder is a struct that contains the various function pointers necessary to look up components of Packer such as builders, commands, etc.

type DispatchHook 

type DispatchHook struct {
	Mapping map[string][]Hook
}

A Hook implementation that dispatches based on an internal mapping.

func (*DispatchHook) Run 

func (h *DispatchHook) Run(name string, ui Ui, comm Communicator, data interface{}) error

Runs the hook with the given name by dispatching it to the proper hooks if a mapping exists. If a mapping doesn't exist, then nothing happens.

type Environment 

type Environment interface {
	Builder(string) (Builder, error)
	Cache() Cache
	Cli([]string) (int, error)
	Hook(string) (Hook, error)
	PostProcessor(string) (PostProcessor, error)
	Provisioner(string) (Provisioner, error)
	Ui() Ui
}

The environment interface provides access to the configuration and state of a single Packer run.

It allows for things such as executing CLI commands, getting the list of available builders, and more.

func NewEnvironment 

func NewEnvironment(config *EnvironmentConfig) (resultEnv Environment, err error)

This creates a new environment

type EnvironmentConfig 

type EnvironmentConfig struct {
	Cache      Cache
	Commands   []string
	Components ComponentFinder
	Ui         Ui
}

This struct configures new environments.

func DefaultEnvironmentConfig 

func DefaultEnvironmentConfig() *EnvironmentConfig

DefaultEnvironmentConfig returns a default EnvironmentConfig that can be used to create a new enviroment with NewEnvironment with sane defaults.

type FileCache 

type FileCache struct {
	CacheDir string
	// contains filtered or unexported fields
}

FileCache implements a Cache by caching the data directly to a cache directory.

func (*FileCache) Lock 

func (f *FileCache) Lock(key string) string

func (*FileCache) RLock 

func (f *FileCache) RLock(key string) (string, bool)

func (*FileCache) RUnlock 

func (f *FileCache) RUnlock(key string)

func (*FileCache) Unlock 

func (f *FileCache) Unlock(key string)

type Hook 

type Hook interface {
	Run(string, Ui, Communicator, interface{}) error
}

A Hook is used to hook into an arbitrarily named location in a build, allowing custom behavior to run at certain points along a build.

Run is called when the hook is called, with the name of the hook and arbitrary data associated with it. To know what format the data is in, you must reference the documentation for the specific hook you're interested in. In addition to that, the Hook is given access to a UI so that it can output things to the user.

type HookFunc 

type HookFunc func(name string) (Hook, error)

The function type used to lookup Hook implementations.

type MachineReadableUi added in v0.3.0 

type MachineReadableUi struct {
	Writer io.Writer
}

MachineReadableUi is a UI that only outputs machine-readable output to the given Writer.

func (*MachineReadableUi) Ask added in v0.3.0 

func (u *MachineReadableUi) Ask(query string) (string, error)

func (*MachineReadableUi) Error added in v0.3.0 

func (u *MachineReadableUi) Error(message string)

func (*MachineReadableUi) Machine added in v0.3.0 

func (u *MachineReadableUi) Machine(category string, args ...string)

func (*MachineReadableUi) Message added in v0.3.0 

func (u *MachineReadableUi) Message(message string)

func (*MachineReadableUi) Say added in v0.3.0 

func (u *MachineReadableUi) Say(message string)

type MultiError 

type MultiError struct {
	Errors []error
}

MultiError is an error type to track multiple errors. This is used to accumulate errors in cases such as configuration parsing, and returning them as a single error.

func MultiErrorAppend added in v0.2.1 

func MultiErrorAppend(err error, errs ...error) *MultiError

MultiErrorAppend is a helper function that will append more errors onto a MultiError in order to create a larger multi-error. If the original error is not a MultiError, it will be turned into one.

func (*MultiError) Error 

func (e *MultiError) Error() string

type PostProcessor 

type PostProcessor interface {
	// Configure is responsible for setting up configuration, storing
	// the state for later, and returning and errors, such as validation
	// errors.
	Configure(...interface{}) error

	// PostProcess takes a previously created Artifact and produces another
	// Artifact. If an error occurs, it should return that error. If `keep`
	// is to true, then the previous artifact is forcibly kept.
	PostProcess(Ui, Artifact) (a Artifact, keep bool, err error)
}

A PostProcessor is responsible for taking an artifact of a build and doing some sort of post-processing to turn this into another artifact. An example of a post-processor would be something that takes the result of a build, compresses it, and returns a new artifact containing a single file of the prior artifact compressed.

type PostProcessorFunc 

type PostProcessorFunc func(name string) (PostProcessor, error)

The function type used to lookup PostProcessor implementations.

type ProvisionHook 

type ProvisionHook struct {
	// The provisioners to run as part of the hook. These should already
	// be prepared (by calling Prepare) at some earlier stage.
	Provisioners []Provisioner
}

A Hook implementation that runs the given provisioners.

func (*ProvisionHook) Run 

func (h *ProvisionHook) Run(name string, ui Ui, comm Communicator, data interface{}) error

Runs the provisioners in order.

type Provisioner 

type Provisioner interface {
	// Prepare is called with a set of configurations to setup the
	// internal state of the provisioner. The multiple configurations
	// should be merged in some sane way.
	Prepare(...interface{}) error

	// Provision is called to actually provision the machine. A UI is
	// given to communicate with the user, and a communicator is given that
	// is guaranteed to be connected to some machine so that provisioning
	// can be done.
	Provision(Ui, Communicator) error
}

A provisioner is responsible for installing and configuring software on a machine prior to building the actual image.

type ProvisionerFunc 

type ProvisionerFunc func(name string) (Provisioner, error)

The function type used to lookup Provisioner implementations.

type RemoteCmd 

type RemoteCmd struct {
	// Command is the command to run remotely. This is executed as if
	// it were a shell command, so you are expected to do any shell escaping
	// necessary.
	Command string

	// Stdin specifies the process's standard input. If Stdin is
	// nil, the process reads from an empty bytes.Buffer.
	Stdin io.Reader

	// Stdout and Stderr represent the process's standard output and
	// error.
	//
	// If either is nil, it will be set to ioutil.Discard.
	Stdout io.Writer
	Stderr io.Writer

	// This will be set to true when the remote command has exited. It
	// shouldn't be set manually by the user, but there is no harm in
	// doing so.
	Exited bool

	// Once Exited is true, this will contain the exit code of the process.
	ExitStatus int
	// contains filtered or unexported fields
}

RemoteCmd represents a remote command being prepared or run.

func (*RemoteCmd) SetExited added in v0.2.2 

func (r *RemoteCmd) SetExited(status int)

SetExited is a helper for setting that this process is exited. This should be called by communicators who are running a remote command in order to set that the command is done.

func (*RemoteCmd) StartWithUi added in v0.2.1 

func (r *RemoteCmd) StartWithUi(c Communicator, ui Ui) error

StartWithUi runs the remote command and streams the output to any configured Writers for stdout/stderr, while also writing each line as it comes to a Ui.

func (*RemoteCmd) Wait 

func (r *RemoteCmd) Wait()

Wait waits for the remote command to complete.

type TargettedUi added in v0.3.0 

type TargettedUi struct {
	Target string
	Ui     Ui
}

TargettedUi is a UI that wraps another UI implementation and modifies the output to indicate a specific target. Specifically, all Say output is prefixed with the target name. Message output is not prefixed but is offset by the length of the target so that output is lined up properly with Say output. Machine-readable output has the proper target set.

func (*TargettedUi) Ask added in v0.3.0 

func (u *TargettedUi) Ask(query string) (string, error)

func (*TargettedUi) Error added in v0.3.0 

func (u *TargettedUi) Error(message string)

func (*TargettedUi) Machine added in v0.3.0 

func (u *TargettedUi) Machine(t string, args ...string)

func (*TargettedUi) Message added in v0.3.0 

func (u *TargettedUi) Message(message string)

func (*TargettedUi) Say added in v0.3.0 

func (u *TargettedUi) Say(message string)

type Template 

type Template struct {
	Variables      map[string]string
	Builders       map[string]rawBuilderConfig
	Hooks          map[string][]string
	PostProcessors [][]rawPostProcessorConfig
	Provisioners   []rawProvisionerConfig
}

The Template struct represents a parsed template, parsed into the most completed form it can be without additional processing by the caller.

func ParseTemplate 

func ParseTemplate(data []byte) (t *Template, err error)

ParseTemplate takes a byte slice and parses a Template from it, returning the template and possibly errors while loading the template. The error could potentially be a MultiError, representing multiple errors. Knowing and checking for this can be useful, if you wish to format it in a certain way.

func ParseTemplateFile added in v0.3.0 

func ParseTemplateFile(path string) (*Template, error)

ParseTemplateFile takes the given template file and parses it into a single template.

func (*Template) Build 

func (t *Template) Build(name string, components *ComponentFinder) (b Build, err error)

Build returns a Build for the given name.

If the build does not exist as part of this template, an error is returned.

func (*Template) BuildNames 

func (t *Template) BuildNames() []string

BuildNames returns a slice of the available names of builds that this template represents.

type Ui 

type Ui interface {
	Ask(string) (string, error)
	Say(string)
	Message(string)
	Error(string)
	Machine(string, ...string)
}

The Ui interface handles all communication for Packer with the outside world. This sort of control allows us to strictly control how output is formatted and various levels of output.

type UiColor 

type UiColor uint

Source Files

View all Source files

Directories

Path Synopsis
The plugin package provides the functionality to both expose a Packer plugin binary and to connect to an existing Packer plugin binary.
 The plugin package provides the functionality to both expose a Packer plugin binary and to connect to an existing Packer plugin binary.

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.