Management commands for working with docker images

Methods for working with docker images. This object is $image within a docker_client object.

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_build

Build an image. Build an image from a tar archive with a Dockerfile in it.

The Dockerfile specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the dockerfile parameter. See the Dockerfile reference for more information.

The Docker daemon performs a preliminary validation of the Dockerfile before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed. Similar to the cli command docker build or docker image build.

Usage:

  image_build(context, dockerfile = NULL, tag = NULL,
      extrahosts = NULL, remote = NULL, q = NULL,
      nocache = NULL, cachefrom = NULL, pull = NULL, rm = NULL,
      forcerm = NULL, memory = NULL, memswap = NULL,
      cpushares = NULL, cpusetcpus = NULL, cpuperiod = NULL,
      cpuquota = NULL, buildargs = NULL, shmsize = NULL,
      squash = NULL, labels = NULL, networkmode = NULL,
      registry_config = NULL, stream = stdout())

Arguments:

context: A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.
dockerfile: Path within the build context to the Dockerfile. This is ignored if remote is specified and points to an external Dockerfile.
tag: A name and optional tag to apply to the image in the name:tag format. If you omit the tag the default latest value is assumed. You can provide a vector of mutiple tags here.
extrahosts: Extra hosts to add to /etc/hosts
remote: A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file's contents are placed into a file called Dockerfile and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the dockerfile parameter is also specified, there must be a file with the corresponding path inside the tarball.
q: Suppress verbose build output.
nocache: Do not use the cache when building the image.
cachefrom: JSON array of images used for build cache resolution.
pull: Attempt to pull the image even if an older image exists locally.
rm: Remove intermediate containers after a successful build.
forcerm: Always remove intermediate containers, even upon failure.
memory: Set memory limit for build.
memswap: Total memory (memory + swap). Set as -1 to disable swap.
cpushares: CPU shares (relative weight).
cpusetcpus: CPUs in which to allow execution (e.g., 0-3, 0,1).
cpuperiod: The length of a CPU period in microseconds.
cpuquota: Microseconds of CPU time that the container can get in a CPU period.
buildargs: JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the Dockerfile RUN instruction, or for variable expansion in other Dockerfile instructions. This is not meant for passing secret values. Read more about the buildargs instruction.
shmsize: Size of /dev/shm in bytes. The size must be greater than 0. If omitted the system uses 64MB.
squash: Squash the resulting images layers into a single layer. (Experimental release only.)
labels: Arbitrary key/value labels to set on the image, as a JSON map of string pairs.
networkmode: Sets the networking mode for the run commands during build. Supported standard values are: bridge, host, none, and container:<name|id>. Any other value is taken as a custom network's name to which this container should connect to.
registry_config: This is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.

The key is a registry URL, and the value is an auth configuration object, hrefhttps://docs.docker.com/engine/api/1.29/#section/Authenticationas described in the authentication section. For example:
```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```
Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a https:// prefix and a /v1/ suffix even though Docker will prefer to use the v2 registry API.
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.

image_build_clean

Delete builder cache. Unimplemented, as 'image_build_clean' (POST /build/prune) requires docker API version at least 1.31 (version 1.29 used)

Usage:

  image_build_clean(...)

Arguments:

...: Ignored in this version

image_export

Export several images. Get a tarball containing all images and metadata for several image repositories.

For each value of the names parameter: if it is a specific name and tag (e.g. ubuntu:latest), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see hrefhttps://docs.docker.com/engine/api/1.29/#operation/ImageGetthe export image endpoint. Similar to the cli command docker image save.

Usage:

  image_export(names = NULL)

Arguments:

names: Image names to filter by

get

Get an image by name or id

Usage:

  get(id)

Arguments:

id: A scalar character with the image's name or id (abbreviations of the id are allowed and will be resolved by the docker daemon).

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

image_import

Import images. Load a set of images and tags into a repository.

For details on the format, see hrefhttps://docs.docker.com/engine/api/1.29/#operation/ImageGetthe export image endpoint. Similar to the cli command docker image import.

Usage:

  image_import(images_tarball = NULL, quiet = NULL)

Arguments:

images_tarball: Tar archive containing images
quiet: Suppress progress details during load.

image_list

List Images. Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image. Similar to the cli command docker images or docker image list.

Usage:

  image_list(all = NULL, filters = NULL, digests = NULL)

Arguments:

all: Show all images. Only images from a final layer (no children) are shown by default.
filters: A named character vector of filters to process on the images list. Available filters:
- before=(<image-name>[:<tag>], <image id> or <image@digest>)
- dangling=true
- label=key or label="key=value" of an image label
- reference=(<image-name>[:<tag>])
- since=(<image-name>[:<tag>], <image id> or <image@digest>)
digests: Show digest information as a RepoDigests field on each image.

image_prune

Delete unused images. Similar to the cli command docker image prune.

Usage:

  image_prune(filters = NULL)

Arguments:

filters: Filters to process on the prune list, as a named character vector. Available filters:
- dangling=<boolean> When set to true (or 1), prune only unused and untagged images. When set to false (or 0), all unused images are pruned.
- until=<string> Prune images created before this timestamp. The <timestamp> can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the daemon machine's time.

image_create

Create an image. Create an image by either pulling it from a registry or importing it. Similar to the cli command docker pull or docker image pull.

Usage:

  image_create(name, tag = NULL, stream = stdout())

Arguments:

name: Name of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.
tag: Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.
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.

image_push

Push an image. Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, registry.example.com/myimage:latest.

The push is cancelled if the HTTP connection is closed. Similar to the cli command docker push or docker image push.

Usage:

  image_push(name, stream = stdout())

Arguments:

name: Image name or ID.
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.

image_delete

Remove an image. Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build. Similar to the cli command docker rmi or docker image rm.

Usage:

  image_delete(name, force = NULL, noprune = NULL)

Arguments:

name: Image name or ID
force: Remove the image even if it is being used by stopped containers or has other tags
noprune: Do not delete untagged parent images

image_search

Search images. Search for an image on Docker Hub. Similar to the cli command docker search.

Usage:

  image_search(term, limit = NULL, filters = NULL)

Arguments:

term: Term to search
limit: Maximum number of results to return
filters: A named character vector of filters to process on the images list. Available filters:
- is-automated=(true|false)
- is-official=(true|false)
- stars=<number> Matches images that has at least 'number' stars.

Details

Methods

See also