Class: Docker::API::Images

Inherits:
Collection show all
Defined in:
lib/docker/api/collections/images.rb

Overview

The images on a daemon.

Examples:

client.images.pull("alpine:3.20", platform: "linux/arm64")
client.images.build(context: "./app", tag: "app:dev")

Instance Attribute Summary

Attributes inherited from Collection

#client

Instance Method Summary collapse

Methods inherited from Collection

#find, #initialize, #to_s

Constructor Details

This class inherits a constructor from Docker::API::Collection

Instance Method Details

#all(all: false, filters: nil, digests: false) ⇒ Array<Docker::API::Image>

List images.

Parameters:

  • all (Boolean) (defaults to: false) —

    include intermediate layers

  • filters (Hash, nil) (defaults to: nil) —

    daemon-side filters

  • digests (Boolean) (defaults to: false) —

    include repository digests

Returns:



20
21
22
23
 
# File 'lib/docker/api/collections/images.rb', line 20

def all(all: false, filters: nil, digests: false)
  operations.image_list(all: all, filters: filters, digests: digests)
    .json!.map { |payload| Image.new(client: client, raw: payload, partial: true) }
end

#build(context: nil, dockerfile: nil, tag: nil, platform: nil, nocache: false, rm: true, pull: false, buildargs: nil, labels: nil, target: nil) {|event| ... } ⇒ Docker::API::Image

Build an image.

The context may be a directory, which is tarred honouring its .dockerignore, or a Dockerfile given as a string for the common case of a short generated build with no accompanying files.

Examples:

Building from a directory

client.images.build(context: "./app", tag: "app:dev") do |event|
  print event["stream"]
end

Building from a Dockerfile in memory

client.images.build(dockerfile: "FROM alpine\nRUN apk add curl\n", tag: "curl:dev")

Parameters:

  • context (String, IO, nil) (defaults to: nil) —

    a directory path, or tar bytes

  • dockerfile (String, nil) (defaults to: nil) —

    Dockerfile contents, when there is no directory, or the name of the Dockerfile within the context

  • tag (String, nil) (defaults to: nil) —

    the reference to give the result

  • platform (String, Hash, nil) (defaults to: nil) —

    the platform to build for

  • nocache (Boolean) (defaults to: false) —

    ignore the layer cache

  • rm (Boolean) (defaults to: true) —

    remove intermediate containers

  • pull (Boolean) (defaults to: false) —

    always re-pull the base image

  • buildargs (Hash, nil) (defaults to: nil) —

    --build-arg values

  • labels (Hash, nil) (defaults to: nil) —

    labels for the resulting image

  • target (String, nil) (defaults to: nil) —

    which stage of a multi-stage build to stop at

Yield Parameters:

  • event (Hash) —

    build output as it arrives

Returns:

Raises:



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/docker/api/collections/images.rb', line 126

def build(context: nil, dockerfile: nil, tag: nil, platform: nil, nocache: false,
  rm: true, pull: false, buildargs: nil, labels: nil, target: nil, &block)
  archive, dockerfile_name = build_context(context, dockerfile)
  image_id = nil
  failure = nil

  stream = Stream::JSONLines.new do |event|
    image_id ||= event.dig("aux", "ID")
    failure ||= event["error"]
    block&.call(event)
  end

  operations.image_build(
    body: archive, content_type: "application/x-tar",
    t: tag, platform: Platform.string(platform), nocache: nocache, rm: rm, pull: pull,
    dockerfile: dockerfile_name, target: target,
    buildargs: buildargs, labels: labels
  ) { |chunk| stream << chunk }

  # The daemon reports build failures inside a 200 response rather than
  # as a status code, so a build that failed looks like a success to
  # anything that only checks HTTP.
  raise Error.new("image build failed: #{failure}", operation: "image_build") if failure

  get(built_reference(tag, image_id))
end

#ensure(reference, platform: nil, auth: nil) {|event| ... } ⇒ Docker::API::Image

Fetch an image, pulling it first if the daemon does not have it.

