commonsteps

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Jan 20, 2025 License: MPL-2.0, MIT Imports: 35 Imported by: 127

Documentation

Overview

The commonsteps package contains the multistep runner that comprises the main architectural convention of Packer builder plugins. It enables builders to respect global Packer flags like "on-error" and "debug". It also contains a selection of convenience "multistep" steps that perform globally relevant tasks that many or most builders will want to implement -- for example, launching Packer's internal HTTP server for serving files to the instance.

It also provides step_provision, which contains the hooks necessary for allowing provisioners to run inside your builder.

While it is possible to create a simple builder without using the multistep runner or step_provision, your builder will lack core Packer functionality.

Index

Constants

View Source 
const (
	NetworkProtocolTCP       string = "tcp"
	NetworkProcotolTCP4             = "tcp4"
	NetworkProtocolTCP6             = "tcp6"
	NetworkProtocolUnix             = "unix"
	NetworkProcotlUnixPacket        = "unixpacket"
)

These are the different valid network procotol values for "http_network_protocol"

View Source 
const HttpAddrNotImplemented = "ERR_HTTP_ADDR_NOT_IMPLEMENTED_BY_BUILDER"
View Source 
const HttpIPNotImplemented = "ERR_HTTP_IP_NOT_IMPLEMENTED_BY_BUILDER"
View Source 
const HttpPortNotImplemented = "ERR_HTTP_PORT_NOT_IMPLEMENTED_BY_BUILDER"

Variables

This section is empty.

Functions

func MultistepDebugFn 

func MultistepDebugFn(ui packersdk.Ui) multistep.DebugPauseFn

MultistepDebugFn will return a proper multistep.DebugPauseFn to use for debugging if you're using multistep in your builder.

func NewRunner 

func NewRunner(steps []multistep.Step, config common.PackerConfig, ui packersdk.Ui) multistep.Runner

NewRunner returns a multistep.Runner that runs steps augmented with support for -debug and -on-error command line arguments.

func NewRunnerWithPauseFn 

func NewRunnerWithPauseFn(steps []multistep.Step, config common.PackerConfig, ui packersdk.Ui, state multistep.StateBag) multistep.Runner

NewRunnerWithPauseFn returns a multistep.Runner that runs steps augmented with support for -debug and -on-error command line arguments. With -debug it puts the multistep.DebugPauseFn that will pause execution between steps into the state under the key "pauseFn".

func PopulateProvisionHookData 

func PopulateProvisionHookData(state multistep.StateBag) map[string]interface{}

Types

type CDConfig 

type CDConfig struct {
	// A list of files to place onto a CD that is attached when the VM is
	// booted. This can include either files or directories; any directories
	// will be copied onto the CD recursively, preserving directory structure
	// hierarchy. Symlinks will have the link's target copied into the directory
	// tree on the CD where the symlink was. File globbing is allowed.
	//
	// Usage example (JSON):
	//
	// “`json
	// "cd_files": ["./somedirectory/meta-data", "./somedirectory/user-data"],
	// "cd_label": "cidata",
	// “`
	//
	// Usage example (HCL):
	//
	// “`hcl
	// cd_files = ["./somedirectory/meta-data", "./somedirectory/user-data"]
	// cd_label = "cidata"
	// “`
	//
	// The above will create a CD with two files, user-data and meta-data in the
	// CD root. This specific example is how you would create a CD that can be
	// used for an Ubuntu 20.04 autoinstall.
	//
	// Since globbing is also supported,
	//
	// “`hcl
	// cd_files = ["./somedirectory/*"]
	// cd_label = "cidata"
	// “`
	//
	// Would also be an acceptable way to define the above cd. The difference
	// between providing the directory with or without the glob is whether the
	// directory itself or its contents will be at the CD root.
	//
	// Use of this option assumes that you have a command line tool installed
	// that can handle the iso creation. Packer will use one of the following
	// tools:
	//
	//   * xorriso
	//   * mkisofs
	//   * hdiutil (normally found in macOS)
	//   * oscdimg (normally found in Windows as part of the Windows ADK)
	CDFiles []string `mapstructure:"cd_files"`
	// Key/Values to add to the CD. The keys represent the paths, and the values
	// contents. It can be used alongside `cd_files`, which is useful to add large
	// files without loading them into memory. If any paths are specified by both,
	// the contents in `cd_content` will take precedence.
	//
	// Usage example (HCL):
	//
	// “`hcl
	// cd_files = ["vendor-data"]
	// cd_content = {
	//   "meta-data" = jsonencode(local.instance_data)
	//   "user-data" = templatefile("user-data", { packages = ["nginx"] })
	// }
	// cd_label = "cidata"
	// “`
	CDContent map[string]string `mapstructure:"cd_content"`
	CDLabel   string            `mapstructure:"cd_label"`
}

