builder

package
v1.13.1 Latest Latest
Warning

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

Go to latest
Published: Mar 11, 2020 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package builder defines interfaces for any Docker builder to implement.

Historically, only server-side Dockerfile interpreters existed. This package allows for other implementations of Docker builders.

Index

Constants

View Source
const (
	// DefaultDockerfileName is the Default filename with Docker commands, read by docker build
	DefaultDockerfileName string = "Dockerfile"
)

Variables

This section is empty.

Functions

func GetContextFromGitURL added in v1.11.0

func GetContextFromGitURL(gitURL, dockerfileName string) (absContextDir, relDockerfile string, err error)

GetContextFromGitURL uses a Git URL as context for a `docker build`. The git repo is cloned into a temporary directory used as the context directory. Returns the absolute path to the temporary context directory, the relative path of the dockerfile in that context directory, and a non-nil error on success.

func GetContextFromLocalDir added in v1.11.0

func GetContextFromLocalDir(localDir, dockerfileName string) (absContextDir, relDockerfile string, err error)

GetContextFromLocalDir uses the given local directory as context for a `docker build`. Returns the absolute path to the local context directory, the relative path of the dockerfile in that context directory, and a non-nil error on success.

func GetContextFromReader added in v1.11.0

func GetContextFromReader(r io.ReadCloser, dockerfileName string) (out io.ReadCloser, relDockerfile string, err error)

GetContextFromReader will read the contents of the given reader as either a Dockerfile or tar archive. Returns a tar archive used as a context and a path to the Dockerfile inside the tar.

func GetContextFromURL added in v1.11.0

func GetContextFromURL(out io.Writer, remoteURL, dockerfileName string) (io.ReadCloser, string, error)

GetContextFromURL uses a remote URL as context for a `docker build`. The remote resource is downloaded as either a Dockerfile or a tar archive. Returns the tar archive used for the context and a path of the dockerfile inside the tar.

func ValidateContextDirectory added in v1.11.0

func ValidateContextDirectory(srcPath string, excludes []string) error

ValidateContextDirectory checks if all the contents of the directory can be read and returns an error if some files can't be read symlinks which point to non-existing files don't trigger an error

Types

type Backend added in v1.10.0

type Backend interface {

	// GetImageOnBuild looks up a Docker image referenced by `name`.
	GetImageOnBuild(name string) (Image, error)
	// TagImage tags an image with newTag
	TagImageWithReference(image.ID, reference.Named) error
	// PullOnBuild tells Docker to pull image referenced by `name`.
	PullOnBuild(ctx context.Context, name string, authConfigs map[string]types.AuthConfig, output io.Writer) (Image, error)
	// ContainerAttachRaw attaches to container.
	ContainerAttachRaw(cID string, stdin io.ReadCloser, stdout, stderr io.Writer, stream bool) error
	// ContainerCreate creates a new Docker container and returns potential warnings
	ContainerCreate(config types.ContainerCreateConfig) (container.ContainerCreateCreatedBody, error)
	// ContainerRm removes a container specified by `id`.
	ContainerRm(name string, config *types.ContainerRmConfig) error
	// Commit creates a new Docker image from an existing Docker container.
	Commit(string, *backend.ContainerCommitConfig) (string, error)
	// ContainerKill stops the container execution abruptly.
	ContainerKill(containerID string, sig uint64) error
	// ContainerStart starts a new container
	ContainerStart(containerID string, hostConfig *container.HostConfig, checkpoint string, checkpointDir string) error
	// ContainerWait stops processing until the given container is stopped.
	ContainerWait(containerID string, timeout time.Duration) (int, error)
	// ContainerUpdateCmdOnBuild updates container.Path and container.Args
	ContainerUpdateCmdOnBuild(containerID string, cmd []string) error
	// ContainerCreateWorkdir creates the workdir (currently only used on Windows)
	ContainerCreateWorkdir(containerID string) error

	// ContainerCopy copies/extracts a source FileInfo to a destination path inside a container
	// specified by a container object.
	// TODO: make an Extract method instead of passing `decompress`
	// TODO: do not pass a FileInfo, instead refactor the archive package to export a Walk function that can be used
	// with Context.Walk
	// ContainerCopy(name string, res string) (io.ReadCloser, error)
	// TODO: use copyBackend api
	CopyOnBuild(containerID string, destPath string, src FileInfo, decompress bool) error

	// HasExperimental checks if the backend supports experimental features
	HasExperimental() bool

	// SquashImage squashes the fs layers from the provided image down to the specified `to` image
	SquashImage(from string, to string) (string, error)
}

Backend abstracts calls to a Docker Daemon.

type Context added in v1.9.0

type Context interface {
	// Close allows to signal that the filesystem tree won't be used anymore.
	// For Context implementations using a temporary directory, it is recommended to
	// delete the temporary directory in Close().
	Close() error
	// Stat returns an entry corresponding to path if any.
	// It is recommended to return an error if path was not found.
	// If path is a symlink it also returns the path to the target file.
	Stat(path string) (string, FileInfo, error)
	// Open opens path from the context and returns a readable stream of it.
	Open(path string) (io.ReadCloser, error)
	// Walk walks the tree of the context with the function passed to it.
	Walk(root string, walkFn WalkFunc) error
}

Context represents a file system tree.

type DockerIgnoreContext added in v1.9.0

type DockerIgnoreContext struct {
	ModifiableContext
}

DockerIgnoreContext wraps a ModifiableContext to add a method for handling the .dockerignore file at the root of the context.

func (DockerIgnoreContext) Process added in v1.9.0

func (c DockerIgnoreContext) Process(filesToRemove []string) error