Parameters:

  • reference (String) —

    the image to ensure is present

  • platform (String, Hash, nil) (defaults to: nil) —

    the platform to select or pull

  • auth (String, nil) (defaults to: nil) —

    an X-Registry-Auth value

Yield Parameters:

  • event (Hash) —

    pull progress, when a pull is needed

Returns:



60
61
62
63
64
 
# File 'lib/docker/api/collections/images.rb', line 60

def ensure(reference, platform: nil, auth: nil, &block)
  get(reference, platform: platform)
rescue NotFound
  pull(reference, platform: platform, auth: auth, &block)
end

#exist?(name, platform: nil) ⇒ Boolean

Whether an image is present locally.

Parameters:

  • name (String) —

    a reference, id or digest

  • platform (String, nil) (defaults to: nil) —

    which platform to ask about

Returns:

  • (Boolean) 


47
48
49
50
51
 
# File 'lib/docker/api/collections/images.rb', line 47

def exist?(name, platform: nil)
  !get(name, platform: platform).nil?
rescue NotFound
  false
end

#get(name, platform: nil) ⇒ Docker::API::Image

Fetch one image.

Parameters:

  • name (String) —

    a reference, id or digest

  • platform (String, Hash, nil) (defaults to: nil) —

    which platform's image to describe, as "linux/arm64" or an OCI platform hash

Returns:

Raises:



32
33
34
35
36
37
38
39
40
 
# File 'lib/docker/api/collections/images.rb', line 32

def get(name, platform: nil)
  Image.new(
    client: client,
    # This endpoint wants the OCI object form, unlike pull and build,
    # which want the string. See Docker::API::Platform.
    raw: operations.image_inspect(name: name, platform: Platform.oci(platform)).json,
    partial: false
  )
end

#prune(filters: nil) ⇒ Hash

Remove unused images.

Parameters:

  • filters (Hash, nil) (defaults to: nil) —

    which images to consider

Returns:

  • (Hash) —

    what was deleted and how much space it freed



157
158
159
 
# File 'lib/docker/api/collections/images.rb', line 157

def prune(filters: nil)
  operations.image_prune(filters: filters).json
end

#pull(reference, platform: nil, auth: nil) {|event| ... } ⇒ Docker::API::Image

Pull an image from a registry.

Credentials are resolved for the registry in the reference, so pulling from two private registries in one process needs no setup between calls. Pass auth: to override.

Examples:

Watching progress

client.images.pull("alpine:3.20") { |event| puts event["status"] }

Parameters:

  • reference (String) —

    "alpine:3.20", "registry.io/team/app:1.0"

  • platform (String, Hash, nil) (defaults to: nil) —

    the platform to pull, as "linux/arm64" or an OCI platform hash

  • auth (String, nil) (defaults to: nil) —

    an X-Registry-Auth value

Yield Parameters:

  • event (Hash) —

    progress events as they arrive

Returns:



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/docker/api/collections/images.rb', line 81

def pull(reference, platform: nil, auth: nil, &block)
  repo, tag = Image.split_reference(reference)
  credentials = auth || Auth.resolve(Image.registry_for(repo))

  stream = block ? Stream::JSONLines.new(&block) : nil
  # Pull wants the string form; inspect below wants the object form.
  operations.image_create(
    from_image: repo, tag: tag, platform: Platform.string(platform),
    x_registry_auth: credentials
  ) { |chunk| stream << chunk if stream }

  # Reassembled rather than reusing the caller's string, because the tag
  # may have been defaulted to "latest" along the way -- and because a
  # digest has to go back together with "@" rather than ":".
  get(Image.join_reference(repo, tag), platform: platform)
end

#search(term, limit: nil, filters: nil) ⇒ Array<Hash>

Search Docker Hub.

Parameters:

  • term (String) —

    what to search for

  • limit (Integer, nil) (defaults to: nil) —

    how many results to return

  • filters (Hash, nil) (defaults to: nil) —

    search filters

Returns:

  • (Array<Hash>) 


167
168
169
 
# File 'lib/docker/api/collections/images.rb', line 167

def search(term, limit: nil, filters: nil)
  operations.image_search(term: term, limit: limit, filters: filters).json
end