docker

package
v1.1.9 Latest Latest
Warning

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

 Go to latest Published: Feb 21, 2018 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package docker implements Docker operations used by the S2I builder and executor.

Index

Constants

View Source 
const (
	// ScriptsURLEnvironment is a deprecated environment variable name that
	// specifies where to look for S2I scripts. Use ScriptsURLLabel instead.
	ScriptsURLEnvironment = "STI_SCRIPTS_URL"
	// LocationEnvironment is a deprecated environment variable name that
	// specifies where to place artifacts in a builder image. Use
	// DestinationLabel instead.
	LocationEnvironment = "STI_LOCATION"

	// ScriptsURLLabel is the name of the Docker image LABEL that tells S2I where
	// to look for the S2I scripts. This label is also copied into the output
	// image.
	// The previous name of this label was 'io.s2i.scripts-url'. This is now
	// deprecated.
	ScriptsURLLabel = api.DefaultNamespace + "scripts-url"

	// AssembleUserLabel is the User that will be used in the assemble process
	AssembleUserLabel = api.DefaultNamespace + "assemble-user"
	// DestinationLabel is the name of the Docker image LABEL that tells S2I where
	// to place the artifacts (scripts, sources) in the builder image.
	// The previous name of this label was 'io.s2i.destination'. This is now
	// deprecated
	DestinationLabel = api.DefaultNamespace + "destination"
	// AssembleInputFilesLabel is the name of the Docker image LABEL that tells S2I which
	// files wil be copied from builder to a runtime image.
	AssembleInputFilesLabel = api.DefaultNamespace + "assemble-input-files"

	// DefaultDestination is the destination where the artifacts will be placed
	// if DestinationLabel was not specified.
	DefaultDestination = "/tmp"
	// DefaultTag is the image tag, being applied if none is specified.
	DefaultTag = "latest"

	// DefaultDockerTimeout specifies a timeout for Docker API calls. When this
	// timeout is reached, certain Docker API calls might error out.
	DefaultDockerTimeout = 2 * time.Minute

	// DefaultShmSize is the default shared memory size to use (in bytes) if not specified.
	DefaultShmSize = int64(1024 * 1024 * 64)
	// DefaultPullRetryDelay is the default pull image retry interval
	DefaultPullRetryDelay = 5 * time.Second
	// DefaultPullRetryCount is the default pull image retry times
	DefaultPullRetryCount = 6
)

Variables

View Source 
var (

	// DefaultEntrypoint is the default entry point used when starting containers
	DefaultEntrypoint = []string{"/usr/bin/env"}
)
View Source 
var (
	// RetriableErrors is a set of strings that indicate that an retriable error occurred.
	RetriableErrors = []string{
		"ping attempt failed with error",
		"is already in progress",
		"connection reset by peer",
		"transport closed before response was received",
		"connection refused",
	}
)

Functions

func CheckAllowedUser added in v1.0.4 

func CheckAllowedUser(d Docker, imageName string, uids user.RangeList, isOnbuild bool) error

CheckAllowedUser retrieves the user for a Docker image and checks that user against an allowed range of uids. - If the range of users is not empty, then the user on the Docker image needs to be a numeric user - The user's uid must be contained by the range(s) specified by the uids Rangelist - If the image contains ONBUILD instructions and those instructions also contain a USER directive, then the user specified by that USER directive must meet the uid range criteria as well.

func GetAssembleUser added in v1.1.8 

func GetAssembleUser(client Client, config *api.Config) (string, error)

GetAssembleUser finds an assemble user on the given image. This functions receives the config to check if the AssembleUser was defined in command line If the cmd is blank, it tries to fetch the value from the Builder Image defined Label (assemble-user) Otherwise it follows the common flow, using the USER defined in Dockerfile

func GetDefaultDockerConfig added in v1.0.4 

func GetDefaultDockerConfig() *api.DockerConfig

GetDefaultDockerConfig checks relevant Docker environment variables to provide defaults for our command line flags

func GetImageRegistryAuth 

func GetImageRegistryAuth(auths *AuthConfigurations, imageName string) api.AuthConfig

GetImageRegistryAuth retrieves the appropriate docker client authentication object for a given image name and a given set of client authentication objects.

func GetRuntimeImage added in v1.1.0 

func GetRuntimeImage(config *api.Config, docker Docker) error

GetRuntimeImage processes the config and performs operations necessary to make the Docker image specified as RuntimeImage available locally.

func NewEngineAPIClient added in v1.1.3 

func NewEngineAPIClient(config *api.DockerConfig) (*dockerapi.Client, error)

NewEngineAPIClient creates a new Docker engine API client

