docker

package
v0.41.13 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2023 License: Apache-2.0 Imports: 18 Imported by: 12

Documentation

Overview

Package docker allows to interact with Docker and docker compose resources.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Build added in v0.22.3 

func Build(t testing.TestingT, path string, options *BuildOptions)

Build runs the 'docker build' command at the given path with the given options and fails the test if there are any errors.

func BuildE added in v0.22.3 

func BuildE(t testing.TestingT, path string, options *BuildOptions) error

BuildE runs the 'docker build' command at the given path with the given options and returns any errors.

func DeleteImage added in v0.40.2 

func DeleteImage(t testing.TestingT, img string, logger *logger.Logger)

DeleteImage removes a docker image using the Docker CLI. This will fail the test if there is an error.

func DeleteImageE added in v0.40.2 

func DeleteImageE(t testing.TestingT, img string, logger *logger.Logger) error

DeleteImageE removes a docker image using the Docker CLI.

func DoesImageExist added in v0.40.2 

func DoesImageExist(t testing.TestingT, imgLabel string, logger *logger.Logger) bool

DoesImageExist lists the images in the docker daemon and returns true if the given image label (repo:tag) exists. This will fail the test if there is an error.

func GetDockerHost added in v0.30.11 

func GetDockerHost() string

GetDockerHost returns the name or address of the host on which the Docker engine is running.

func GitCloneAndBuild added in v0.40.2 

func GitCloneAndBuild(
	t testing.TestingT,
	repo string,
	ref string,
	path string,
	dockerBuildOpts *BuildOptions,
)

GitCloneAndBuild builds a new Docker image from a given Git repo. This function will clone the given repo at the specified ref, and call the docker build command on the cloned repo from the given relative path (relative to repo root). This will fail the test if there are any errors.

func GitCloneAndBuildE added in v0.40.2 

func GitCloneAndBuildE(
	t testing.TestingT,
	repo string,
	ref string,
	path string,
	dockerBuildOpts *BuildOptions,
) error

GitCloneAndBuildE builds a new Docker image from a given Git repo. This function will clone the given repo at the specified ref, and call the docker build command on the cloned repo from the given relative path (relative to repo root).

func Push added in v0.37.5 

func Push(t testing.TestingT, logger *logger.Logger, tag string)

Push runs the 'docker push' command to push the given tag. This will fail the test if there are any errors.

func PushE added in v0.37.5 

func PushE(t testing.TestingT, logger *logger.Logger, tag string) error

PushE runs the 'docker push' command to push the given tag.

func Run added in v0.22.3 

func Run(t testing.TestingT, image string, options *RunOptions) string

Run runs the 'docker run' command on the given image with the given options and return stdout/stderr. This method fails the test if there are any errors.

func RunAndGetID added in v0.26.5 

func RunAndGetID(t testing.TestingT, image string, options *RunOptions) string

RunAndGetID runs the 'docker run' command on the given image with the given options and returns the container ID that is returned in stdout. This method fails the test if there are any errors.

func RunAndGetIDE added in v0.26.5 

func RunAndGetIDE(t testing.TestingT, image string, options *RunOptions) (string, error)

RunAndGetIDE runs the 'docker run' command on the given image with the given options and returns the container ID that is returned in stdout, or any error.

func RunDockerCompose 

func RunDockerCompose(t testing.TestingT, options *Options, args ...string) string

RunDockerCompose runs docker compose with the given arguments and options and return stdout/stderr.

func RunDockerComposeAndGetStdOut added in v0.30.7 

func RunDockerComposeAndGetStdOut(t testing.TestingT, options *Options, args ...string) string

RunDockerComposeAndGetStdout runs docker compose with the given arguments and options and returns only stdout.

func RunDockerComposeE 

func RunDockerComposeE(t testing.TestingT, options *Options, args ...string) (string, error)

RunDockerComposeE runs docker compose with the given arguments and options and return stdout/stderr.

func RunE added in v0.22.3 

func RunE(t testing.TestingT, image string, options *RunOptions) (string, error)

RunE runs the 'docker run' command on the given image with the given options and return stdout/stderr, or any error.

