docker

README

What is this?

This is a helper library for interacting with docker by entropy, particularly in continuous integration workflows. It provides a canonical way to create volumes, containers, images, etc and tear them down.

Documentation

Overview

Package docker allows you to orchestrate container workflows for testing, etc more easily from golang. Features include container creation, and idiomatic teardown

Index

• Constants
• func FilterByLabels(labels map[string]string) (args filters.Args)
• type Client
  • func NewDockerClient() Client
  • func (c Client) ContainerStatus(containerID string) (ContainerStatus, error)
  • func (c Client) CreateContainer(config *container.Config, hostConfig *container.HostConfig, ...) (container.ContainerCreateCreatedBody, error)
  • func (c Client) CreateNetwork(name string) (networkID string, err error)
  • func (c *Client) CreateVolume(name string) (err error)
  • func (c *Client) Exec(containerID string, cmd []string) (ExecResult, error)
  • func (c *Client) ExecRaw(containerID string, config types.ExecConfig) (ExecResult, error)
  • func (c Client) GetSessionLabels() map[string]string
  • func (c *Client) InspectExecResp(ctx context.Context, id string) (ExecResult, error)
  • func (c Client) PrintContainerLogs(containerID string)
  • func (c Client) PullImage(image string) error
  • func (c *Client) RemoveContainer(id string) error
  • func (c Client) RemoveNetwork(networkID string) error
  • func (c *Client) RemoveVolume(name string) error
  • func (c *Client) StopContainer(id string) error
  • func (c *Client) TeardownSession() (err error)
  • func (c *Client) TeardownSessionContainers() (err error)
  • func (c *Client) TeardownSessionNetworks() (err error)
  • func (c *Client) TeardownSessionVolumes() (err error)
  • func (c *Client) VolumeExists(name string) bool
• type ContainerStatus
• type ExecResult
  • func (er *ExecResult) String() string

Constants

const Driver = "local"

Driver defines the supported volume driver by docker-utils docker provides a number of different volume drivers for interacting with persistent disks. Since this library is oriented toward testing, we use local only here. For more info, see: https://docs.docker.com/engine/extend/plugins_volume/

Functions

func FilterByLabels

func FilterByLabels(labels map[string]string) (args filters.Args)

FilterByLabels creates filters.Args based on a set of labels

Types

type Client

type Client struct {
	// pointer to the original docker client
	*client.Client
	// Ctx is the context object used for interacting with docker
	Ctx context.Context
	// SessionID is the identifier used for all resources created during
	// this session (as a v4 uuid)
	SessionID string
	// configured authentication goes here
	RegistryAuth *types.AuthConfig
}

Client contains context information for the current session to allow easy teardown at the end of the session

func NewDockerClient

func NewDockerClient() Client

NewDockerClient creates a new Client and initializes it with a sessionId. Note: in some cases of failure, deferred methods like Client.TeardownSession may not be called. It may be useful to print out the session id and tell the user how to remove all items associated with a session in this scenario

func (Client) ContainerStatus

func (c Client) ContainerStatus(containerID string) (ContainerStatus, error)

ContainerStatus fetches a container's status and normalizes it see: https://docs.docker.com/engine/reference/commandline/inspect/

func (Client) CreateContainer

func (c Client) CreateContainer(config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig, platform *specs.Platform, containerName string) (container.ContainerCreateCreatedBody, error)

CreateContainer creates a container with a given *container.Config making sure to pull the image using PullImage if not present and session the SessionId for variadic teardown. See https://docs.docker.com/engine/reference/commandline/create/ for details

func (Client) CreateNetwork

func (c Client) CreateNetwork(name string) (networkID string, err error)

CreateNetwork creates a docker network that can be used for communication in between containers see: https://docs.docker.com/network/ for details

func (*Client) CreateVolume

func (c *Client) CreateVolume(name string) (err error)

CreateVolume creates a new docker volume with a unique name see Client.VolumeCreate or https://docs.docker.com/engine/extend/plugins_volume/ for details

func (*Client) Exec

func (c *Client) Exec(containerID string, cmd []string) (ExecResult, error)

Exec executes a command cmd in a container using ExecRaw This method will then attach to the container and return ExecResult using InspectExecResp. See https://docs.docker.com/engine/reference/commandline/exec/ for details

func (*Client) ExecRaw

func (c *Client) ExecRaw(containerID string, config types.ExecConfig) (ExecResult, error)

ExecRaw allows you to pass a custom types.ExecConfig to a container running your command. This method will then attach to the container and return ExecResult using InspectExecResp. See https://docs.docker.com/engine/reference/commandline/exec/ or Client.ContainerExecCreate for details

func (Client) GetSessionLabels

func (c Client) GetSessionLabels() map[string]string

GetSessionLabels gets labels set for all resources created in this session

func (*Client) InspectExecResp