func StreamContainerIO added in v1.0.2 

func StreamContainerIO(r io.Reader, errOutput *string, log func(string)) <-chan struct{}

StreamContainerIO starts a goroutine to take data from the reader and redirect it to the log function (typically we pass in glog.Error for stderr and glog.Info for stdout. The caller should wrap glog functions in a closure to ensure accurate line numbers are reported: https://github.com/openshift/source-to-image/issues/558 . StreamContainerIO returns a channel which is closed after the reader is closed.

Types

type AuthConfigurations added in v1.1.2 

type AuthConfigurations struct {
	Configs map[string]api.AuthConfig
}

AuthConfigurations maps a registry name to an AuthConfig, as used for example in the .dockercfg file

func LoadImageRegistryAuth added in v1.0.2 

func LoadImageRegistryAuth(dockerCfg io.Reader) *AuthConfigurations

LoadImageRegistryAuth loads and returns the set of client auth objects from a docker config json file.

func NewAuthConfigurations added in v1.1.2 

func NewAuthConfigurations(r io.Reader) (*AuthConfigurations, error)

NewAuthConfigurations finishes creating the auth config array s2i pulls from any auth config file it is pointed to when started from the command line

type BuildImageOptions 

type BuildImageOptions struct {
	Name         string
	Stdin        io.Reader
	Stdout       io.WriteCloser
	CGroupLimits *api.CGroupLimits
}

BuildImageOptions are options passed in to the BuildImage method

type Client 

type Client interface {
	ContainerAttach(ctx context.Context, container string, options dockertypes.ContainerAttachOptions) (dockertypes.HijackedResponse, error)
	ContainerCommit(ctx context.Context, container string, options dockertypes.ContainerCommitOptions) (dockertypes.IDResponse, error)
	ContainerCreate(ctx context.Context, config *dockercontainer.Config, hostConfig *dockercontainer.HostConfig, networkingConfig *dockernetwork.NetworkingConfig, containerName string) (dockercontainer.ContainerCreateCreatedBody, error)
	ContainerInspect(ctx context.Context, container string) (dockertypes.ContainerJSON, error)
	ContainerRemove(ctx context.Context, container string, options dockertypes.ContainerRemoveOptions) error
	ContainerStart(ctx context.Context, container string, options dockertypes.ContainerStartOptions) error
	ContainerKill(ctx context.Context, container, signal string) error
	ContainerWait(ctx context.Context, container string, condition dockercontainer.WaitCondition) (<-chan dockercontainer.ContainerWaitOKBody, <-chan error)
	CopyToContainer(ctx context.Context, container, path string, content io.Reader, opts dockertypes.CopyToContainerOptions) error
	CopyFromContainer(ctx context.Context, container, srcPath string) (io.ReadCloser, dockertypes.ContainerPathStat, error)
	ImageBuild(ctx context.Context, buildContext io.Reader, options dockertypes.ImageBuildOptions) (dockertypes.ImageBuildResponse, error)
	ImageInspectWithRaw(ctx context.Context, image string) (dockertypes.ImageInspect, []byte, error)
	ImagePull(ctx context.Context, ref string, options dockertypes.ImagePullOptions) (io.ReadCloser, error)
	ImageRemove(ctx context.Context, image string, options dockertypes.ImageRemoveOptions) ([]dockertypes.ImageDeleteResponseItem, error)
	ServerVersion(ctx context.Context) (dockertypes.Version, error)
}

Client contains all methods used when interacting directly with docker engine-api

type CommitContainerOptions 

type CommitContainerOptions struct {
	ContainerID string
	Repository  string
	User        string
	Command     []string
	Env         []string
	Entrypoint  []string
	Labels      map[string]string
}

CommitContainerOptions are options passed in to the CommitContainer method

type Docker 

type Docker interface {
	IsImageInLocalRegistry(name string) (bool, error)
	IsImageOnBuild(string) bool
	GetOnBuild(string) ([]string, error)
	RemoveContainer(id string) error
	GetScriptsURL(name string) (string, error)
	GetAssembleInputFiles(string) (string, error)
	RunContainer(opts RunContainerOptions) error
	GetImageID(name string) (string, error)
	GetImageWorkdir(name string) (string, error)
	CommitContainer(opts CommitContainerOptions) (string, error)
	RemoveImage(name string) error
	CheckImage(name string) (*api.Image, error)
	PullImage(name string) (*api.Image, error)
	CheckAndPullImage(name string) (*api.Image, error)
	BuildImage(opts BuildImageOptions) error
	GetImageUser(name string) (string, error)
	GetImageEntrypoint(name string) ([]string, error)
	GetLabels(name string) (map[string]string, error)
	UploadToContainer(fs fs.FileSystem, srcPath, destPath, container string) error
	UploadToContainerWithTarWriter(fs fs.FileSystem, srcPath, destPath, container string, makeTarWriter func(io.Writer) s2itar.Writer) error
	DownloadFromContainer(containerPath string, w io.Writer, container string) error
	Version() (dockertypes.Version, error)
	CheckReachable() error
}

Docker is the interface between STI and the docker engine-api. It contains higher level operations called from the STI build or usage commands

func New 

func New(client Client, auth api.AuthConfig) Docker

New creates a new implementation of the STI Docker interface

type FakeDocker added in v1.0.4 

type FakeDocker struct {
	LocalRegistryImage           string
	LocalRegistryResult          bool
	LocalRegistryError           error
	RemoveContainerID            string
	RemoveContainerError         error
	DefaultURLImage              string
	DefaultURLResult             string
	DefaultURLError              error
	AssembleInputFilesResult     string
	AssembleInputFilesError      error
	RunContainerOpts             RunContainerOptions
	RunContainerError            error
	RunContainerErrorBeforeStart bool
	RunContainerContainerID      string
	RunContainerCmd              []string
	GetImageIDImage              string
	GetImageIDResult             string
	GetImageIDError              error
	GetImageUserImage            string
	GetImageUserResult           string
	GetImageUserError            error
	GetImageEntrypointResult     []string
	GetImageEntrypointError      error
	CommitContainerOpts          CommitContainerOptions
	CommitContainerResult        string
	CommitContainerError         error
	RemoveImageName              string
	RemoveImageError             error
	BuildImageOpts               BuildImageOptions
	BuildImageError              error
	PullResult                   bool
	PullError                    error
	OnBuildImage                 string
	OnBuildResult                []string
	OnBuildError                 error
	IsOnBuildResult              bool
	IsOnBuildImage               string
	Labels                       map[string]string
	LabelsError                  error
}

FakeDocker provides a fake docker interface

func (*FakeDocker) BuildImage added in v1.0.4 

func (f *FakeDocker) BuildImage(opts BuildImageOptions) error

BuildImage builds image

func (*FakeDocker) CheckAndPullImage added in v1.0.4 

func (f *FakeDocker) CheckAndPullImage(name string) (*api.Image, error)

CheckAndPullImage pulls a fake docker image

func (*FakeDocker) CheckImage added in v1.0.4 

func (f *FakeDocker) CheckImage(name string) (*api.Image, error)

CheckImage checks image in local registry

func (*FakeDocker) CheckReachable added in v1.1.6 

func (f *FakeDocker) CheckReachable() error

CheckReachable returns if the Docker daemon is reachable from s2i

func (*FakeDocker) CommitContainer added in v1.0.4 

func (f *FakeDocker) CommitContainer(opts CommitContainerOptions) (string, error)

CommitContainer commits a fake Docker container

func (*FakeDocker) DownloadFromContainer added in v1.1.0 

func (f *FakeDocker) DownloadFromContainer(containerPath string, w io.Writer, container string) error

DownloadFromContainer downloads file (or directory) from the container.

func (*FakeDocker) GetAssembleInputFiles added in v1.1.0 

func (f *FakeDocker) GetAssembleInputFiles(image string) (string, error)

GetAssembleInputFiles finds a io.openshift.s2i.assemble-input-files label on the given image.

func (*FakeDocker) GetImageEntrypoint added in v1.1.1 

func (f *FakeDocker) GetImageEntrypoint(image string) ([]string, error)

GetImageEntrypoint returns an empty entrypoint

func (*FakeDocker) GetImageID added in v1.0.4 

func (f *FakeDocker) GetImageID(image string) (string, error)

GetImageID returns a fake Docker image ID

func (*FakeDocker) GetImageUser added in v1.0.4 

func (f *FakeDocker) GetImageUser(image string) (string, error)

GetImageUser returns a fake user

func (*FakeDocker) GetImageWorkdir added in v1.0.5 

func (f *FakeDocker) GetImageWorkdir(name string) (string, error)

GetImageWorkdir returns the workdir

func (*FakeDocker) GetLabels added in v1.0.4 

func (f *FakeDocker) GetLabels(name string) (map[string]string, error)

GetLabels returns the labels of the image

func (*FakeDocker) GetOnBuild added in v1.0.4 

func (f *FakeDocker) GetOnBuild(imageName string) ([]string, error)

GetOnBuild returns the list of onbuild instructions for the given image

func (*FakeDocker) GetScriptsURL added in v1.0.4 

func (f *FakeDocker) GetScriptsURL(image string) (string, error)

GetScriptsURL returns a default STI scripts URL

func (*FakeDocker) IsImageInLocalRegistry added in v1.0.4 

func (f *FakeDocker) IsImageInLocalRegistry(imageName string) (bool, error)

IsImageInLocalRegistry checks if the image exists in the fake local registry

func (*FakeDocker) IsImageOnBuild added in v1.0.4 

func (f *FakeDocker) IsImageOnBuild(imageName string) bool

IsImageOnBuild returns true if the builder has onbuild instructions

func (*FakeDocker) KillContainer added in v1.1.5 

func (f *FakeDocker) KillContainer(id string) error

KillContainer kills a fake container

func (*FakeDocker) PullImage added in v1.0.4 

func (f *FakeDocker) PullImage(imageName string) (*api.Image, error)

PullImage pulls a fake docker image

func (*FakeDocker) RemoveContainer added in v1.0.4 

func (f *FakeDocker) RemoveContainer(id string) error

RemoveContainer removes a fake Docker container

func (*FakeDocker) RemoveImage added in v1.0.4 

func (f *FakeDocker) RemoveImage(name string) error

RemoveImage removes a fake Docker image

func (*FakeDocker) RunContainer added in v1.0.4 

func (f *FakeDocker) RunContainer(opts RunContainerOptions) error

RunContainer runs a fake Docker container

func (*FakeDocker) UploadToContainer added in v1.0.5 

func (f *FakeDocker) UploadToContainer(fs fs.FileSystem, srcPath, destPath, container string) error

UploadToContainer uploads artifacts to the container.

func (*FakeDocker) UploadToContainerWithTarWriter added in v1.1.4 

func (f *FakeDocker) UploadToContainerWithTarWriter(fs fs.FileSystem, srcPath, destPath, container string, makeTarWriter func(io.Writer) tar.Writer) error

UploadToContainerWithTarWriter uploads artifacts to the container.

func (*FakeDocker) Version added in v1.1.3 

func (f *FakeDocker) Version() (dockertypes.Version, error)

Version returns information of the docker client and server host

type PostExecutor 

type PostExecutor interface {
	PostExecute(containerID, destination string) error
}

PostExecutor is an interface which provides a PostExecute function

type PullResult 

type PullResult struct {
	OnBuild bool
	Image   *api.Image
}

PullResult is the result returned by the PullImage function

func GetBuilderImage added in v1.0.4 

func GetBuilderImage(client Client, config *api.Config) (*PullResult, error)

GetBuilderImage processes the config and performs operations necessary to make the Docker image specified as BuilderImage available locally. It returns information about the base image, containing metadata necessary for choosing the right STI build strategy.

func GetRebuildImage added in v1.1.2 

func GetRebuildImage(client Client, config *api.Config) (*PullResult, error)

GetRebuildImage obtains the metadata information for the image specified in a s2i rebuild operation. Assumptions are made that the build is available locally since it should have been previously built.

func PullImage added in v1.0.4 

func PullImage(name string, d Docker, policy api.PullPolicy) (*PullResult, error)

PullImage pulls the Docker image specified by name taking the pull policy into the account.

type RunContainerOptions 

type RunContainerOptions struct {
	Image           string
	PullImage       bool
	PullAuth        api.AuthConfig
	ExternalScripts bool
	ScriptsURL      string
	Destination     string
	Env             []string
	// Entrypoint will be used to override the default entrypoint
	// for the image if it has one.  If the image has no entrypoint,
	// this value is ignored.
	Entrypoint       []string
	Stdin            io.ReadCloser
	Stdout           io.WriteCloser
	Stderr           io.WriteCloser
	OnStart          func(containerID string) error
	PostExec         PostExecutor
	TargetImage      bool
	NetworkMode      string
	User             string
	CGroupLimits     *api.CGroupLimits
	CapDrop          []string
	Binds            []string
	Command          string
	CommandOverrides func(originalCmd string) string
	// CommandExplicit provides a full control on the CMD directive.
	// It won't modified in any way and will be passed to the docker as-is.
	// Use this option when you want to use arbitrary command as CMD directive.
	// In this case you can't use Command because 1) it's just a string
	// 2) it will be modified by prepending base dir and cleaned by the path.Join().
	// You also can't use CommandOverrides because 1) it's a string
	// 2) it only gets applied when Command equals to "assemble" or "usage" script
	// AND script is inside of the tar archive.
	CommandExplicit []string
	// SecurityOpt is passed through as security options to the underlying container.
	SecurityOpt []string
}

RunContainerOptions are options passed in to the RunContainer method

Source Files

View all Source files

Directories

Path Synopsis

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.