buildah

package module
v0.0.0-...-6284537 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2017 License: Apache-2.0 Imports: 44 Imported by: 0

README

buildah - a tool which facilitates building OCI container images

Go Report Card Travis

Note: this package is in alpha, but is close to being feature-complete.

The buildah package provides a command line tool which can be used to

  • create a working container, either from scratch or using an image as a starting point
  • create an image, either from a working container or via the instructions in a Dockerfile
  • images can be built in either the OCI image format or the traditional upstream docker image format
  • mount a working container's root filesystem for manipulation
  • unmount a working container's root filesystem
  • use the updated contents of a container's root filesystem as a filesystem layer to create a new image
  • delete a working container or an image

Installation notes

Prior to installing buildah, install the following packages on your linux distro:

  • make
  • golang (Requires version 1.8.1 or higher.)
  • bats
  • btrfs-progs-devel
  • device-mapper-devel
  • gpgme-devel
  • libassuan-devel
  • git
  • bzip2
  • go-md2man
  • runc
  • skopeo-containers

In Fedora, you can use this command:

 dnf -y install \
    make \
    golang \
    bats \
    btrfs-progs-devel \
    device-mapper-devel \
    gpgme-devel \
    libassuan-devel \
    git \
    bzip2 \
    go-md2man \
    runc \
    skopeo-containers

Then to install buildah follow the steps in this example:

  mkdir ~/buildah
  cd ~/buildah
  export GOPATH=`pwd` 
  git clone https://github.com/projectatomic/buildah ./src/github.com/projectatomic/buildah 
  cd ./src/github.com/projectatomic/buildah 
  make 
  make install
  buildah --help

buildah uses runc to run commands when buildah run is used, or when buildah build-using-dockerfile encounters a RUN instruction, so you'll also need to build and install a compatible version of runc for buildah to call for those cases.

Commands

Command Description
buildah-add(1) Add the contents of a file, URL, or a directory to the container.
buildah-bud(1) Build an image using instructions from Dockerfiles.
buildah-commit(1) Create an image from a working container.
buildah-config(1) Update image configuration settings.
buildah-containers(1) List the working containers and their base images.
buildah-copy(1) Copies the contents of a file, URL, or directory into a container's working directory.
buildah-from(1) Creates a new working container, either from scratch or using a specified image as a starting point.
buildah-images(1) List images in local storage.
buildah-inspect(1) Inspects the configuration of a container or image.
buildah-mount(1) Mount the working container's root filesystem.
buildah-push(1) Copies an image from local storage.
buildah-rm(1) Removes one or more working containers.
buildah-rmi(1) Removes one or more images.
buildah-run(1) Run a command inside of the container.
buildah-tag(1) Add an additional name to a local image.
buildah-umount(1) Unmount a working container's root file system.

Future goals include:

  • more CI tests
  • additional CLI commands (?)

Documentation

Index

Constants

View Source 
const (
	// Package is the name of this package, used in help output and to
	// identify working containers.
	Package = "buildah"
	// Version for the Package
	Version = "0.1"
)
View Source 
const (
	// PullIfMissing is one of the values that BuilderOptions.PullPolicy
	// can take, signalling that the source image should be pulled from a
	// registry if a local copy of it is not already present.
	PullIfMissing = iota
	// PullAlways is one of the values that BuilderOptions.PullPolicy can
	// take, signalling that a fresh, possibly updated, copy of the image
	// should be pulled from a registry before the build proceeds.
	PullAlways
	// PullNever is one of the values that BuilderOptions.PullPolicy can
	// take, signalling that the source image should not be pulled from a
	// registry if a local copy of it is not already present.
	PullNever
)
View Source 
const (
	// OCIv1ImageManifest is the MIME type of an OCIv1 image manifest,
	// suitable for specifying as a value of the PreferredManifestType
	// member of a CommitOptions structure.  It is also the default.
	OCIv1ImageManifest = v1.MediaTypeImageManifest
	// Dockerv2ImageManifest is the MIME type of a Docker v2s2 image
	// manifest, suitable for specifying as a value of the
	// PreferredManifestType member of a CommitOptions structure.
	Dockerv2ImageManifest = docker.V2S2MediaTypeManifest
)
View Source 
const (
	// DefaultWorkingDir is used if none was specified.
	DefaultWorkingDir = "/"
	// DefaultRuntime is the default command to use to run the container.
	DefaultRuntime = "runc"
)
View Source 
const (
	// DefaultTerminal indicates that this Run invocation should be
	// connected to a pseudoterminal if we're connected to a terminal.
	DefaultTerminal = iota
	// WithoutTerminal indicates that this Run invocation should NOT be
	// connected to a pseudoterminal.
	WithoutTerminal
	// WithTerminal indicates that this Run invocation should be connected
	// to a pseudoterminal.
	WithTerminal
)
View Source 
const (
	// BaseImageFakeName is the "name" of a source image which we interpret
	// as "no image".
	BaseImageFakeName = imagebuilder.NoBaseImageSpecifier
)

Variables

This section is empty.

Functions

func InitReexec 

func InitReexec() bool

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

func Push 

func Push(image string, dest types.ImageReference, options PushOptions) error

Push copies the contents of the image to a new location.

Types

type Builder 

type Builder struct {

	// Type is used to help identify a build container's metadata.  It
	// should not be modified.
	Type string `json:"type"`
	// FromImage is the name of the source image which was used to create
	// the container, if one was used.  It should not be modified.
	FromImage string `json:"image,omitempty"`
	// FromImageID is the ID of the source image which was used to create
	// the container, if one was used.  It should not be modified.
	FromImageID string `json:"image-id"`
	// Config is the source image's configuration.  It should not be
	// modified.
	Config []byte `json:"config,omitempty"`
	// Manifest is the source image's manifest.  It should not be modified.
	Manifest []byte `json:"manifest,omitempty"`

	// Container is the name of the build container.  It should not be modified.
	Container string `json:"container-name,omitempty"`
	// ContainerID is the ID of the build container.  It should not be modified.
	ContainerID string `json:"container-id,omitempty"`
	// MountPoint is the last location where the container's root
	// filesystem was mounted.  It should not be modified.
	MountPoint string `json:"mountpoint,omitempty"`

	// ImageAnnotations is a set of key-value pairs which is stored in the
	// image's manifest.
	ImageAnnotations map[string]string `json:"annotations,omitempty"`
	// ImageCreatedBy is a description of how this container was built.
	ImageCreatedBy string `json:"created-by,omitempty"`

	// Image metadata and runtime settings, in multiple formats.
	OCIv1  v1.Image       `json:"ociv1,omitempty"`
	Docker docker.V2Image `json:"docker,omitempty"`
	// contains filtered or unexported fields
}

Builder objects are used to represent containers which are being used to build images. They also carry potential updates which will be applied to the image's configuration when the container's contents are used to build an image.

func ImportBuilder 

func ImportBuilder(store storage.Store, options ImportOptions) (*Builder, error)

ImportBuilder creates a new build configuration using an already-present container.

func ImportBuilderFromImage 

func ImportBuilderFromImage(store storage.Store, options ImportFromImageOptions) (*Builder, error)

ImportBuilderFromImage creates a new builder configuration using an image. The returned object can be modified and examined, but it can not be saved or committed because it is not associated with a working container.

func NewBuilder 

func NewBuilder(store storage.Store, options BuilderOptions) (*Builder, error)

NewBuilder creates a new build container.

func OpenAllBuilders 

func OpenAllBuilders(store storage.Store) (builders []*Builder, err error)

OpenAllBuilders loads all containers which have a state file that we use in their data directory, typically so that they can be listed.

func OpenBuilder 

func OpenBuilder(store storage.Store, container string) (*Builder, error)

