Package org.jenkinsci.plugins.docker.workflow.client

Class DockerClient

java.lang.Object

org.jenkinsci.plugins.docker.workflow.client.DockerClient

Direct Known Subclasses:

WindowsDockerClient

public class DockerClient
extends Object

Simple docker client for Pipeline.

Author:

tom.fennelly@gmail.com

Field Summary

Fields

Modifier and Type	Field	Description
static int	CLIENT_TIMEOUT	Maximum amount of time (in seconds) to wait for docker client operations which are supposed to be more or less instantaneous.
static final String	DOCKER_DATE_TIME_FORMAT
static boolean	SKIP_RM_ON_STOP	Skip removal of container after a container has been stopped.

Constructor Summary

Constructors

Constructor	Description
DockerClient(Launcher launcher, Node node, String toolName)

Method Summary

Modifier and Type	Method	Description
com.google.common.base.Optional<String>	getContainerIdIfContainerized()	Checks if this DockerClient instance is running inside a container and returns the id of the container if so.
org.jenkinsci.plugins.docker.commons.fingerprint.ContainerRecord	getContainerRecord(EnvVars launchEnv, String containerId)
List<String>	getVolumes(EnvVars launchEnv, String containerID)	Inspect the mounts of a container.
String	inspect(EnvVars launchEnv, String objectId, String fieldPath)	Inspect a docker image/container.
String	inspectRequiredField(EnvVars launchEnv, String objectId, String fieldPath)	Inspect a docker image/container.
List<String>	listProcess(EnvVars launchEnv, String containerId)
protected static VersionNumber	parseVersionNumber(String versionString)	Parse a Docker version string (e.g.
void	rm(EnvVars launchEnv, String containerId)	Remove a container.
String	run(EnvVars launchEnv, String image, String args, String workdir, Map<String,String> volumes, Collection<String> volumesFromContainers, EnvVars containerEnv, String user, String... command)	Run a docker image.
void	stop(EnvVars launchEnv, String containerId)	Stop a container.
VersionNumber	version()	Get the docker version.
String	whoAmI()	Who is executing this DockerClient instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CLIENT_TIMEOUT

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static int CLIENT_TIMEOUT

Maximum amount of time (in seconds) to wait for docker client operations which are supposed to be more or less instantaneous.

SKIP_RM_ON_STOP

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean SKIP_RM_ON_STOP

Skip removal of container after a container has been stopped.

DOCKER_DATE_TIME_FORMAT

public static final String DOCKER_DATE_TIME_FORMAT

See Also:

• Constant Field Values

Constructor Details

DockerClient

public DockerClient(@NonNull
 Launcher launcher,
 @CheckForNull
 Node node,
 @CheckForNull
 String toolName)

Method Details

run

public String run(@NonNull
 EnvVars launchEnv,
 @NonNull
 String image,
 @CheckForNull
 String args,
 @CheckForNull
 String workdir,
 @NonNull
 Map<String,String> volumes,
 @NonNull
 Collection<String> volumesFromContainers,
 @NonNull
 EnvVars containerEnv,
 @NonNull
 String user,
 @NonNull
 String... command)
           throws IOException,
InterruptedException

Run a docker image.

Parameters:

launchEnv - Docker client launch environment.

image - The image name.

args - Any additional arguments for the docker run command.

workdir - The working directory in the container, or null for default.

volumes - Volumes to be bound. Supply an empty list if no volumes are to be bound.

volumesFromContainers - Mounts all volumes from the given containers.

containerEnv - Environment variables to set in container.

user - The uid:gid to execute the container command as. Use whoAmI().

command - The command to execute in the image container being run.

Returns:

The container ID.

Throws:

IOException

InterruptedException

listProcess

public List<String> listProcess(@NonNull
 EnvVars launchEnv,
 @NonNull
 String containerId)
                         throws IOException,
InterruptedException

Throws:

IOException

InterruptedException

stop

public void stop(@NonNull
 EnvVars launchEnv,
 @NonNull
 String containerId)
          throws IOException,
InterruptedException

Stop a container.

Also removes (rm(EnvVars, String)) the container if property SKIP_RM_ON_STOP is unset or equals false.

Parameters:

launchEnv - Docker client launch environment.

containerId - The container ID.

Throws:

IOException

InterruptedException

rm

public void rm(@NonNull
 EnvVars launchEnv,
 @NonNull
 String containerId)
        throws IOException,
InterruptedException

Remove a container.

Parameters:

launchEnv - Docker client launch environment.

containerId - The container ID.

Throws:

IOException

InterruptedException

inspect

@CheckForNull
public String inspect(@NonNull
 EnvVars launchEnv,
 @NonNull
 String objectId,
 @NonNull
 String fieldPath)
               throws IOException,
InterruptedException

Inspect a docker image/container.

Parameters:

launchEnv - Docker client launch environment.

objectId - The image/container ID.

fieldPath - The data path of the data required e.g. .NetworkSettings.IPAddress.

Returns:

The inspected field value. Null if the command failed

Throws:

IOException

InterruptedException

inspectRequiredField

@NonNull
public String inspectRequiredField(@NonNull
 EnvVars launchEnv,
 @NonNull
 String objectId,
 @NonNull
 String fieldPath)
                            throws IOException,
InterruptedException

Inspect a docker image/container.

Parameters:

launchEnv - Docker client launch environment.

objectId - The image/container ID.

fieldPath - The data path of the data required e.g. .NetworkSettings.IPAddress.

Returns:

The inspected field value. May be an empty string

Throws:

IOException - Execution error. Also fails if cannot retrieve the requested field from the request

InterruptedException - Interrupted

Since:

1.1

version

@CheckForNull
public VersionNumber version()
                      throws IOException,
InterruptedException

Get the docker version.

Returns:

The VersionNumber instance if the version string matches the expected format, otherwise null.

Throws:

IOException

InterruptedException

parseVersionNumber

protected static VersionNumber parseVersionNumber(@NonNull
 String versionString)

Parse a Docker version string (e.g. "Docker version 1.5.0, build a8a31ef").

Parameters:

versionString - The version string to parse.

Returns:

The VersionNumber instance if the version string matched the expected format, otherwise null.

whoAmI

public String whoAmI()
              throws IOException,
InterruptedException

Who is executing this DockerClient instance.

Returns:

a String containing the uid:gid.

Throws:

IOException

InterruptedException

getContainerIdIfContainerized

public com.google.common.base.Optional<String> getContainerIdIfContainerized()
                                                                      throws IOException,
InterruptedException

Checks if this DockerClient instance is running inside a container and returns the id of the container if so.

Returns:

an optional string containing the container id, or absent if it isn't containerized.

Throws:

IOException

InterruptedException

See Also:

• Discussion

getContainerRecord

public org.jenkinsci.plugins.docker.commons.fingerprint.ContainerRecord getContainerRecord(@NonNull
 EnvVars launchEnv,
 String containerId)
                                                                                    throws IOException,
InterruptedException

Throws:

IOException

InterruptedException

getVolumes

public List<String> getVolumes(@NonNull
 EnvVars launchEnv,
 String containerID)
                        throws IOException,
InterruptedException

Inspect the mounts of a container. These might have been declared VOLUMEs, or mounts defined via --volume.

Parameters:

launchEnv - Docker client launch environment.

containerID - The container ID.

Returns:

a list of filesystem paths inside the container

Throws:

IOException - Execution error. Also fails if cannot retrieve the requested field from the request

InterruptedException - Interrupted