An iso (CD) containing custom files can be made available for your build.

By default, no extra CD will be attached. All files listed in this setting get placed into the root directory of the CD and the CD is attached as the second CD device.

This config exists to work around modern operating systems that have no way to mount floppy disks, which was our previous go-to for adding files at boot time.

func (*CDConfig) Prepare 

func (c *CDConfig) Prepare(ctx *interpolate.Context) []error

type FloppyConfig 

type FloppyConfig struct {
	// A list of files to place onto a floppy disk that is attached when the VM
	// is booted. Currently, no support exists for creating sub-directories on
	// the floppy. Wildcard characters (\\*, ?, and \[\]) are allowed. Directory
	// names are also allowed, which will add all the files found in the
	// directory to the floppy.
	FloppyFiles []string `mapstructure:"floppy_files"`
	// A list of directories to place onto the floppy disk recursively. This is
	// similar to the `floppy_files` option except that the directory structure
	// is preserved. This is useful for when your floppy disk includes drivers
	// or if you just want to organize it's contents as a hierarchy. Wildcard
	// characters (\\*, ?, and \[\]) are allowed. The maximum summary size of
	// all files in the listed directories are the same as in `floppy_files`.
	FloppyDirectories []string `mapstructure:"floppy_dirs"`
	// Key/Values to add to the floppy disk. The keys represent the paths, and
	// the values contents. It can be used alongside `floppy_files` or
	// `floppy_dirs`, which is useful to add large files without loading them
	// into memory. If any paths are specified by both, the contents in
	// `floppy_content` will take precedence.
	//
	// Usage example (HCL):
	//
	// “`hcl
	// floppy_files = ["vendor-data"]
	// floppy_content = {
	//   "meta-data" = jsonencode(local.instance_data)
	//   "user-data" = templatefile("user-data", { packages = ["nginx"] })
	// }
	// floppy_label = "cidata"
	// “`
	FloppyContent map[string]string `mapstructure:"floppy_content"`
	FloppyLabel   string            `mapstructure:"floppy_label"`
}

A floppy can be made available for your build. This is most useful for unattended Windows installs, which look for an Autounattend.xml file on removable media. By default, no floppy will be attached. All files listed in this setting get placed into the root directory of the floppy and the floppy is attached as the first floppy device. The summary size of the listed files must not exceed 1.44 MB. The supported ways to move large files into the OS are using `http_directory` or [the file provisioner](/packer/docs/provisioners/file).

func (*FloppyConfig) Prepare 

func (c *FloppyConfig) Prepare(ctx *interpolate.Context) []error

type HTTPConfig 

type HTTPConfig struct {
	// Path to a directory to serve using an HTTP server. The files in this
	// directory will be available over HTTP that will be requestable from the
	// virtual machine. This is useful for hosting kickstart files and so on.
	// By default this is an empty string, which means no HTTP server will be
	// started. The address and port of the HTTP server will be available as
	// variables in `boot_command`. This is covered in more detail below.
	HTTPDir string `mapstructure:"http_directory"`
	// Key/Values to serve using an HTTP server. `http_content` works like and
	// conflicts with `http_directory`. The keys represent the paths and the
	// values contents, the keys must start with a slash, ex: `/path/to/file`.
	// `http_content` is useful for hosting kickstart files and so on. By
	// default this is empty, which means no HTTP server will be started. The
	// address and port of the HTTP server will be available as variables in
	// `boot_command`. This is covered in more detail below.
	// Example:
	// “`hcl
	//   http_content = {
	//     "/a/b"     = file("http/b")
	//     "/foo/bar" = templatefile("${path.root}/preseed.cfg", { packages = ["nginx"] })
	//   }
	// “`
	HTTPContent map[string]string `mapstructure:"http_content"`
	// These are the minimum and maximum port to use for the HTTP server
	// started to serve the `http_directory`. Because Packer often runs in
	// parallel, Packer will choose a randomly available port in this range to
	// run the HTTP server. If you want to force the HTTP server to be on one
	// port, make this minimum and maximum port the same. By default the values
	// are `8000` and `9000`, respectively.
	HTTPPortMin int `mapstructure:"http_port_min"`
	HTTPPortMax int `mapstructure:"http_port_max"`
	// This is the bind address for the HTTP server. Defaults to 0.0.0.0 so that
	// it will work with any network interface.
	HTTPAddress string `mapstructure:"http_bind_address"`
	// This is the bind interface for the HTTP server. Defaults to the first
	// interface with a non-loopback address. Either `http_bind_address` or
	// `http_interface` can be specified.
	HTTPInterface string `mapstructure:"http_interface" undocumented:"true"`
	// Defines the HTTP Network protocol. Valid options are `tcp`, `tcp4`, `tcp6`,
	// `unix`, and `unixpacket`. This value defaults to `tcp`.
	HTTPNetworkProtocol string `mapstructure:"http_network_protocol"`
}