OpenBuilder loads information about a build container given its name or ID.

func OpenBuilderByPath 

func OpenBuilderByPath(store storage.Store, path string) (*Builder, error)

OpenBuilderByPath loads information about a build container given a path to the container's root filesystem

func (*Builder) Add 

func (b *Builder) Add(destination string, extract bool, source ...string) error

Add copies the contents of the specified sources into the container's root filesystem, optionally extracting contents of local files that look like non-empty archives.

func (*Builder) AddVolume 

func (b *Builder) AddVolume(v string)

AddVolume adds a location to the image's list of locations which should be mounted from outside of the container when a container based on an image built from this container is run.

func (*Builder) Annotations 

func (b *Builder) Annotations() map[string]string

Annotations returns a set of key-value pairs from the image's manifest.

func (*Builder) Architecture 

func (b *Builder) Architecture() string

Architecture returns a name of the architecture on which the container, or a container built using an image built from this container, is intended to be run.

func (*Builder) ClearAnnotations 

func (b *Builder) ClearAnnotations()

ClearAnnotations removes all keys and their values from the image's manifest.

func (*Builder) ClearEnv 

func (b *Builder) ClearEnv()

ClearEnv removes all values from the set of environment strings which should be set when running commands in this container, or in a container built using an image built from this container.

func (*Builder) ClearLabels 

func (b *Builder) ClearLabels()

ClearLabels removes all keys and their values from the image's runtime configuration.

func (*Builder) ClearPorts 

func (b *Builder) ClearPorts()

ClearPorts empties the set of ports which should be exposed when a container based on an image built from this container is run.

func (*Builder) ClearVolumes 

func (b *Builder) ClearVolumes()

ClearVolumes removes all locations from the image's list of locations which should be mounted from outside of the container when a container based on an image built from this container is run.

func (*Builder) Cmd 

func (b *Builder) Cmd() []string

Cmd returns the default command, or command parameters if an Entrypoint is set, to use when running a container built from an image built from this container.

func (*Builder) Commit 

func (b *Builder) Commit(dest types.ImageReference, options CommitOptions) error

Commit writes the contents of the container, along with its updated configuration, to a new image in the specified location, and if we know how, add any additional tags that were specified.

func (*Builder) CreatedBy 

func (b *Builder) CreatedBy() string

CreatedBy returns a description of how this image was built.

func (*Builder) Delete 

func (b *Builder) Delete() error

Delete removes the working container. The buildah.Builder object should not be used after this method is called.

func (*Builder) Domainname 

func (b *Builder) Domainname() string

Domainname returns the domainname which will be set in the container and in containers built using images built from the container.

func (*Builder) Entrypoint 

func (b *Builder) Entrypoint() []string

Entrypoint returns the command to be run for containers built from images built from this container.

func (*Builder) Env 

func (b *Builder) Env() []string

Env returns a list of key-value pairs to be set when running commands in the container, or in a container built using an image built from this container.

func (*Builder) Hostname 

func (b *Builder) Hostname() string

Hostname returns the hostname which will be set in the container and in containers built using images built from the container.

func (*Builder) Labels 

func (b *Builder) Labels() map[string]string

Labels returns a set of key-value pairs from the image's runtime configuration.

func (*Builder) Maintainer 

func (b *Builder) Maintainer() string

Maintainer returns contact information for the person who built the image.

func (*Builder) Mount 

func (b *Builder) Mount(label string) (string, error)

Mount mounts a container's root filesystem in a location which can be accessed from the host, and returns the location.

func (*Builder) OS 

func (b *Builder) OS() string

OS returns a name of the OS on which the container, or a container built using an image built from this container, is intended to be run.

func (*Builder) Ports 

func (b *Builder) Ports() []string

Ports returns the set of ports which should be exposed when a container based on an image built from this container is run.

func (*Builder) RemoveVolume 

func (b *Builder) RemoveVolume(v string)