func Stop added in v0.23.2 

func Stop(t testing.TestingT, containers []string, options *StopOptions) string

Stop runs the 'docker stop' command for the given containers and return the stdout/stderr. This method fails the test if there are any errors

func StopE added in v0.23.2 

func StopE(t testing.TestingT, containers []string, options *StopOptions) (string, error)

StopE runs the 'docker stop' command for the given containers and returns any errors.

Types

type BuildOptions added in v0.22.3 

type BuildOptions struct {
	// Tags for the Docker image
	Tags []string

	// Build args to pass the 'docker build' command
	BuildArgs []string

	// Target build arg to pass to the 'docker build' command
	Target string

	// All architectures to target in a multiarch build. Configuring this variable will cause terratest to use docker
	// buildx to construct multiarch images.
	// You can read more about multiarch docker builds in the official documentation for buildx:
	// https://docs.docker.com/buildx/working-with-buildx/
	// NOTE: This list does not automatically include the current platform. For example, if you are building images on
	// an Apple Silicon based MacBook, and you configure this variable to []string{"linux/amd64"} to build an amd64
	// image, the buildx command will not automatically include linux/arm64 - you must include that explicitly.
	Architectures []string

	// Whether or not to push images directly to the registry on build. Note that for multiarch images (Architectures is
	// not empty), this must be true to ensure availability of all architectures - only the image for the current
	// platform will be loaded into the daemon (due to a limitation of the docker daemon), so you won't be able to run a
	// `docker push` command later to push the multiarch image.
	// See https://github.com/moby/moby/pull/38738 for more info on the limitation of multiarch images in docker daemon.
	Push bool

	// Whether or not to load the image into the docker daemon at the end of a multiarch build so that it can be used
	// locally. Note that this is only used when Architectures is set, and assumes the current architecture is already
	// included in the Architectures list.
	Load bool

	// Custom CLI options that will be passed as-is to the 'docker build' command. This is an "escape hatch" that allows
	// Terratest to not have to support every single command-line option offered by the 'docker build' command, and
	// solely focus on the most important ones.
	OtherOptions []string

	// Whether ot not to enable buildkit. You can find more information about buildkit here https://docs.docker.com/build/buildkit/#getting-started.
	EnableBuildKit bool

	// Additional environment variables to pass in when running docker build command.
	Env map[string]string

	// Set a logger that should be used. See the logger package for more info.
	Logger *logger.Logger
}

BuildOptions defines options that can be passed to the 'docker build' command.

type ContainerInspect added in v0.26.5 

type ContainerInspect struct {
	// ID of the inspected container
	ID string

	// Name of the inspected container
	Name string

	// time.Time that the container was created
	Created time.Time

	// String representing the container's status
	Status string

	// Whether the container is currently running or not
	Running bool

	// Container's exit code
	ExitCode uint8

	// String with the container's error message, if there is any
	Error string

	// Ports exposed by the container
	Ports []Port

	// Volume bindings made to the container
	Binds []VolumeBind

	// Health check
	Health HealthCheck
}

ContainerInspect defines the output of the Inspect method, with the options returned by 'docker inspect' converted into a more friendly and testable interface

func Inspect added in v0.26.5 

func Inspect(t *testing.T, id string) *ContainerInspect

Inspect runs the 'docker inspect {container id}' command and returns a ContainerInspect struct, converted from the output JSON, along with any errors

func InspectE added in v0.26.5 

func InspectE(t *testing.T, id string) (*ContainerInspect, error)

InspectE runs the 'docker inspect {container id}' command and returns a ContainerInspect struct, converted from the output JSON, along with any errors

func (ContainerInspect) GetExposedHostPort added in v0.32.14 

func (inspectOutput ContainerInspect) GetExposedHostPort(containerPort uint16) uint16

GetExposedHostPort returns an exposed host port according to requested container port. Returns 0 if the requested port is not exposed.

type HealthCheck added in v0.27.1 

type HealthCheck struct {
	// Health check status
	Status string

	// Current count of failing health checks
	FailingStreak uint8

	// Log of failures
	Log []HealthLog
}

