Documentation
¶
Overview ¶
Package docker implements Docker operations used by the S2I builder and executor.
Index ¶
- Constants
- Variables
- func CheckAllowedUser(d Docker, imageName string, uids user.RangeList, isOnbuild bool) error
- func GetAssembleUser(client Client, config *api.Config) (string, error)
- func GetDefaultDockerConfig() *api.DockerConfig
- func GetImageRegistryAuth(auths *AuthConfigurations, imageName string) api.AuthConfig
- func GetRuntimeImage(config *api.Config, docker Docker) error
- func NewEngineAPIClient(config *api.DockerConfig) (*dockerapi.Client, error)
- func StreamContainerIO(r io.Reader, errOutput *string, log func(string)) <-chan struct{}
- type AuthConfigurations
- type BuildImageOptions
- type Client
- type CommitContainerOptions
- type Docker
- type FakeDocker
- func (f *FakeDocker) BuildImage(opts BuildImageOptions) error
- func (f *FakeDocker) CheckAndPullImage(name string) (*api.Image, error)
- func (f *FakeDocker) CheckImage(name string) (*api.Image, error)
- func (f *FakeDocker) CheckReachable() error
- func (f *FakeDocker) CommitContainer(opts CommitContainerOptions) (string, error)
- func (f *FakeDocker) DownloadFromContainer(containerPath string, w io.Writer, container string) error
- func (f *FakeDocker) GetAssembleInputFiles(image string) (string, error)
- func (f *FakeDocker) GetImageEntrypoint(image string) ([]string, error)
- func (f *FakeDocker) GetImageID(image string) (string, error)
- func (f *FakeDocker) GetImageUser(image string) (string, error)
- func (f *FakeDocker) GetImageWorkdir(name string) (string, error)
- func (f *FakeDocker) GetLabels(name string) (map[string]string, error)
- func (f *FakeDocker) GetOnBuild(imageName string) ([]string, error)
- func (f *FakeDocker) GetScriptsURL(image string) (string, error)
- func (f *FakeDocker) IsImageInLocalRegistry(imageName string) (bool, error)
- func (f *FakeDocker) IsImageOnBuild(imageName string) bool
- func (f *FakeDocker) KillContainer(id string) error
- func (f *FakeDocker) PullImage(imageName string) (*api.Image, error)
- func (f *FakeDocker) RemoveContainer(id string) error
- func (f *FakeDocker) RemoveImage(name string) error
- func (f *FakeDocker) RunContainer(opts RunContainerOptions) error
- func (f *FakeDocker) UploadToContainer(fs fs.FileSystem, srcPath, destPath, container string) error
- func (f *FakeDocker) UploadToContainerWithTarWriter(fs fs.FileSystem, srcPath, destPath, container string, ...) error
- func (f *FakeDocker) Version() (dockertypes.Version, error)
- type PostExecutor
- type PullResult
- type RunContainerOptions
Constants ¶
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 ¶
var ( // DefaultEntrypoint is the default entry point used when starting containers DefaultEntrypoint = []string{"/usr/bin/env"} )
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
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
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
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
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.ContainerCommitResponse, error)
ContainerCreate(ctx context.Context, config *dockercontainer.Config, hostConfig *dockercontainer.HostConfig, networkingConfig *dockernetwork.NetworkingConfig, containerName string) (dockertypes.ContainerCreateResponse, error)
ContainerInspect(ctx context.Context, containerID string) (dockertypes.ContainerJSON, error)
ContainerRemove(ctx context.Context, containerID string, options dockertypes.ContainerRemoveOptions) error
ContainerStart(ctx context.Context, containerID string) error
ContainerKill(ctx context.Context, containerID, signal string) error
ContainerWait(ctx context.Context, containerID string) (int, 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, imageID string, getSize bool) (dockertypes.ImageInspect, []byte, error)
ImagePull(ctx context.Context, ref string, options dockertypes.ImagePullOptions) (io.ReadCloser, error)
ImageRemove(ctx context.Context, imageID string, options dockertypes.ImageRemoveOptions) ([]dockertypes.ImageDelete, 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
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 ¶
PostExecutor is an interface which provides a PostExecute function
type PullResult ¶
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