RemoveVolume removes a location from the list of locations which should be mounted from outside of the container when a container based on an image built from this container is run.

func (*Builder) Run 

func (b *Builder) Run(command []string, options RunOptions) error

Run runs the specified command in the container's root filesystem.

func (*Builder) Save 

func (b *Builder) Save() error

Save saves the builder's current state to the build container's metadata. This should not need to be called directly, as other methods of the Builder object take care of saving their state.

func (*Builder) SetAnnotation 

func (b *Builder) SetAnnotation(key, value string)

SetAnnotation adds or overwrites a key's value from the image's manifest. Note: this setting is not present in the Docker v2 image format, so it is discarded when writing images using Docker v2 formats.

func (*Builder) SetArchitecture 

func (b *Builder) SetArchitecture(arch string)

SetArchitecture sets the name of the architecture on which the container, or a container built using an image built from this container, is intended to be run.

func (*Builder) SetCmd 

func (b *Builder) SetCmd(cmd []string)

SetCmd sets the default command, or command parameters if an Entrypoint is set, to use when running a container built from an image built from this container.

func (*Builder) SetCreatedBy 

func (b *Builder) SetCreatedBy(how string)

SetCreatedBy sets the description of how this image was built.

func (*Builder) SetDomainname 

func (b *Builder) SetDomainname(name string)

SetDomainname sets the domainname which will be set in the container and in containers built using images built from the container. Note: this setting is not present in the OCIv1 image format, so it is discarded when writing images using OCIv1 formats.

func (*Builder) SetEntrypoint 

func (b *Builder) SetEntrypoint(ep []string)

SetEntrypoint sets the command to be run for in containers built from images built from this container.

func (*Builder) SetEnv 

func (b *Builder) SetEnv(k string, v string)

SetEnv adds or overwrites a value to the set of environment strings which should be set when running commands in the container, or in a container built using an image built from this container.

func (*Builder) SetHostname 

func (b *Builder) SetHostname(name string)

SetHostname sets the hostname which will be set in the container and in containers built using images built from the container. Note: this setting is not present in the OCIv1 image format, so it is discarded when writing images using OCIv1 formats.

func (*Builder) SetLabel 

func (b *Builder) SetLabel(k string, v string)

SetLabel adds or overwrites a key's value from the image's runtime configuration.

func (*Builder) SetMaintainer 

func (b *Builder) SetMaintainer(who string)

SetMaintainer sets contact information for the person who built the image.

func (*Builder) SetOS 

func (b *Builder) SetOS(os string)

SetOS sets the name of the OS on which the container, or a container built using an image built from this container, is intended to be run.

func (*Builder) SetPort 

func (b *Builder) SetPort(p string)

SetPort adds or overwrites an exported port in the set of ports which should be exposed when a container based on an image built from this container is run.

func (*Builder) SetUser 

func (b *Builder) SetUser(spec string)

SetUser sets information about the user as whom the container, or a container built using an image built from this container, should be run. Acceptable forms are a user name or ID, optionally followed by a colon and a group name or ID.

func (*Builder) SetWorkDir 

func (b *Builder) SetWorkDir(there string)

SetWorkDir sets the location of the default working directory for running commands in the container, or in a container built using an image built from this container.

func (*Builder) Unmount 

func (b *Builder) Unmount() error

Unmount unmounts a build container.

func (*Builder) UnsetAnnotation 

func (b *Builder) UnsetAnnotation(key string)

UnsetAnnotation removes a key and its value from the image's manifest, if it's present.

func (*Builder) UnsetEnv 

func (b *Builder) UnsetEnv(k string)

UnsetEnv removes a value from the set of environment strings which should be set when running commands in this container, or in a container built using an image built from this container.

func (*Builder) UnsetLabel 

func (b *Builder) UnsetLabel(k string)

UnsetLabel removes a key and its value from the image's runtime configuration, if it's present.

func (*Builder) UnsetPort 