HealthCheck represents the current health history of the container

type HealthLog added in v0.27.1 

type HealthLog struct {
	// Start time of health check
	Start string

	// End time of health check
	End string

	// Exit code of health check
	ExitCode uint8

	// Output of health check
	Output string
}

HealthLog represents the output of a single Health check of the container

type Image added in v0.40.2 

type Image struct {
	// ID is the image ID in docker, and can be used to identify the image in place of the repo and tag.
	ID string

	// Repository is the image repository.
	Repository string

	// Tag is the image tag wichin the repository.
	Tag string

	// CreatedAt represents a timestamp for when the image was created.
	CreatedAt string

	// CreatedSince is a diff between when the image was created to now.
	CreatedSince string

	// SharedSize is the amount of space that an image shares with another one (i.e. their common data).
	SharedSize string

	// UniqueSize is the amount of space that is only used by a given image.
	UniqueSize string

	// VirtualSize is the total size of the image, combining SharedSize and UniqueSize.
	VirtualSize string

	// Containers represents the list of containers that are using the image.
	Containers string

	// Digest is the hash digest of the image, if requested.
	Digest string
}

Image represents a docker image, and exports all the fields that the docker images command returns for the image.

func ListImages added in v0.40.2 

func ListImages(t testing.TestingT, logger *logger.Logger) []Image

ListImages calls docker images using the Docker CLI to list the available images on the local docker daemon.

func ListImagesE added in v0.40.2 

func ListImagesE(t testing.TestingT, logger *logger.Logger) ([]Image, error)

ListImagesE calls docker images using the Docker CLI to list the available images on the local docker daemon.

func (Image) String added in v0.40.2 

func (image Image) String() string

type Options 

type Options struct {
	WorkingDir string
	EnvVars    map[string]string

	// Whether ot not to enable buildkit. You can find more information about buildkit here https://docs.docker.com/build/buildkit/#getting-started.
	EnableBuildKit bool

	// Set a logger that should be used. See the logger package for more info.
	Logger      *logger.Logger
	ProjectName string
}

Options are Docker options.

type Port added in v0.26.5 

type Port struct {
	HostPort      uint16
	ContainerPort uint16
	Protocol      string
}

Port represents a single port mapping exported by the container

type RunOptions added in v0.22.3 

type RunOptions struct {
	// Override the default COMMAND of the Docker image
	Command []string

	// If set to true, pass the --detach flag to 'docker run' to run the container in the background
	Detach bool

	// Override the default ENTRYPOINT of the Docker image
	Entrypoint string

	// Set environment variables
	EnvironmentVariables []string

	// If set to true, pass the --init flag to 'docker run' to run an init inside the container that forwards signals
	// and reaps processes
	Init bool

	// Assign a name to the container
	Name string

	// If set to true, pass the --privileged flag to 'docker run' to give extended privileges to the container
	Privileged bool

	// If set to true, pass the --rm flag to 'docker run' to automatically remove the container when it exits
	Remove bool

	// If set to true, pass the -tty flag to 'docker run' to allocate a pseudo-TTY
	Tty bool

	// Username or UID
	User string

	// Bind mount these volume(s) when running the container
	Volumes []string

	// Custom CLI options that will be passed as-is to the 'docker run' command. This is an "escape hatch" that allows
	// Terratest to not have to support every single command-line option offered by the 'docker run' command, and
	// solely focus on the most important ones.
	OtherOptions []string

	// Set a logger that should be used. See the logger package for more info.
	Logger *logger.Logger
}

RunOptions defines options that can be passed to the 'docker run' command.

type StopOptions added in v0.23.2 

type StopOptions struct {
	// Seconds to wait for stop before killing the container (default 10)
	Time int

	// Set a logger that should be used. See the logger package for more info.
	Logger *logger.Logger
}

StopOptions defines the options that can be passed to the 'docker stop' command

type VolumeBind added in v0.26.5 

type VolumeBind struct {
	Source      string
	Destination string
}

VolumeBind represents a single volume binding made to the container

Source Files

View all Source files

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.