Create docker client

Source: R/docker_client.R

Create a docker client object, which allows you to interact with docker from R. The object has several methods that allow interaction with the docker daemon (for this object they are all "system" commands) and collections, which contains further methods. The client is structured similarly to the docker command line client, such that docker container create <args> in the command line becomes docker$container$create(...) in R (if the client is called R).

docker_client(
  ...,
  api_version = NULL,
  host = NULL,
  cert_path = NULL,
  tls_verify = NULL,
  machine = NULL,
  http_client_type = NULL,
  data_frame = NULL,
  quiet = FALSE,
  debug = NULL,
  ignore_environment = FALSE
)

Arguments

...

Reserved for future use. Passing in any unrecognised argument will throw an error. Part of the role of this argument is to force use of named arguments until the API is stabilised.

api_version

Version of the API to use when communicating with the docker daemon. The default value, NULL, detects the docker server API version and attempts to match it (this mirrors the default behaviour of the docker command line client). Alternatively, provide an API version number as a string or numeric_version object (supported between 1.25 and 1.39 ). The version 1.29 is the version used in most automated tests, and if problems are encountered, consider forcing this version).

host

The URL for the docker daemon. This can be a unix socket (e.g., unix:///var/run/docker.sock) on macOS/Linux, a named pipe (e.g., npipe:////./pipe/docker_engine) on Windows, or an http or https url (e.g., https://localhost:2376). If not given, we use the environment variable DOCKER_HOST, falling back on the default socket or named pipe (for macOS/unix and windows respectively).

cert_path

The path to a directory containing certificate files. If using an https url this is required. If not given, we use the environment variable DOCKER_CERT_PATH. This is ignored without warning if used with a socket or named pipe connection.

tls_verify

Logical, indicating if TLS should be verified. This is only used if using an https connection (i.e., host is a tcp/http/https url andcert_path is given). If not given, we use the environment variable DOCKER_TLS_VERIFY.

machine

Scalar character (if provided) indicating the name of a "docker machine" instance to use. If this is provided then docker-machine must be installed and the machine must exist and be running. stevedore will run docker-machine env machine to determine the environment variables to contact this machine and use these values for host, cert_path and tls_verify (silently ignoring any provided values). Carl Boettiger is working on a docker machine package for R that would make managing docker machines from R easier. As an alternative to this option, one can set docker-machine environment variables as described in docker-machine env before running R and they would be picked up as described above.

http_client_type

HTTP client type to use. The options are (currently) "curl", which uses the curl package (works over unix sockets and over TCP) and httppipe which works over unix sockets and windows named pipes, using the Docker SDK's pipe code via the httppipe package. Not all functionality is supported with the httppipe client. This option may eventually be moved into the ... argument as is not intended for end-user use; it is primarily intended for debugging in development (forcing the httppipe client where the curl client would ordinarily be preferred).

data_frame

Function, used to wrap data.frames returned. This may make output easier to consume. You might use tibble::as_tibble to return a tbl_df or datatable::as.data.table to return data.table objects. This will be applied to all data.frames after they are constructed, and so must take a single argument (the newly constructed data.frame) and return a new object that is largely compatible with data.frame. Another use for this would be to define a function data_frame = function(x) structure(x, class = c("foo", "data.frame")) to set the class of all returned data.frame objects to be "foo" as well and then defining a custom S3 print method for "foo" that limited the output.

quiet

Suppress informational messages.

debug

Enable http debugging (supported by the curl http driver only). Provide a connection object and http headers and content will be sent to it. Using debug = TRUE is equivalent to code = stdout(), while debug = FALSE is equivalent to debug = NULL (the default) which prevents debugging information being printed. This option can be used to write to a file by opening a writeable connection but care must be made not to close this connection because otherwise the curl requests may fail.

ignore_environment

Logical, indicating if environment variables (DOCKER_HOST, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY and DOCKER_API_VERSION) should be ignored (this has no effect if machine is specified).

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

Management commands

config

Manage config - see docker_config_collection

container

Manage container - see docker_container_collection

image

Manage image - see docker_image_collection

network

Manage network - see docker_network_collection

node

Manage node - see docker_node_collection

plugin

Manage plugin - see docker_plugin_collection

secret

Manage secret - see docker_secret_collection

service

Manage service - see docker_service_collection

swarm

Manage swarm - see docker_swarm_collection

task

Manage task - see docker_task_collection

types

Manage types - see docker_types

volume

Manage volume - see docker_volume_collection

Methods

api_version

Return the version of the API that the docker client is using to communicate with the server, as a string (e.g., "1.29")

Usage:

  api_version()
connection_info

Return information about the connection to the server.

Usage:

  connection_info()
cp

Copy a file or directory between the host filesystem and a running container. Like the command line, exactly one of from and to must be in the form <container>:<path> while the other must be in the form <path>. This wrapper is included for compatiblity with the docker command line and is available in a slightly more flexible form as cp_out and cp_in methods of a docker_container object. Similar to the cli command docker cp.

Usage:

  cp(src, dest)

Arguments:

  • src: The source file or directory. If on the host it may be a relative or an absolute path. If on the container then it must be of the form <container_id>:<path>; the container id can be an id (hex) or name.

  • dest: The destination file or directory, with the same pattern as from.

system_df

Get data usage information. Similar to the cli command docker system df.

Usage:

  system_df()
system_events

Monitor events. Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update

Images report these events: delete, import, load, pull, push, save, tag, untag

Volumes report these events: create, mount, unmount, destroy

Networks report these events: create, connect, disconnect, destroy

The Docker daemon reports these events: reload. Similar to the cli command docker events.

Usage:

  system_events(since = NULL, until = NULL, filters = NULL)

Arguments:

  • since: Show events created since this timestamp then stream new events.

  • until: Show events created until this timestamp then stop streaming.

  • filters: A named character vector of filters to process on the event list. Available filters:

    • container=<string> container name or ID

    • daemon=<string> daemon name or ID

    • event=<string> event type

    • image=<string> image name or ID

    • label=<string> image or container label

    • network=<string> network name or ID

    • plugin=<string> plugin name or ID

    • type=<string> object to filter by, one of container, image, volume, network, or daemon

    • volume=<string> volume name or ID

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 "?")