func (c *Client) InspectExecResp(ctx context.Context, id string) (ExecResult, error)

InspectExecResp copies container execution results into an ExecResult object after thje command is finished executing. Returns error on failure See: https://docs.docker.com/engine/reference/commandline/attach/ for details

func (Client) PrintContainerLogs

func (c Client) PrintContainerLogs(containerID string)

PrintContainerLogs copies logs for a running, non-executing command to stdout See https://docs.docker.com/engine/reference/commandline/logs/ for details TODO: in the futre this should be more flexible

func (Client) PullImage

func (c Client) PullImage(image string) error

PullImage pulls a docker image by name. If RegistryAuth is specified, it is used here see: https://docs.docker.com/engine/reference/commandline/pull/ for details

func (*Client) RemoveContainer

func (c *Client) RemoveContainer(id string) error

RemoveContainer removes a stopped a container (and it's volumes) by id if it exists see Client.ContainerRemove or https://docs.docker.com/engine/reference/commandline/container_rm/ for details

func (Client) RemoveNetwork

func (c Client) RemoveNetwork(networkID string) error

RemoveNetwork removes a network by id

func (*Client) RemoveVolume

func (c *Client) RemoveVolume(name string) error

RemoveVolume removes a volume by name if it exists see Client.VolumeRemove or https://docs.docker.com/engine/reference/commandline/volume_rm/ for details

func (*Client) StopContainer

func (c *Client) StopContainer(id string) error

StopContainer stops a container (but does not remove it) by id if it exists see Client.ContainerStop or https://docs.docker.com/engine/reference/commandline/container_stop/ for details

func (*Client) TeardownSession

func (c *Client) TeardownSession() (err error)

TeardownSession removes all resources created during the session

func (*Client) TeardownSessionContainers

func (c *Client) TeardownSessionContainers() (err error)

TeardownSessionContainers removes containers created in the current session using StopContainer and RemoveContainer the current session is determined based on the Client so this method should be called once per Client

func (*Client) TeardownSessionNetworks

func (c *Client) TeardownSessionNetworks() (err error)

TeardownSessionNetworks removes containers created in the current session using StopContainer and RemoveContainer the current session is determined based on the Client so this method should be called once per Client

func (*Client) TeardownSessionVolumes

func (c *Client) TeardownSessionVolumes() (err error)

TeardownSessionVolumes removes containers created in the current session using RemoveVolume the current session is determined based on the Client so this method should be called once per Client

func (*Client) VolumeExists

func (c *Client) VolumeExists(name string) bool

VolumeExists checks if a volume exists by name see Client.VolumeInspect or https://docs.docker.com/engine/reference/commandline/volume_inspect/ for details

type ContainerStatus

type ContainerStatus string

ContainerStatus defines constants for container statuses in docker the standard docker library requires us to make string comparisons that are wrapped here to make comparators easier to use. see statuses here: https://docs.docker.com/engine/reference/commandline/ps/

const (
	// ContainerCreated indicates a container has been created
	// this is the status after container create
	// see: https://docs.docker.com/engine/reference/commandline/container_create/ for details
	ContainerCreated ContainerStatus = "created"
	// ContainerRunning indicates a command inside a container is running
	// see: https://docs.docker.com/engine/reference/commandline/container_run/
	ContainerRunning ContainerStatus = "running"
	// ContainerPaused indicates a container is paused and is not available
	// see: https://docs.docker.com/engine/reference/commandline/container_pause/
	ContainerPaused ContainerStatus = "paused"
	// ContainerRestarting indicates a container is in the process of restarting
	// and is not available
	// see: https://docs.docker.com/engine/reference/commandline/container_restart/
	ContainerRestarting ContainerStatus = "restarting"
	// ContainerExited indicates the command run in the container has exited
	ContainerExited ContainerStatus = "exited"
	// ContainerDead is a container that cannot be restarted
	// see: https://git.io/JqV6W
	ContainerDead ContainerStatus = "dead"
	// ContainerRemoving is a container that is in the process of being removed
	// see: https://docs.docker.com/engine/reference/commandline/rm/
	ContainerRemoving ContainerStatus = "removing"
	// ContainerUnknown is a container status that is unknown.
	ContainerUnknown ContainerStatus = "unknown"
)

container is running

type ExecResult

type ExecResult struct {
	// StdOut displays what is send to stdout by the container. This is normally in docker logs
	// See: https://docs.docker.com/config/containers/logging/
	StdOut string
	// StdOut displays what is send to stderr by the container. This is normally in docker logs
	// See: https://docs.docker.com/config/containers/logging/
	StdErr string
	// ExitCode of the process. See https://tldp.org/LDP/abs/html/exitcodes.html for details
	ExitCode int
}

ExecResult gets the result of a executed docker command

func (*ExecResult) String

func (er *ExecResult) String() string