Packer will create an http server serving `http_directory` when it is set, a random free port will be selected and the architecture of the directory referenced will be available in your builder.

Example usage from a builder:

``` wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg ```

func (*HTTPConfig) Prepare 

func (c *HTTPConfig) Prepare(ctx *interpolate.Context) []error

type ISOConfig 

type ISOConfig struct {
	// The checksum for the ISO file or virtual hard drive file. The type of
	// the checksum is specified within the checksum field as a prefix, ex:
	// "md5:{$checksum}". The type of the checksum can also be omitted and
	// Packer will try to infer it based on string length. Valid values are
	// "none", "{$checksum}", "md5:{$checksum}", "sha1:{$checksum}",
	// "sha256:{$checksum}", "sha512:{$checksum}" or "file:{$path}". Here is a
	// list of valid checksum values:
	//  * md5:090992ba9fd140077b0661cb75f7ce13
	//  * 090992ba9fd140077b0661cb75f7ce13
	//  * sha1:ebfb681885ddf1234c18094a45bbeafd91467911
	//  * ebfb681885ddf1234c18094a45bbeafd91467911
	//  * sha256:ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
	//  * ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
	//  * file:http://releases.ubuntu.com/20.04/SHA256SUMS
	//  * file:file://./local/path/file.sum
	//  * file:./local/path/file.sum
	//  * none
	// Although the checksum will not be verified when it is set to "none",
	// this is not recommended since these files can be very large and
	// corruption does happen from time to time.
	ISOChecksum string `mapstructure:"iso_checksum" required:"true"`
	// A URL to the ISO containing the installation image or virtual hard drive
	// (VHD or VHDX) file to clone.
	RawSingleISOUrl string `mapstructure:"iso_url" required:"true"`
	// Multiple URLs for the ISO to download. Packer will try these in order.
	// If anything goes wrong attempting to download or while downloading a
	// single URL, it will move on to the next. All URLs must point to the same
	// file (same checksum). By default this is empty and `iso_url` is used.
	// Only one of `iso_url` or `iso_urls` can be specified.
	ISOUrls []string `mapstructure:"iso_urls"`
	// The path where the iso should be saved after download. By default will
	// go in the packer cache, with a hash of the original filename and
	// checksum as its name.
	TargetPath string `mapstructure:"iso_target_path"`
	// The extension of the iso file after download. This defaults to `iso`.
	TargetExtension string `mapstructure:"iso_target_extension"`
}

