imagebuildah

Documentation

Index

• Constants
• func BuildDockerfiles(ctx context.Context, store storage.Store, options BuildOptions, ...) (string, reference.Canonical, error)
• func InitReexec() bool
• func TempDirForURL(dir, prefix, url string) (name string, subdir string, err error)
• type BuildOptions
• type Executor
  • func NewExecutor(store storage.Store, options BuildOptions, mainNode *parser.Node) (*Executor, error)
  • func (b *Executor) Build(ctx context.Context, stages imagebuilder.Stages) (imageID string, ref reference.Canonical, err error)
• type Mount
• type StageExecutor
  • func (s *StageExecutor) Copy(excludes []string, copies ...imagebuilder.Copy) error
  • func (s *StageExecutor) Delete() (err error)
  • func (s *StageExecutor) EnsureContainerPath(path string) error
  • func (s *StageExecutor) Execute(ctx context.Context, stage imagebuilder.Stage, base string) (imgID string, ref reference.Canonical, err error)
  • func (s *StageExecutor) Preserve(path string) error
  • func (s *StageExecutor) Run(run imagebuilder.Run, config docker.Config) error
  • func (s *StageExecutor) UnrecognizedInstruction(step *imagebuilder.Step) error

Constants

const (
	PullIfMissing = buildah.PullIfMissing
	PullAlways    = buildah.PullAlways
	PullNever     = buildah.PullNever

	Gzip         = archive.Gzip
	Bzip2        = archive.Bzip2
	Xz           = archive.Xz
	Uncompressed = archive.Uncompressed
)

Functions

func BuildDockerfiles

func BuildDockerfiles(ctx context.Context, store storage.Store, options BuildOptions, paths ...string) (string, reference.Canonical, error)

BuildDockerfiles parses a set of one or more Dockerfiles (which may be URLs), creates a new Executor, and then runs Prepare/Execute/Commit/Delete over the entire set of instructions.

func InitReexec

func InitReexec() bool

InitReexec is a wrapper for buildah.InitReexec(). It should be called at the start of main(), and if it returns true, main() should return immediately.

func TempDirForURL

func TempDirForURL(dir, prefix, url string) (name string, subdir string, err error)

TempDirForURL checks if the passed-in string looks like a URL. If it is, TempDirForURL creates a temporary directory, arranges for its contents to be the contents of that URL, and returns the temporary directory's path, along with the name of a subdirectory which should be used as the build context (which may be empty or "."). Removal of the temporary directory is the responsibility of the caller. If the string doesn't look like a URL, TempDirForURL returns empty strings and a nil error code.

Types

type BuildOptions

type BuildOptions struct {
	// ContextDirectory is the default source location for COPY and ADD
	// commands.
	ContextDirectory string
	// PullPolicy controls whether or not we pull images.  It should be one
	// of PullIfMissing, PullAlways, or PullNever.
	PullPolicy buildah.PullPolicy
	// Registry is a value which is prepended to the image's name, if it
	// needs to be pulled and the image name alone can not be resolved to a
	// reference to a source image.  No separator is implicitly added.
	Registry string
	// IgnoreUnrecognizedInstructions tells us to just log instructions we
	// don't recognize, and try to keep going.
	IgnoreUnrecognizedInstructions bool
	// Quiet tells us whether or not to announce steps as we go through them.
	Quiet bool
	// Isolation controls how Run() runs things.
	Isolation buildah.Isolation
	// Runtime is the name of the command to run for RUN instructions when
	// Isolation is either IsolationDefault or IsolationOCI.  It should
	// accept the same arguments and flags that runc does.
	Runtime string
	// RuntimeArgs adds global arguments for the runtime.
	RuntimeArgs []string
	// TransientMounts is a list of mounts that won't be kept in the image.
	TransientMounts []Mount
	// Compression specifies the type of compression which is applied to
	// layer blobs.  The default is to not use compression, but
	// archive.Gzip is recommended.
	Compression archive.Compression
	// Arguments which can be interpolated into Dockerfiles
	Args map[string]string
	// Name of the image to write to.
	Output string
	// Additional tags to add to the image that we write, if we know of a
	// way to add them.
	AdditionalTags []string
	// Log is a callback that will print a progress message.  If no value
	// is supplied, the message will be sent to Err (or os.Stderr, if Err
	// is nil) by default.
	Log func(format string, args ...interface{})
	// In is connected to stdin for RUN instructions.
	In io.Reader
	// Out is a place where non-error log messages are sent.
	Out io.Writer
	// Err is a place where error log messages should be sent.
	Err io.Writer
	// SignaturePolicyPath specifies an override location for the signature
	// policy which should be used for verifying the new image as it is
	// being written.  Except in specific circumstances, no value should be
	// specified, indicating that the shared, system-wide default policy
	// should be used.
	SignaturePolicyPath string
	// ReportWriter is an io.Writer which will be used to report the
	// progress of the (possible) pulling of the source image and the
	// writing of the new image.
	ReportWriter io.Writer
	// OutputFormat is the format of the output image's manifest and
	// configuration data.
	// Accepted values are buildah.OCIv1ImageManifest and buildah.Dockerv2ImageManifest.
	OutputFormat string
	// SystemContext holds parameters used for authentication.
	SystemContext *types.SystemContext
	// NamespaceOptions controls how we set up namespaces processes that we
	// might need when handling RUN instructions.
	NamespaceOptions []buildah.NamespaceOption
	// ConfigureNetwork controls whether or not network interfaces and
	// routing are configured for a new network namespace (i.e., when not
	// joining another's namespace and not just using the host's
	// namespace), effectively deciding whether or not the process has a
	// usable network.
	ConfigureNetwork buildah.NetworkConfigurationPolicy
	// CNIPluginPath is the location of CNI plugin helpers, if they should be
	// run from a location other than the default location.
	CNIPluginPath string
	// CNIConfigDir is the location of CNI configuration files, if the files in
	// the default configuration directory shouldn't be used.
	CNIConfigDir string
	// ID mapping options to use if we're setting up our own user namespace
	// when handling RUN instructions.
	IDMappingOptions *buildah.IDMappingOptions
	// AddCapabilities is a list of capabilities to add to the default set when
	// handling RUN instructions.
	AddCapabilities []string
	// DropCapabilities is a list of capabilities to remove from the default set
	// when handling RUN instructions. If a capability appears in both lists, it
	// will be dropped.
	DropCapabilities []string
	CommonBuildOpts  *buildah.CommonBuildOptions
	// DefaultMountsFilePath is the file path holding the mounts to be mounted in "host-path:container-path" format
	DefaultMountsFilePath string
	// IIDFile tells the builder to write the image ID to the specified file
	IIDFile string
	// Squash tells the builder to produce an image with a single layer
	// instead of with possibly more than one layer.
	Squash bool
	// Labels metadata for an image
	Labels []string
	// Annotation metadata for an image
	Annotations []string
	// OnBuild commands to be run by images based on this image
	OnBuild []string
	// Layers tells the builder to create a cache of images for each step in the Dockerfile
	Layers bool
	// NoCache tells the builder to build the image from scratch without checking for a cache.
	// It creates a new set of cached images for the build.
	NoCache bool
	// RemoveIntermediateCtrs tells the builder whether to remove intermediate containers used
	// during the build process. Default is true.
	RemoveIntermediateCtrs bool
	// ForceRmIntermediateCtrs tells the builder to remove all intermediate containers even if
	// the build was unsuccessful.
	ForceRmIntermediateCtrs bool
	// BlobDirectory is a directory which we'll use for caching layer blobs.
	BlobDirectory string
	// Target the targeted FROM in the Dockerfile to build
	Target string
}

