dockerutil

Documentation

Overview

Package dockerutil is a collection of utility functions, primarily for testing.

Index

• func EnsureSupportedDockerVersion()
• func LinkArg(source *Docker, target string) string
• func MountArg(source, target string, mode MountMode) string
• func PrepareFiles(names ...string) (string, error)
• func Pull(image string) error
• func RuntimePath() (string, error)
• type Docker
  • func MakeDocker(namePrefix string) Docker
  • func (d *Docker) Checkpoint(name string) error
  • func (d *Docker) CleanUp()
  • func (d *Docker) Create(args ...string) error
  • func (d *Docker) Exec(args ...string) (string, error)
  • func (d *Docker) ExecAsUser(user string, args ...string) (string, error)
  • func (d *Docker) ExecWithFlags(flags []string, args ...string) (string, error)
  • func (d *Docker) ExecWithTerminal(args ...string) (*exec.Cmd, *os.File, error)
  • func (d *Docker) FindIP() (string, error)
  • func (d *Docker) FindPort(sandboxPort int) (int, error)
  • func (d *Docker) ID() (string, error)
  • func (d *Docker) Logs() (string, error)
  • func (d *Docker) Pause() error
  • func (d *Docker) Remove() error
  • func (d *Docker) Restore(name string) error
  • func (d *Docker) Run(args ...string) error
  • func (d *Docker) RunFg(args ...string) (string, error)
  • func (d *Docker) RunWithPty(args ...string) (*exec.Cmd, *os.File, error)
  • func (d *Docker) SandboxPid() (int, error)
  • func (d *Docker) Start() error
  • func (d *Docker) Stop() error
  • func (d *Docker) Unpause() error
  • func (d *Docker) Wait(timeout time.Duration) (syscall.WaitStatus, error)
  • func (d *Docker) WaitForOutput(pattern string, timeout time.Duration) (string, error)
  • func (d *Docker) WaitForOutputSubmatch(pattern string, timeout time.Duration) ([]string, error)
• type MountMode
  • func (m MountMode) String() string

Functions

func EnsureSupportedDockerVersion

func EnsureSupportedDockerVersion()

EnsureSupportedDockerVersion checks if correct docker is installed.

func LinkArg

func LinkArg(source *Docker, target string) string

LinkArg formats the link argument.

func MountArg

func MountArg(source, target string, mode MountMode) string

MountArg formats the volume argument to mount in the container.

func PrepareFiles

func PrepareFiles(names ...string) (string, error)

PrepareFiles creates temp directory to copy files there. The sandbox doesn't have access to files in the test dir.

func Pull

func Pull(image string) error

Pull pulls a docker image. This is used in tests to isolate the time to pull the image off the network from the time to actually start the container, to avoid timeouts over slow networks.

func RuntimePath

func RuntimePath() (string, error)

RuntimePath returns the binary path for the current runtime.

Types

type Docker

type Docker struct {
	Runtime string
	Name    string
}

Docker contains the name and the runtime of a docker container.

func MakeDocker

func MakeDocker(namePrefix string) Docker

MakeDocker sets up the struct for a Docker container. Names of containers will be unique.

func (*Docker) Checkpoint

func (d *Docker) Checkpoint(name string) error

Checkpoint calls 'docker checkpoint'.

func (*Docker) CleanUp

func (d *Docker) CleanUp()

CleanUp kills and deletes the container (best effort).

func (*Docker) Create

func (d *Docker) Create(args ...string) error

Create calls 'docker create' with the arguments provided.

func (*Docker) Exec

func (d *Docker) Exec(args ...string) (string, error)

Exec calls 'docker exec' with the arguments provided.

func (*Docker) ExecAsUser

func (d *Docker) ExecAsUser(user string, args ...string) (string, error)

ExecAsUser calls 'docker exec' as the given user with the arguments provided.

func (*Docker) ExecWithFlags

func (d *Docker) ExecWithFlags(flags []string, args ...string) (string, error)

ExecWithFlags calls 'docker exec <flags> name <args>'.

func (*Docker) ExecWithTerminal

func (d *Docker) ExecWithTerminal(args ...string) (*exec.Cmd, *os.File, error)

ExecWithTerminal calls 'docker exec -it' with the arguments provided and attaches a pty to stdio.

func (*Docker) FindIP

func (d *Docker) FindIP() (string, error)

FindIP returns the IP address of the container as a string.

func (*Docker) FindPort

func (d *Docker) FindPort(sandboxPort int) (int, error)

FindPort returns the host port that is mapped to 'sandboxPort'. This calls docker to allocate a free port in the host and prevent conflicts.

func (*Docker) ID

func (d *Docker) ID() (string, error)

ID returns the container ID.

func (*Docker) Logs

func (d *Docker) Logs() (string, error)

Logs calls 'docker logs'.

func (*Docker) Pause

func (d *Docker) Pause() error

Pause calls 'docker pause'.

func (*Docker) Remove

func (d *Docker) Remove() error

Remove calls 'docker rm'.

func (*Docker) Restore

func (d *Docker) Restore(name string) error

Restore calls 'docker start --checkname [name]'.

func (*Docker) Run

func (d *Docker) Run(args ...string) error

Run calls 'docker run' with the arguments provided. The container starts running in the background and the call returns immediately.

func (*Docker) RunFg

func (d *Docker) RunFg(args ...string) (string, error)

RunFg calls 'docker run' with the arguments provided in the foreground. It blocks until the container exits and returns the output.

func (*Docker) RunWithPty

func (d *Docker) RunWithPty(args ...string) (*exec.Cmd, *os.File, error)

RunWithPty is like Run but with an attached pty.

func (*Docker) SandboxPid

func (d *Docker) SandboxPid() (int, error)

SandboxPid returns the PID to the sandbox process.

func (*Docker) Start

func (d *Docker) Start() error

Start calls 'docker start'.

func (*Docker) Stop

func (d *Docker) Stop() error

Stop calls 'docker stop'.

func (*Docker) Unpause

func (d *Docker) Unpause() error

Unpause calls 'docker pause'.

func (*Docker) Wait

func (d *Docker) Wait(timeout time.Duration) (syscall.WaitStatus, error)

Wait waits for container to exit, up to the given timeout. Returns error if wait fails or timeout is hit. Returns the application return code otherwise. Note that the application may have failed even if err == nil, always check the exit code.

func (*Docker) WaitForOutput

func (d *Docker) WaitForOutput(pattern string, timeout time.Duration) (string, error)

WaitForOutput calls 'docker logs' to retrieve containers output and searches for the given pattern.

func (*Docker) WaitForOutputSubmatch

func (d *Docker) WaitForOutputSubmatch(pattern string, timeout time.Duration) ([]string, error)

WaitForOutputSubmatch calls 'docker logs' to retrieve containers output and searches for the given pattern. It returns any regexp submatches as well.

type MountMode

type MountMode int

MountMode describes if the mount should be ro or rw.

const (
	// ReadOnly is what the name says.
	ReadOnly MountMode = iota
	// ReadWrite is what the name says.
	ReadWrite
)

func (MountMode) String

func (m MountMode) String() string

String returns the mount mode argument for this MountMode.