By default, Packer will symlink, download or copy image files to the Packer cache into a "`hash($iso_url+$iso_checksum).$iso_target_extension`" file. Packer uses hashicorp/go-getter(https://github.com/hashicorp/go-getter) in file mode in order to perform a download.

go-getter supports the following protocols:

* Local files * Git * Mercurial * HTTP * Amazon S3

Examples: go-getter can guess the checksum type based on `iso_checksum` length, and it is also possible to specify the checksum type.

In JSON:

```json 

"iso_checksum": "946a6077af6f5f95a51f82fdc44051c7aa19f9cfc5f737954845a6050543d7c2",
"iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

```json 

"iso_checksum": "file:ubuntu.org/..../ubuntu-14.04.1-server-amd64.iso.sum",
"iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

```json 

"iso_checksum": "file://./shasums.txt",
"iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

```json 

"iso_checksum": "file:./shasums.txt",
"iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

In HCL2:

```hcl 

iso_checksum = "946a6077af6f5f95a51f82fdc44051c7aa19f9cfc5f737954845a6050543d7c2"
iso_url = "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

```hcl 

iso_checksum = "file:ubuntu.org/..../ubuntu-14.04.1-server-amd64.iso.sum"
iso_url = "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

```hcl 

iso_checksum = "file://./shasums.txt"
iso_url = "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

```hcl 

iso_checksum = "file:./shasums.txt",
iso_url = "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"

```

func (*ISOConfig) Prepare 

func (c *ISOConfig) Prepare(*interpolate.Context) (warnings []string, errs []error)

type MapServer added in v0.1.1 

type MapServer map[string]string

func (MapServer) ServeHTTP added in v0.1.1 

func (s MapServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

type StepCleanupTempKeys 

type StepCleanupTempKeys struct {
	Comm *communicator.Config
}

func (*StepCleanupTempKeys) Cleanup 

func (s *StepCleanupTempKeys) Cleanup(state multistep.StateBag)

func (*StepCleanupTempKeys) Run 

func (s *StepCleanupTempKeys) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction

type StepCreateCD 

type StepCreateCD struct {
	// Files can be either files or directories. Any files provided here will
	// be written to the root of the CD. Directories will be written to the
	// root of the CD as well, but will retain their subdirectory structure.
	Files   []string
	Content map[string]string
	Label   string

	CDPath string
	// contains filtered or unexported fields
}

StepCreateCD will create a CD disk with the given files.

func (*StepCreateCD) AddContent added in v0.2.3 

func (s *StepCreateCD) AddContent(dst, path, content string) error

func (*StepCreateCD) AddFile 

func (s *StepCreateCD) AddFile(dst, src string) error

func (*StepCreateCD) Cleanup 

func (s *StepCreateCD) Cleanup(multistep.StateBag)

func (*StepCreateCD) Run 

func (s *StepCreateCD) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction

type StepCreateFloppy 

type StepCreateFloppy struct {
	Files       []string
	Directories []string
	Content     map[string]string
	Label       string

	FilesAdded map[string]bool
	// contains filtered or unexported fields
}

StepCreateFloppy will create a floppy disk with the given files.

func (*StepCreateFloppy) Add 

func (s *StepCreateFloppy) Add(dircache directoryCache, src string) error

func (*StepCreateFloppy) AddContent added in v0.2.7 

func (s *StepCreateFloppy) AddContent(dircache directoryCache, path, content string) error

func (*StepCreateFloppy) Cleanup 

func (s *StepCreateFloppy) Cleanup(multistep.StateBag)

func (*StepCreateFloppy) Run 

func (s *StepCreateFloppy) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction

type StepDownload 

type StepDownload struct {
	// The checksum and the type of the checksum for the download
	Checksum string

	// A short description of the type of download being done. Example:
	// "ISO" or "Guest Additions"
	Description string

	// The name of the key where the final path of the ISO will be put
	// into the state.
	ResultKey string

	// The path where the result should go, otherwise it goes to the
	// cache directory.
	TargetPath string

	// A list of URLs to attempt to download this thing.
	Url []string

	// Extension is the extension to force for the file that is downloaded.
	// Some systems require a certain extension. If this isn't set, the
	// extension on the URL is used. Otherwise, this will be forced
	// on the downloaded file for every URL.
	Extension string
}

StepDownload downloads a remote file using the download client within this package. This step handles setting up the download configuration, progress reporting, interrupt handling, etc.

Uses: 

cache packer.Cache
ui    packersdk.Ui

func (*StepDownload) Cleanup 

func (s *StepDownload) Cleanup(multistep.StateBag)

func (*StepDownload) Run 

func (s *StepDownload) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction

func (*StepDownload) UseSourceToFindCacheTarget 

func (s *StepDownload) UseSourceToFindCacheTarget(source string) (*url.URL, string, error)

type StepHTTPServer 

type StepHTTPServer struct {
	HTTPDir             string
	HTTPContent         map[string]string
	HTTPPortMin         int
	HTTPPortMax         int
	HTTPAddress         string
	HTTPNetworkProcotol string
	// contains filtered or unexported fields
}

This step creates and runs the HTTP server that is serving files from the directory specified by the 'http_directory` configuration parameter in the template.

Uses: 

ui     packersdk.Ui

Produces: 

http_port int - The port the HTTP server started on.

func HTTPServerFromHTTPConfig added in v0.1.1 

func HTTPServerFromHTTPConfig(cfg *HTTPConfig) *StepHTTPServer

func (*StepHTTPServer) Cleanup 

func (s *StepHTTPServer) Cleanup(state multistep.StateBag)

func (*StepHTTPServer) Handler added in v0.1.1 

func (s *StepHTTPServer) Handler() http.Handler

func (*StepHTTPServer) Run 

func (s *StepHTTPServer) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction

type StepOutputDir 

type StepOutputDir struct {
	Force bool
	Path  string
	// contains filtered or unexported fields
}

StepOutputDir sets up the output directory by creating it if it does not exist, deleting it if it does exist and we're forcing, and cleaning it up when we're done with it.

func (*StepOutputDir) Cleanup 

func (s *StepOutputDir) Cleanup(state multistep.StateBag)

func (*StepOutputDir) Run 

func (s *StepOutputDir) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction

type StepProvision 

type StepProvision struct {
	Comm packersdk.Communicator
}

func (*StepProvision) Cleanup 

func (s *StepProvision) Cleanup(state multistep.StateBag)

func (*StepProvision) Run 

func (s *StepProvision) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction

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.