BuildOptions can be used to alter how an image is built.

type Executor

type Executor struct {
	// contains filtered or unexported fields
}

Executor is a buildah-based implementation of the imagebuilder.Executor interface. It coordinates the entire build by using one StageExecutors to handle each stage of the build.

func NewExecutor

func NewExecutor(store storage.Store, options BuildOptions, mainNode *parser.Node) (*Executor, error)

NewExecutor creates a new instance of the imagebuilder.Executor interface.

func (*Executor) Build

func (b *Executor) Build(ctx context.Context, stages imagebuilder.Stages) (imageID string, ref reference.Canonical, err error)

Build takes care of the details of running Prepare/Execute/Commit/Delete over each of the one or more parsed Dockerfiles and stages.

type Mount

type Mount specs.Mount

Mount is a mountpoint for the build container.

type StageExecutor

type StageExecutor struct {
	// contains filtered or unexported fields
}

StageExecutor bundles up what we need to know when executing one stage of a (possibly multi-stage) build. Each stage may need to produce an image to be used as the base in a later stage (with the last stage's image being the end product of the build), and it may need to leave its working container in place so that the container's root filesystem's contents can be used as the source for a COPY instruction in a later stage. Each stage has its own base image, so it starts with its own configuration and set of volumes. If we're naming the result of the build, only the last stage will apply that name to the image that it produces.

func (*StageExecutor) Copy

func (s *StageExecutor) Copy(excludes []string, copies ...imagebuilder.Copy) error

Copy copies data into the working tree. The "Download" field is how imagebuilder tells us the instruction was "ADD" and not "COPY".

func (*StageExecutor) Delete

func (s *StageExecutor) Delete() (err error)

Delete deletes the stage's working container, if we have one.

func (*StageExecutor) EnsureContainerPath

func (s *StageExecutor) EnsureContainerPath(path string) error

func (*StageExecutor) Execute

func (s *StageExecutor) Execute(ctx context.Context, stage imagebuilder.Stage, base string) (imgID string, ref reference.Canonical, err error)

Execute runs each of the steps in the stage's parsed tree, in turn.

func (*StageExecutor) Preserve

func (s *StageExecutor) Preserve(path string) error

Preserve informs the stage executor that from this point on, it needs to ensure that only COPY and ADD instructions can modify the contents of this directory or anything below it. The StageExecutor handles this by caching the contents of directories which have been marked this way before executing a RUN instruction, invalidating that cache when an ADD or COPY instruction sets any location under the directory as the destination, and using the cache to reset the contents of the directory tree after processing each RUN instruction. It would be simpler if we could just mark the directory as a read-only bind mount of itself during Run(), but the directory is expected to be remain writeable while the RUN instruction is being handled, even if any changes made within the directory are ultimately discarded.

func (*StageExecutor) Run

func (s *StageExecutor) Run(run imagebuilder.Run, config docker.Config) error

Run executes a RUN instruction using the stage's current working container as a root directory.

func (*StageExecutor) UnrecognizedInstruction

func (s *StageExecutor) UnrecognizedInstruction(step *imagebuilder.Step) error

UnrecognizedInstruction is called when we encounter an instruction that the imagebuilder parser didn't understand.