Class: DockerEngine::Resources::Images

Inherits:
Object
  • Object
show all
Defined in:
lib/docker_engine/resources/images.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Images

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Images.

Parameters:



671
672
673
 
# File 'lib/docker_engine/resources/images.rb', line 671

def initialize(client:)
  @client = client
end

Instance Method Details

#build(body:, buildargs: nil, cachefrom: nil, cpuperiod: nil, cpuquota: nil, cpusetcpus: nil, cpushares: nil, dockerfile: nil, extrahosts: nil, forcerm: nil, labels: nil, memory: nil, memswap: nil, networkmode: nil, nocache: nil, outputs: nil, platform: nil, pull: nil, q: nil, remote: nil, rm: nil, shmsize: nil, squash: nil, t: nil, target: nil, version: nil, x_registry_config: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::ImageBuildParams for more details.

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.

*(Experimen

Parameters:

  • body (Pathname, StringIO, IO, String, DockerEngine::FilePart) —

    Body param

  • buildargs (String) —

    Query param: JSON map of string pairs for build-time variables. Users pass these

  • cachefrom (String) —

    Query param: JSON array of images used for build cache resolution.

  • cpuperiod (Integer) —

    Query param: The length of a CPU period in microseconds.

  • cpuquota (Integer) —

    Query param: Microseconds of CPU time that the container can get in a CPU period

  • cpusetcpus (String) —

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

  • cpushares (Integer) —

    Query param: CPU shares (relative weight).

  • dockerfile (String) —

    Query param: Path within the build context to the Dockerfile. This is ignored

  • extrahosts (String) —

    Query param: Extra hosts to add to /etc/hosts

  • forcerm (Boolean) —

    Query param: Always remove intermediate containers, even upon failure.

  • labels (String) —

    Query param: Arbitrary key/value labels to set on the image, as a JSON map of st

  • memory (Integer) —

    Query param: Set memory limit for build.

  • memswap (Integer) —

    Query param: Total memory (memory + swap). Set as -1 to disable swap.

  • networkmode (String) —

    Query param: Sets the networking mode for the run commands during build. Support

  • nocache (Boolean) —

    Query param: Do not use the cache when building the image.

  • outputs (String) —

    Query param: BuildKit output configuration in the format of a stringified JSON a

  • platform (String) —

    Query param: Platform in the format os[/arch[/variant]]

  • pull (String) —

    Query param: Attempt to pull the image even if an older image exists locally.

  • q (Boolean) —

    Query param: Suppress verbose build output.

  • remote (String) —

    Query param: A Git repository URI or HTTP/HTTPS context URI. If the URI points t

  • rm (Boolean) —

    Query param: Remove intermediate containers after a successful build.

  • shmsize (Integer) —

    Query param: Size of /dev/shm in bytes. The size must be greater than 0. If om

  • squash (Boolean) —

    Query param: Squash the resulting images layers into a single layer.

  • t (String) —

    Query param: A name and optional tag to apply to the image in the name:tag for

  • target (String) —

    Query param: Target build stage

  • version (Symbol, DockerEngine::Models::ImageBuildParams::Version) —

    Query param: Version of the builder backend to use.

  • x_registry_config (String) —

    Header param: This is a base64-encoded JSON object with auth configurations for

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/docker_engine/resources/images.rb', line 154

def build(params)
  parsed, options = DockerEngine::ImageBuildParams.dump_request(params)
  query_params =
    [
      :buildargs,
      :cachefrom,
      :cpuperiod,
      :cpuquota,
      :cpusetcpus,
      :cpushares,
      :dockerfile,
      :extrahosts,
      :forcerm,
      :labels,
      :memory,
      :memswap,
      :networkmode,
      :nocache,
      :outputs,
      :platform,
      :pull,
      :q,
      :remote,
      :rm,
      :shmsize,
      :squash,
      :t,
      :target,
      :version
    ]
  @client.request(
    method: :post,
    path: "build",
    query: parsed.slice(*query_params),
    headers: {
      "content-type" => "application/octet-stream",
      **parsed.except(:body, *query_params)
    }.transform_keys(
      x_registry_config: "x-registry-config"
    ),
    body: parsed[:body],
    model: NilClass,
    options: options
  )
end

#build_prune(all: nil, filters: nil, max_used_space: nil, min_free_space: nil, reserved_space: nil, request_options: {}) ⇒ DockerEngine::Models::ImageBuildPruneResponse

Some parameter documentations has been truncated, see Models::ImageBuildPruneParams for more details.

Delete builder cache

Parameters:

  • all (Boolean) —

    Remove all types of build cache

  • filters (String) —

    A JSON encoded value of the filters (a map[string][]string) to

  • max_used_space (Integer) —

    Maximum amount of disk space allowed to keep for cache

  • min_free_space (Integer) —

    Target amount of free disk space after pruning

  • reserved_space (Integer) —

    Amount of disk space in bytes to keep for cache

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/docker_engine/resources/images.rb', line 222

def build_prune(params = {})
  parsed, options = DockerEngine::ImageBuildPruneParams.dump_request(params)
  @client.request(
    method: :post,
    path: "build/prune",
    query: parsed.transform_keys(
      max_used_space: "max-used-space",
      min_free_space: "min-free-space",
      reserved_space: "reserved-space"
    ),
    model: DockerEngine::Models::ImageBuildPruneResponse,
    options: options
  )
end

#commit(author: nil, changes: nil, comment: nil, container: nil, pause: nil, repo: nil, tag: nil, args_escaped: nil, attach_stderr: nil, attach_stdin: nil, attach_stdout: nil, cmd: nil, domainname: nil, entrypoint: nil, env: nil, exposed_ports: nil, healthcheck: nil, hostname: nil, image: nil, labels: nil, network_disabled: nil, on_build: nil, open_stdin: nil, shell: nil, stdin_once: nil, stop_signal: nil, stop_timeout: nil, tty: nil, user: nil, volumes: nil, working_dir: nil, request_options: {}) ⇒ DockerEngine::Models::ImageCommitResponse

Some parameter documentations has been truncated, see Models::ImageCommitParams for more details.

Create a new image from a container

Parameters:

  • author (String) —

    Query param: Author of the image (e.g., `John Hannibal Smith <[email protected]

  • changes (String) —

    Query param: Dockerfile instructions to apply while committing

  • comment (String) —

    Query param: Commit message

  • container (String) —

    Query param: The ID or name of the container to commit

  • pause (Boolean) —

    Query param: Whether to pause the container before committing

  • repo (String) —

    Query param: Repository name for the created image

  • tag (String) —

    Query param: Tag name for the create image

  • args_escaped (Boolean, nil) —

    Body param: Command is already escaped (Windows only)

  • attach_stderr (Boolean) —

    Body param: Whether to attach to stderr.

  • attach_stdin (Boolean) —

    Body param: Whether to attach to stdin.

  • attach_stdout (Boolean) —

    Body param: Whether to attach to stdout.

  • cmd (Array<String>) —

    Body param: Command to run specified as a string or an array of strings.

  • domainname (String) —

    Body param: The domain name to use for the container.

  • entrypoint (Array<String>) —

    Body param: The entry point for the container as a string or an array of strings

  • env (Array<String>) —

    Body param: A list of environment variables to set inside the container in the

  • exposed_ports (Hash{Symbol=>Object}, nil) —

    Body param: An object mapping ports to an empty object in the form:

  • healthcheck (DockerEngine::Models::Config::Healthcheck) —

    Body param: A test to perform to check that the container is healthy.

  • hostname (String) —

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

  • image (String) —

    Body param: The name (or reference) of the image to use when creating the contai

  • labels (Hash{Symbol=>String}) —

    Body param: User-defined key/value metadata.

  • network_disabled (Boolean, nil) —

    Body param: Disable networking for the container.

  • on_build (Array<String>, nil) —

    Body param: ONBUILD metadata that were defined in the image's Dockerfile.

  • open_stdin (Boolean) —

    Body param: Open stdin

  • shell (Array<String>, nil) —

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

  • stdin_once (Boolean) —

    Body param: Close stdin after one attached client disconnects

  • stop_signal (String, nil) —

    Body param: Signal to stop a container as a string or unsigned integer.

  • stop_timeout (Integer, nil) —

    Body param: Timeout to stop a container in seconds.

  • tty (Boolean) —

    Body param: Attach standard streams to a TTY, including stdin if it is not clo

  • user (String) —

    Body param: Commands run as this user inside the container. If omitted, commands

  • volumes (Hash{Symbol=>Object}) —

    Body param: An object mapping mount point paths inside the container to empty

  • working_dir (String) —

    Body param: The working directory for commands to run in.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/docker_engine/resources/images.rb', line 311

def commit(params = {})
  parsed, options = DockerEngine::ImageCommitParams.dump_request(params)
  query_params = [:author, :changes, :comment, :container, :pause, :repo, :tag]
  @client.request(
    method: :post,
    path: "commit",
    query: parsed.slice(*query_params),
    body: parsed.except(*query_params),
    model: DockerEngine::Models::ImageCommitResponse,
    options: options
  )
end

#delete(name, force: nil, noprune: nil, platforms: nil, request_options: {}) ⇒ Array<DockerEngine::Models::DeleteItem>

Some parameter documentations has been truncated, see Models::ImageDeleteParams for more details.

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.

Parameters:

  • name (String) —

    Image name or ID

  • force (Boolean) —

    Remove the image even if it is being used by stopped containers or has other tag

  • noprune (Boolean) —

    Do not delete untagged parent images

  • platforms (Array<String>) —

    Select platform-specific content to delete.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/docker_engine/resources/images.rb', line 64

def delete(name, params = {})
  parsed, options = DockerEngine::ImageDeleteParams.dump_request(params)
  @client.request(
    method: :delete,
    path: ["images/%1$s", name],
    query: parsed,
    model: DockerEngine::Internal::Type::ArrayOf[DockerEngine::DeleteItem],
    options: options
  )
end

#get(name, platform: nil, request_options: {}) ⇒ StringIO

Some parameter documentations has been truncated, see Models::ImageGetParams for more details.

Get a tarball containing all images and metadata for a repository.

If name is a specific name and tag (e.g. ubuntu:latest), then only that image (and its parents) are returned. If name is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the repositories file in the tarball, as there were no image names referenced.

Image tarball format

An image tarball contains Content as defined in the OCI Image Layout Specification.

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a repositories file at the root that contains a list of repository and tag names mapped to layer IDs.

{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}

Parameters:

  • name (String) —

    Image name or ID

  • platform (Array<String>) —

    JSON encoded OCI platform describing a platform which will be used

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (StringIO)

See Also:



365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/docker_engine/resources/images.rb', line 365

def get(name, params = {})
  parsed, options = DockerEngine::ImageGetParams.dump_request(params)
  @client.request(
    method: :get,
    path: ["images/%1$s/get", name],
    query: parsed,
    headers: {"accept" => "application/x-tar"},
    model: StringIO,
    options: options
  )
end

#get_all(names: nil, platform: nil, request_options: {}) ⇒ StringIO

Some parameter documentations has been truncated, see Models::ImageGetAllParams for more details.

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 the export image endpoint.

Parameters:

  • names (Array<String>) —

    Image names to filter by

  • platform (Array<String>) —

    JSON encoded OCI platform(s) which will be used to select the

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (StringIO)

See Also:



400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/docker_engine/resources/images.rb', line 400

def get_all(params = {})
  parsed, options = DockerEngine::ImageGetAllParams.dump_request(params)
  @client.request(
    method: :get,
    path: "images/get",
    query: parsed,
    headers: {"accept" => "application/x-tar"},
    model: StringIO,
    options: options
  )
end

#history(name, platform: nil, request_options: {}) ⇒ Array<DockerEngine::Models::HistoryItem>

Some parameter documentations has been truncated, see Models::ImageHistoryParams for more details.

Return parent layers of an image.

Parameters:

  • name (String) —

    Image name or ID

  • platform (String) —

    JSON-encoded OCI platform to select the platform-variant.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



428
429
430
431
432
433
434
435
436
437
 
# File 'lib/docker_engine/resources/images.rb', line 428

def history(name, params = {})
  parsed, options = DockerEngine::ImageHistoryParams.dump_request(params)
  @client.request(
    method: :get,
    path: ["images/%1$s/history", name],
    query: parsed,
    model: DockerEngine::Internal::Type::ArrayOf[DockerEngine::HistoryItem],
    options: options
  )
end

#inspect_(name, manifests: nil, request_options: {}) ⇒ DockerEngine::Models::Image

Return low-level information about an image.

Parameters:

  • name (String) —

    Image name or id

  • manifests (Boolean) —

    Include Manifests in the image summary.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



452
453
454
455
456
457
458
459
460
461
 
# File 'lib/docker_engine/resources/images.rb', line 452

def inspect_(name, params = {})
  parsed, options = DockerEngine::ImageInspectParams.dump_request(params)
  @client.request(
    method: :get,
    path: ["images/%1$s/json", name],
    query: parsed,
    model: DockerEngine::Image,
    options: options
  )
end

#list(all: nil, digests: nil, filters: nil, manifests: nil, shared_size: nil, request_options: {}) ⇒ Array<DockerEngine::Models::Summary>

Some parameter documentations has been truncated, see Models::ImageListParams for more details.

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

Parameters:

  • all (Boolean) —

    Show all images. Only images from a final layer (no children) are shown by defau

  • digests (Boolean) —

    Show digest information as a RepoDigests field on each image.

  • filters (String) —

    A JSON encoded value of the filters (a map[string][]string) to

  • manifests (Boolean) —

    Include Manifests in the image summary.

  • shared_size (Boolean) —

    Compute and show shared size as a SharedSize field on each image.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



29
30
31
32
33
34
35
36
37
38
 
# File 'lib/docker_engine/resources/images.rb', line 29

def list(params = {})
  parsed, options = DockerEngine::ImageListParams.dump_request(params)
  @client.request(
    method: :get,
    path: "images/json",
    query: parsed.transform_keys(shared_size: "shared-size"),
    model: DockerEngine::Internal::Type::ArrayOf[DockerEngine::Summary],
    options: options
  )
end

#load_(body:, platform: nil, quiet: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::ImageLoadParams for more details.

Load a set of images and tags into a repository.

For details on the format, see the export image endpoint.

Parameters:

  • body (Pathname, StringIO, IO, String, DockerEngine::FilePart) —

    Body param

  • platform (Array<String>) —

    Query param: JSON encoded OCI platform(s) which will be used to select the

  • quiet (Boolean) —

    Query param: Suppress progress details during load.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



483
484
485
486
487
488
489
490
491
492
493
494
 
# File 'lib/docker_engine/resources/images.rb', line 483

def load_(params)
  parsed, options = DockerEngine::ImageLoadParams.dump_request(params)
  @client.request(
    method: :post,
    path: "images/load",
    query: parsed.except(:body),
    headers: {"content-type" => "application/x-tar"},
    body: parsed[:body],
    model: NilClass,
    options: options
  )
end

#prune(filters: nil, request_options: {}) ⇒ DockerEngine::Models::ImagePruneResponse

Some parameter documentations has been truncated, see Models::ImagePruneParams for more details.

Delete unused images

Parameters:

  • filters (String) —

    Filters to process on the prune list, encoded as JSON (a map[string][]string).

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



510
511
512
513
514
515
516
517
518
519
 
# File 'lib/docker_engine/resources/images.rb', line 510

def prune(params = {})
  parsed, options = DockerEngine::ImagePruneParams.dump_request(params)
  @client.request(
    method: :post,
    path: "images/prune",
    query: parsed,
    model: DockerEngine::Models::ImagePruneResponse,
    options: options
  )
end

#pull(changes: nil, from_image: nil, from_src: nil, message: nil, platform: nil, repo: nil, tag: nil, body: nil, x_registry_auth: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::ImagePullParams for more details.

Pull or import an image.

Parameters:

  • changes (Array<String>) —

    Query param: Apply Dockerfile instructions to the image that is created,

  • from_image (String) —

    Query param: Name of the image to pull. If the name includes a tag or digest, sp

  • from_src (String) —

    Query param: Source to import. The value may be a URL from which the image can b

  • message (String) —

    Query param: Set commit message for imported image.

  • platform (String) —

    Query param: Platform in the format os[/arch[/variant]].

  • repo (String) —

    Query param: Repository name given to an image when it is imported. The repo may

  • tag (String) —

    Query param: Tag or digest. If empty when pulling an image, this causes all tags

  • body (String) —

    Body param

  • x_registry_auth (String) —

    Header param: A base64url-encoded auth configuration.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
 
# File 'lib/docker_engine/resources/images.rb', line 551

def pull(params = {})
  parsed, options = DockerEngine::ImagePullParams.dump_request(params)
  query_params = [:changes, :from_image, :from_src, :message, :platform, :repo, :tag]
  @client.request(
    method: :post,
    path: "images/create",
    query: parsed.slice(*query_params).transform_keys(from_image: "fromImage", from_src: "fromSrc"),
    headers: {
      "content-type" => "application/octet-stream",
      **parsed.except(:body, *query_params)
    }.transform_keys(
      x_registry_auth: "x-registry-auth"
    ),
    body: parsed[:body],
    model: NilClass,
    options: options
  )
end

#push(name, x_registry_auth:, platform: nil, tag: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::ImagePushParams for more details.

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.

Parameters:

  • name (String) —

    Path param: Name of the image to push. For example, `registry.example.com/myimag

  • x_registry_auth (String) —

    Header param: A base64url-encoded auth configuration.

  • platform (String) —

    Query param: JSON-encoded OCI platform to select the platform-variant to push.

  • tag (String) —

    Query param: Tag of the image to push. For example, latest. If no tag is provi

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



596
597
598
599
600
601
602
603
604
605
606
607
 
# File 'lib/docker_engine/resources/images.rb', line 596

def push(name, params)
  parsed, options = DockerEngine::ImagePushParams.dump_request(params)
  query_params = [:platform, :tag]
  @client.request(
    method: :post,
    path: ["images/%1$s/push", name],
    query: parsed.slice(*query_params),
    headers: parsed.except(*query_params).transform_keys(x_registry_auth: "x-registry-auth"),
    model: NilClass,
    options: options
  )
end

#search(term:, filters: nil, limit: nil, request_options: {}) ⇒ Array<DockerEngine::Models::ImageSearchResponseItem>

Some parameter documentations has been truncated, see Models::ImageSearchParams for more details.

Search for an image on Docker Hub.

Parameters:

  • term (String) —

    Term to search

  • filters (String) —

    A JSON encoded value of the filters (a map[string][]string) to process on the

  • limit (Integer) —

    Maximum number of results to return

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



627
628
629
630
631
632
633
634
635
636
 
# File 'lib/docker_engine/resources/images.rb', line 627

def search(params)
  parsed, options = DockerEngine::ImageSearchParams.dump_request(params)
  @client.request(
    method: :get,
    path: "images/search",
    query: parsed,
    model: DockerEngine::Internal::Type::ArrayOf[DockerEngine::Models::ImageSearchResponseItem],
    options: options
  )
end

#tag(name, repo: nil, tag: nil, request_options: {}) ⇒ nil

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

Parameters:

  • name (String) —

    Image name or ID to tag.

  • repo (String) —

    The repository to tag in. For example, someuser/someimage.

  • tag (String) —

    The name of the new tag.

  • request_options (DockerEngine::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



657
658
659
660
661
662
663
664
665
666
 
# File 'lib/docker_engine/resources/images.rb', line 657

def tag(name, params = {})
  parsed, options = DockerEngine::ImageTagParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["images/%1$s/tag", name],
    query: parsed,
    model: NilClass,
    options: options
  )
end