Process reads the .dockerignore file at the root of the embedded context. If .dockerignore does not exist in the context, then nil is returned.

It can take a list of files to be removed after .dockerignore is removed. This is used for server-side implementations of builders that need to send the .dockerignore file as well as the special files specified in filesToRemove, but expect them to be excluded from the context after they were processed.

For example, server-side Dockerfile builders are expected to pass in the name of the Dockerfile to be removed after it was parsed.

TODO: Don't require a ModifiableContext (use Context instead) and don't remove files, instead handle a list of files to be excluded from the context.

type FileInfo added in v1.9.0

type FileInfo interface {
	os.FileInfo
	Path() string
}

FileInfo extends os.FileInfo to allow retrieving an absolute path to the file. TODO: remove this interface once pkg/archive exposes a walk function that Context can use.

type Hashed added in v1.9.0

type Hashed interface {
	// Hash returns the hash of a file.
	Hash() string
	SetHash(string)
}

Hashed defines an extra method intended for implementations of os.FileInfo.

type HashedFileInfo added in v1.9.0

type HashedFileInfo struct {
	FileInfo
	// FileHash represents the hash of a file.
	FileHash string
}

HashedFileInfo is a convenient struct that augments FileInfo with a field.

func (HashedFileInfo) Hash added in v1.9.0

func (fi HashedFileInfo) Hash() string

Hash returns the hash of a file.

func (*HashedFileInfo) SetHash added in v1.9.0

func (fi *HashedFileInfo) SetHash(h string)

SetHash sets the hash of a file.

type Image added in v1.10.0

type Image interface {
	ImageID() string
	RunConfig() *container.Config
}

Image represents a Docker image used by the builder.

type ImageCache added in v1.9.0

type ImageCache interface {
	// GetCachedImageOnBuild returns a reference to a cached image whose parent equals `parent`
	// and runconfig equals `cfg`. A cache miss is expected to return an empty ID and a nil error.
	GetCache(parentID string, cfg *container.Config) (imageID string, err error)
}

ImageCache abstracts an image cache. (parent image, child runconfig) -> child image

type ImageCacheBuilder added in v1.13.0

type ImageCacheBuilder interface {
	// MakeImageCache creates a stateful image cache.
	MakeImageCache(cacheFrom []string) ImageCache
}

ImageCacheBuilder represents a generator for stateful image cache.

type ModifiableContext added in v1.9.0

type ModifiableContext interface {
	Context
	// Remove deletes the entry specified by `path`.
	// It is usual for directory entries to delete all its subentries.
	Remove(path string) error
}

ModifiableContext represents a modifiable Context. TODO: remove this interface once we can get rid of Remove()

func DetectContextFromRemoteURL added in v1.11.0

func DetectContextFromRemoteURL(r io.ReadCloser, remoteURL string, createProgressReader func(in io.ReadCloser) io.ReadCloser) (context ModifiableContext, dockerfileName string, err error)

DetectContextFromRemoteURL returns a context and in certain cases the name of the dockerfile to be used irrespective of user input. progressReader is only used if remoteURL is actually a URL (not empty, and not a Git endpoint).

func MakeGitContext added in v1.9.0

func MakeGitContext(gitURL string) (ModifiableContext, error)

MakeGitContext returns a Context from gitURL that is cloned in a temporary directory.

func MakeRemoteContext added in v1.9.0

func MakeRemoteContext(remoteURL string, contentTypeHandlers map[string]func(io.ReadCloser) (io.ReadCloser, error)) (ModifiableContext, error)

MakeRemoteContext downloads a context from remoteURL and returns it.

If contentTypeHandlers is non-nil, then the Content-Type header is read along with a maximum of maxPreambleLength bytes from the body to help detecting the MIME type. Look at acceptableRemoteMIME for more details.

If a match is found, then the body is sent to the contentType handler and a (potentially compressed) tar stream is expected to be returned. If no match is found, it is assumed the body is a tar stream (compressed or not). In either case, an (assumed) tar stream is passed to MakeTarSumContext whose result is returned.

func MakeTarSumContext added in v1.9.0

func MakeTarSumContext(tarStream io.Reader) (ModifiableContext, error)

MakeTarSumContext returns a build Context from a tar stream.

It extracts the tar stream to a temporary folder that is deleted as soon as the Context is closed. As the extraction happens, a tarsum is calculated for every file, and the set of all those sums then becomes the source of truth for all operations on this Context.

Closing tarStream has to be done by the caller.

type PathFileInfo added in v1.9.0

type PathFileInfo struct {
	os.FileInfo
	// FilePath holds the absolute path to the file.
	FilePath string
	// Name holds the basename for the file.
	FileName string
}

PathFileInfo is a convenience struct that implements the FileInfo interface.

func (PathFileInfo) Name added in v1.9.1

func (fi PathFileInfo) Name() string

Name returns the basename of the file.

func (PathFileInfo) Path added in v1.9.0

func (fi PathFileInfo) Path() string

Path returns the absolute path to the file.

type WalkFunc added in v1.9.0

type WalkFunc func(path string, fi FileInfo, err error) error

WalkFunc is the type of the function called for each file or directory visited by Context.Walk().

Directories

Path Synopsis
Package dockerfile is the evaluation step in the Dockerfile parse/evaluate pipeline.
Package dockerfile is the evaluation step in the Dockerfile parse/evaluate pipeline.
command
Package command contains the set of Dockerfile commands.
Package command contains the set of Dockerfile commands.
parser
Package parser implements a parser and parse tree dumper for Dockerfiles.
Package parser implements a parser and parse tree dumper for Dockerfiles.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL