Management commands for working with a particular docker container

Source: R/help.R

Methods for working with a particular docker container. Container objects are returned by creating or running a docker container, or by using $container$get to fetch an existing container by name or id.

Details

Below is reference documentation for all methods for version '1.29' of the docker API - other versions are available. This documentation is automatically generated from docker's API schema, and so inaccuracies may exist between it and stevedore's interface (especially references to JSON objects). Please report any documentation that might be improved at https://github.com/richfitz/stevedore/issues

Methods

image_commit

Create a new image from a container. Similar to the cli command docker commit or docker container commit.

Usage:

  image_commit(repo = NULL, tag = NULL, author = NULL,
      changes = NULL, comment = NULL, pause = NULL,
      hostname = NULL, domainname = NULL, user = NULL,
      attach_stdin = NULL, attach_stdout = NULL,
      attach_stderr = NULL, exposed_ports = NULL, tty = NULL,
      open_stdin = NULL, stdin_once = NULL, env = NULL,
      cmd = NULL, healthcheck = NULL, args_escaped = NULL,
      image = NULL, volumes = NULL, working_dir = NULL,
      entrypoint = NULL, network_disabled = NULL,
      mac_address = NULL, on_build = NULL, labels = NULL,
      stop_signal = NULL, stop_timeout = NULL, shell = NULL)

Arguments:

  • repo: Repository name for the created image

  • tag: Tag name for the create image

  • author: Author of the image (e.g., John Hannibal Smith <hannibal@a-team.com>)

  • changes: Dockerfile instructions to apply while committing

  • comment: Commit message

  • pause: Whether to pause the container before committing

  • hostname: The hostname to use for the container, as a valid RFC 1123 hostname.

  • domainname: The domain name to use for the container.

  • user: The user that commands are run as inside the container.

  • attach_stdin: Whether to attach to stdin.

  • attach_stdout: Whether to attach to stdout.

  • attach_stderr: Whether to attach to stderr.

  • exposed_ports: A character vector of port mappings between the container and host, in (1) the form <host>:<container> (e.g., 10080:80 to map the container's port 80 to the host's port 10080), <ip>:<host>:<container> to bind a specific host interface as well as a port (e.g., you can use localhost or 127.0.0.1 for the first element), (3) form <port> to map the containers port to a random available port on the host s shorthand for <port>:<port>, or (3) a single logical value TRUE indicating to map all container ports to random available ports on the host. You can use the $ports() method in the docker_container object to query the port mapping of a running container. Multiple values can be provided to map multiple ports to the host (e.g., c("80", "443:443").

  • tty: Attach standard streams to a TTY, including stdin if it is not closed.

  • open_stdin: Open stdin

  • stdin_once: Close stdin after one attached client disconnects

  • env: A list of environment variables to set inside the container in the form ["VAR=value", ...]. A variable without = is removed from the environment, rather than to have an empty value.

  • cmd: Command to run specified as a string or an array of strings.

  • healthcheck: A test to perform to check that the container is healthy.

  • args_escaped: Command is already escaped (Windows only)

  • image: The name of the image to use when creating the container

  • volumes: A character vector of mappings of mount points on the host (or in volumes) to paths on the container. Each element must be of the form <path_host>:<path_container>, possibly followed by :ro for read-only mappings (i.e., the same syntax as the docker command line client). docker_volume objects have a $map method to help with generating these paths for volume mappings.

  • working_dir: The working directory for commands to run in.

  • entrypoint: The entry point for the container as a string or an array of strings.

    If the array consists of exactly one empty string ([""]) then the entry point is reset to system default (i.e., the entry point used by docker when there is no ENTRYPOINT instruction in the Dockerfile).

  • network_disabled: Disable networking for the container.

  • mac_address: MAC address of the container.

  • on_build: ONBUILD metadata that were defined in the image's Dockerfile.

  • labels: User-defined key/value metadata.

  • stop_signal: Signal to stop a container as a string or unsigned integer.

  • stop_timeout: Timeout to stop a container in seconds.

  • shell: Shell for when RUN, CMD, and ENTRYPOINT uses a shell.

cp_in

Copy files or directory into the container. This function tries to follow the same semantics as the command line docker cp command.

Usage:

  cp_in(src, dest)

Arguments:

  • src: File or directory to copy into the container.

  • dest: Destination within the container. This must be a single path.

cp_out

Copy files or directories from the container. This function tries to follow the same semantics as the command line docker cp command.

Usage:

  cp_out(src, dest)

Arguments:

  • src: File or directory within the container to copy to the host.

  • dest: Destination on the host. This must be a single path.

container_changes

Get changes on a container's filesystem. Returns which files in a container's filesystem have been added, deleted, or modified. The Kind of modification can be one of:

  • 0: Modified

  • 1: Added

  • 2: Deleted. Similar to the cli command docker diff or docker container diff.

Usage:

  container_changes()
exec

Create and run an exec instance. Run a command inside a running container. Similar to the cli command docker exec.

Usage:

  exec(cmd, stdin = NULL, stdout = TRUE, stderr = TRUE,
      detach_keys = NULL, tty = NULL, env = NULL,
      privileged = NULL, user = NULL, detach = FALSE,
      stream = stdout())

Arguments:

  • cmd: Command to run, as a string or array of strings.

  • stdin: Attach to stdin of the exec command.

  • stdout: Attach to stdout of the exec command.

  • stderr: Attach to stderr of the exec command.

  • detach_keys: Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.

  • tty: Allocate a pseudo-TTY.

  • env: A list of environment variables in the form ["VAR=value", ...].

  • privileged: Runs the exec process with extended privileges.

  • user: The user, and optionally, group to run the exec process inside the container. Format is one of: user, user:group, uid, or uid:gid.

  • detach: Detach from the command.

  • stream: The stream to send output to. Options here are (1) a connection object (e.g. stdout(), stderr() or a writable open file connection object, (2) a scalar character indicating a filename to write to, or (3) FALSE or NULL to disable any output.

exec_create

Create an exec instance. Run a command inside a running container. Similar to the cli command docker exec.

Usage:

  exec_create(cmd, stdin = NULL, stdout = TRUE, stderr = TRUE,
      detach_keys = NULL, tty = NULL, env = NULL,
      privileged = NULL, user = NULL)

Arguments:

  • cmd: Command to run, as a string or array of strings.

  • stdin: Attach to stdin of the exec command.

  • stdout: Attach to stdout of the exec command.

  • stderr: Attach to stderr of the exec command.

  • detach_keys: Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.

  • tty: Allocate a pseudo-TTY.

  • env: A list of environment variables in the form ["VAR=value", ...].

  • privileged: Runs the exec process with extended privileges.

  • user: The user, and optionally, group to run the exec process inside the container. Format is one of: user, user:group, uid, or uid:gid.

container_export

Export a container. Export the contents of a container as a tarball. Similar to the cli command docker export or docker container export.

Usage:

  container_export()
container_archive

Get an archive of a filesystem resource in a container. Get a tar archive of a resource in the filesystem of container id.

Usage:

  container_archive(path, dest)

Arguments:

  • path: Resource in the container's filesystem to archive.

  • dest: Destination for the archive. Must be either a scalar character (representing a filename) or NULL, in which case a raw vector is returned.

help

Display help for this object

Usage:

  help(help_type = getOption("help_type"))

Arguments:

  • help_type: Passed to utils::help, can be one of "text", "html" or "pdf" (or an abbreviation). By default it uses the value getOption("help_type") and should follow the same behaviour as other R help (e.g., using "?")

id

Return the container's id

Usage:

  id()
image

Return the image for this container, as a docker_image object.

Usage:

  image()
inspect

Return detailed information about this container. Similar to the cli command docker container inspect.

Usage:

  inspect(reload = TRUE)

Arguments:

  • reload: Logical scalar, indicating if the information should be refreshed from the daemon. This is useful to set to FALSE after a container has been removed.

container_kill

Kill a container. Send a POSIX signal to a container, defaulting to killing to the container. Similar to the cli command docker kill or docker container kill.

Usage:

  container_kill(signal = NULL)

Arguments:

  • signal: Signal to send to the container as an integer or string (e.g. SIGINT)

labels

Return labels for this container

Usage:

  labels(reload = TRUE)

Arguments:

  • reload: Logical scalar, indicating if the information should be refreshed from the daemon. This is useful to set to FALSE after a container has been removed.

container_logs

Get container logs. Get stdout and stderr logs from a container.

Note: This endpoint works only for containers with the json-file or journald logging driver. Similar to the cli command docker logs or docker container logs.

Usage:

  container_logs(follow = NULL, stdout = TRUE, stderr = TRUE,
      since = NULL, timestamps = NULL, tail = NULL,
      stream = stdout())

Arguments:

  • follow: Return the logs as a stream.

    This will return a 101 HTTP response with a Connection: upgrade header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, hrefhttps://docs.docker.com/engine/api/1.29/#operation/ContainerAttachsee the documentation for the attach endpoint.

  • stdout: Return logs from stdout

  • stderr: Return logs from stderr

  • since: Only return logs since this time, as a UNIX timestamp

  • timestamps: Add timestamps to every log line

  • tail: Only return this number of log lines from the end of the logs. Specify as an integer or all to output all log lines.

  • stream: The stream to send output to. Options here are (1) a connection object (e.g. stdout(), stderr() or a writable open file connection object, (2) a scalar character indicating a filename to write to, or (3) FALSE or NULL to disable any output.

name

Return name for this container

Usage:

  name()
container_path_stat

Get information about files in a container. A response header X-Docker-Container-Path-Stat is return containing a base64 - encoded JSON object with some filesystem header information about the path.

Usage:

  container_path_stat(path)

Arguments:

  • path: Resource in the container's filesystem to archive.

container_pause

Pause a container. Use the cgroups freezer to suspend all processes in a container.

Traditionally, when suspending a process the SIGSTOP signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. Similar to the cli command docker pause or docker container pause.

Usage:

  container_pause()
ports

Return a data.frame of information about ports opened by this container. This is particularly useful in a container started with ports = TRUE, where container ports are mapped to random ports on the host. Similar to the cli command docker container port.

Usage:

  ports(reload = TRUE)

Arguments:

  • reload: Logical scalar, indicating if the information should be refreshed from the daemon. This is useful to set to FALSE after a container has been removed.

container_import

Extract an archive of files or folders to a directory in a container. Upload a tar archive to be extracted to a path in the filesystem of container id.

Usage:

  container_import(src, path, no_overwrite_dir_non_dir = NULL)

Arguments:

  • src: The input stream must be a tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

  • path: Path to a directory in the container to extract the archive's contents into.

  • no_overwrite_dir_non_dir: If '1', 'true', or 'True' then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa.

reload

Refresh infomation on the container from the server, returning $inspect() invisibly.

Usage:

  reload()
container_delete

Remove a container. Similar to the cli command docker rm or docker container rm.

Usage:

  container_delete(delete_volumes = NULL, force = NULL,
      link = NULL)

Arguments:

  • delete_volumes: Remove the volumes associated with the container.

  • force: If the container is running, kill it before removing it.

  • link: Remove the specified link associated with the container.

container_rename

Rename a container. Similar to the cli command docker rename or docker container rename.

Usage:

  container_rename(name)

Arguments:

  • name: New name for the container

container_resize

Resize a container TTY. Resize the TTY for a container. You must restart the container for the resize to take effect.

Usage:

  container_resize(h = NULL, w = NULL)

Arguments:

  • h: Height of the tty session in characters

  • w: Width of the tty session in characters

container_restart

Restart a container. Similar to the cli command docker restart or docker container restart.

Usage:

  container_restart(t = NULL)

Arguments:

  • t: Number of seconds to wait before killing the container

container_start

Start a container. Similar to the cli command docker start or docker container start.

Usage:

  container_start(detach_keys = NULL)

Arguments:

  • detach_keys: Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.

container_stats

Get container stats based on resource usage. This endpoint returns a live stream of a container's resource usage statistics.

The precpu_stats is the CPU statistic of last read, which is used for calculating the CPU usage percentage. It is not the same as the cpu_stats field.

If either precpu_stats.online_cpus or cpu_stats.online_cpus is nil then for compatibility with older daemons the length of the corresponding cpu_usage.percpu_usage array should be used. Similar to the cli command docker stats or docker container stats.

Usage:

  container_stats()
status

Short status of the container ("running", "exited", etc).

Usage:

  status(reload = TRUE)

Arguments:

  • reload: Refresh container data?

container_stop

Stop a container. Similar to the cli command docker stop or docker container stop.

Usage:

  container_stop(t = NULL)

Arguments:

  • t: Number of seconds to wait before killing the container

container_top

List processes running inside a container. On Unix systems, this is done by running the ps command. This endpoint is not supported on Windows. Similar to the cli command docker top or docker container top.

Usage:

  container_top(ps_args = NULL)

Arguments:

  • ps_args: The arguments to pass to ps. For example, aux

container_unpause

Unpause a container. Resume a container which has been paused. Similar to the cli command docker unpause or docker container unpause.

Usage:

  container_unpause()
container_update

Update a container. Change various configuration options of a container without having to recreate it. Similar to the cli command docker update or docker container update.

Usage:

  container_update(cpu_shares = NULL, memory = NULL,
      cgroup_parent = NULL, blkio_weight = NULL,
      blkio_weight_device = NULL, blkio_device_read_bps = NULL,
      blkio_device_write_bps = NULL,
      blkio_device_read_iops = NULL,
      blkio_device_write_iops = NULL, cpu_period = NULL,
      cpu_quota = NULL, cpu_realtime_period = NULL,
      cpu_realtime_runtime = NULL, cpuset_cpus = NULL,
      cpuset_mems = NULL, devices = NULL,
      device_cgroup_rules = NULL, disk_quota = NULL,
      kernel_memory = NULL, memory_reservation = NULL,
      memory_swap = NULL, memory_swappiness = NULL,
      nano_cpus = NULL, oom_kill_disable = NULL,
      pids_limit = NULL, ulimits = NULL, cpu_count = NULL,
      cpu_percent = NULL, io_maximum_iops = NULL,
      io_maximum_bandwidth = NULL, restart_policy = NULL)

Arguments:

  • cpu_shares: An integer value representing this container's relative CPU weight versus other containers.

  • memory: Memory limit in bytes.

  • cgroup_parent: Path to cgroups under which the container's cgroup is created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups are created if they do not already exist.

  • blkio_weight: Block IO weight (relative weight).

  • blkio_weight_device: Block IO weight (relative device weight) in the form [{"Path": "device_path", "Weight": weight}].

  • blkio_device_read_bps: Limit read rate (bytes per second) from a device, in the form [{"Path": "device_path", "Rate": rate}].

  • blkio_device_write_bps: Limit write rate (bytes per second) to a device, in the form [{"Path": "device_path", "Rate": rate}].

  • blkio_device_read_iops: Limit read rate (IO per second) from a device, in the form [{"Path": "device_path", "Rate": rate}].

  • blkio_device_write_iops: Limit write rate (IO per second) to a device, in the form [{"Path": "device_path", "Rate": rate}].

  • cpu_period: The length of a CPU period in microseconds.

  • cpu_quota: Microseconds of CPU time that the container can get in a CPU period.

  • cpu_realtime_period: The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.

  • cpu_realtime_runtime: The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.

  • cpuset_cpus: CPUs in which to allow execution (e.g., 0-3, 0,1)

  • cpuset_mems: Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.

  • devices: A list of devices to add to the container.

  • device_cgroup_rules: a list of cgroup rules to apply to the container

  • disk_quota: Disk limit (in bytes).

  • kernel_memory: Kernel memory limit in bytes.

  • memory_reservation: Memory soft limit in bytes.

  • memory_swap: Total memory limit (memory + swap). Set as -1 to enable unlimited swap.

  • memory_swappiness: Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.

  • nano_cpus: CPU quota in units of 10<sup>-9</sup> CPUs.

  • oom_kill_disable: Disable OOM Killer for the container.

  • pids_limit: Tune a container's pids limit. Set -1 for unlimited.

  • ulimits: A list of resource limits to set in the container. For example: {"Name": "nofile", "Soft": 1024, "Hard": 2048}"

  • cpu_count: The number of usable CPUs (Windows only).

    On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is CPUCount first, then CPUShares, and CPUPercent last.

  • cpu_percent: The usable percentage of the available CPUs (Windows only).

    On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is CPUCount first, then CPUShares, and CPUPercent last.

  • io_maximum_iops: Maximum IOps for the container system drive (Windows only)

  • io_maximum_bandwidth: Maximum IO in bytes per second for the container system drive (Windows only)

  • restart_policy: The behavior to apply when the container exits. The default is not to restart.

    An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.

container_wait

Wait for a container. Block until a container stops, then returns the exit code. Similar to the cli command docker wait or docker container wait.

Usage:

  container_wait()

See also

docker_container_collection for other container management methods.