func (b *Builder) UnsetPort(p string)

UnsetPort removes an exposed port from the set of ports which should be exposed when a container based on an image built from this container is run.

func (*Builder) User 

func (b *Builder) User() string

User returns information about the user as whom the container, or a container built using an image built from this container, should be run.

func (*Builder) Volumes 

func (b *Builder) Volumes() []string

Volumes returns a list of filesystem locations which should be mounted from outside of the container when a container built from an image built from this container is run.

func (*Builder) WorkDir 

func (b *Builder) WorkDir() string

WorkDir returns the default working directory for running commands in the container, or in a container built using an image built from this container.

type BuilderOptions 

type BuilderOptions struct {
	// FromImage is the name of the image which should be used as the
	// starting point for the container.  It can be set to an empty value
	// or "scratch" to indicate that the container should not be based on
	// an image.
	FromImage string
	// Container is a desired name for the build container.
	Container string
	// PullPolicy decides whether or not we should pull the image that
	// we're using as a base image.  It should be PullIfMissing,
	// PullAlways, or PullNever.
	PullPolicy int
	// 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.
	Registry string
	// Mount signals to NewBuilder() that the container should be mounted
	// immediately.
	Mount bool
	// 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 log the reading
	// of the source image from a registry, if we end up pulling the image.
	ReportWriter io.Writer
}

BuilderOptions are used to initialize a new Builder.

type CommitOptions 

type CommitOptions struct {
	// PreferredManifestType is the preferred type of image manifest.  The
	// image configuration format will be of a compatible type.
	PreferredManifestType string
	// 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
	// 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
	// AdditionalTags is a list of additional names to add to the image, if
	// the transport to which we're writing the image gives us a way to add
	// them.
	AdditionalTags []string
	// ReportWriter is an io.Writer which will be used to log the writing
	// of the new image.
	ReportWriter io.Writer
	// HistoryTimestamp is the timestamp used when creating new items in the
	// image's history.  If unset, the current time will be used.
	HistoryTimestamp *time.Time
}

CommitOptions can be used to alter how an image is committed.

type ImportFromImageOptions 

type ImportFromImageOptions struct {
	// Image is the name or ID of the image we'd like to examine.
	Image string
	// 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
}

ImportFromImageOptions are used to initialize a Builder from an image.

type ImportOptions 

type ImportOptions struct {
	// Container is the name of the build container.
	Container string
	// 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
}

ImportOptions are used to initialize a Builder from an existing container which was created elsewhere.

type PushOptions 

type PushOptions struct {
	// 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
	// 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 log the writing
	// of the new image.
	ReportWriter io.Writer
	// Store is the local storage store which holds the source image.
	Store storage.Store
}

PushOptions can be used to alter how an image is copied somewhere.

type RunOptions 

type RunOptions struct {
	// Hostname is the hostname we set for the running container.
	Hostname string
	// Runtime is the name of the command to run.  It should accept the same arguments that runc does.
	Runtime string
	// Args adds global arguments for the runtime.
	Args []string
	// Mounts are additional mount points which we want to provide.
	Mounts []specs.Mount
	// Env is additional environment variables to set.
	Env []string
	// User is the user as whom to run the command.
	User string
	// WorkingDir is an override for the working directory.
	WorkingDir string
	// Cmd is an override for the configured default command.
	Cmd []string
	// Entrypoint is an override for the configured entry point.
	Entrypoint []string
	// NetworkDisabled puts the container into its own network namespace.
	NetworkDisabled bool
	// Terminal provides a way to specify whether or not the command should
	// be run with a pseudoterminal.  By default (DefaultTerminal), a
	// terminal is used if os.Stdout is connected to a terminal, but that
	// decision can be overridden by specifying either WithTerminal or
	// WithoutTerminal.
	Terminal int
}

RunOptions can be used to alter how a command is run in the container.

Source Files

View all Source files

Directories

Path Synopsis
cmd
buildah

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.