system_info

Get system information. Similar to the cli command docker info.

Usage:

  system_info()
system_auth

Check auth configuration. Validate credentials for a registry and, if available, get an identity token for accessing the registry without password. Similar to the cli command docker login.

Usage:

  system_auth(username = NULL, password = NULL, email = NULL,
      serveraddress = NULL)

Arguments:

  • username: For authentication to check

  • password: For authentication to check

  • email: For authentication to check

  • serveraddress: For authentication to check

system_ping

Ping. This is a dummy endpoint you can use to test if the server is accessible.

Usage:

  system_ping()
request

Interact directly with the Docker HTTP API. This might be useful for debugging or for trying out new/experimental docker features that have not yet made it into stevedore. This is most likely to be useful in conjunction with the Docker API docs; https://docs.docker.com/engine/api Each call will return a list with elements url (the used url), status_code (the HTTP status code), headers (a raw vector containing the returned headers) and content (a raw vector containing the content). The curl driver provides some other entries too.

Usage:

  request(verb, path, query = NULL, body = NULL,
      headers = NULL, stream = NULL)

Arguments:

  • verb: A HTTP verb (e.g., GET, POST) as a string. Will be converted to uppercase.

  • path: A path as a string, e.g., /version or /containers/json. Do not provide any hostname, and use an absoluate path.

  • query: Optionally, a named list of query parameters (e.g., list(limit = 10) as a query parameter for /containers/json).

  • body: Either a raw vector (e.g., a tar-ed image for POST /build) or a string representing json (e.g. for POST /containers/create).

  • headers: Headers to send with the request. The API does not use this extensively except for X-Registry-Auth for some endpoints.

  • stream: An R function to handle streaming output. If given then the function must take a single argument which will be a raw vector with the docker daemon's output. The function's return output is ignored so needs to do all actions via side effects.

system_version

Get version. Returns the version of Docker that is running and various information about the system that Docker is running on. Similar to the cli command docker version.

Usage:

  system_version()

Connection options

stevedore can connect to the docker daemon via a unix socket (this is the default set-up on Linux and macOS), over a named pipe (Windows 10 - see below) and https over a normal tcp connection (this is especially useful with docker-machine.

  1. If the machine argument is given then stevedore queries docker-machine for settings. If that command fails (e.g., there is no machine, docker-machine not installed) then that will cause an error. (Note that the docker-machine output does not include API version information so the api_version argument is relevant, but host, cert_path and tls_verify will be silently ignored if provided).

  2. The arguments host overrides the environment variable DOCKER_HOST, cert_path overrides DOCKER_CERT_PATH and tls_verify overrides DOCKER_TLS_VERIFY. If ignore_environment is TRUE then the environment variables are not used at all.

  3. if code is not provided by any of the above methods (machine, argument or environment variable) it will fall back on the default unix socket (var/run/docker.sock) on Linux/macOS or the default windows named pipe (npipe:////./pipe/docker_engine) on windows.

The API version is set by the api_version argument, which falls back on the environment variable DOCKER_API_VERSION (this is the same as the docker command line client and the python SDK). If neither are provided then stevedore will detect the API version being used by the daemon and match that (provided it falls within the range of versions supported by the package).

Examples

if (stevedore::docker_available()) {
  # Create a new client object:
  client <- stevedore::docker_client()

  # Version information for your docker daemon:
  client$version()

  # General information about your daemon:
  client$info()

  # Most of the interesting methods are within the collections.
  # For example, to see a summary of running containers:
  client$container$list()

  # (see ?docker_container) for more information.
}
#> Detected API version '1.41' is above max version '1.39'; downgrading
#> Detected API version '1.41' is above max version '1.39'; downgrading
#>  [1] id               names            image            image_id        
#>  [5] command          created          ports            size_rw         
#>  [9] size_root_fs     labels           state            status          
#> [13] host_config      network_settings mounts           name            
#> <0 rows> (or 0-length row.names)