Class: Docker::API::Image

Inherits:
Base
  • Object
show all
Defined in:
lib/docker/api/image.rb

Overview

This class represents the Docker API endpoints regarding images.

See Also:

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

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

Instance Method Details

#build(path, params = {}, authentication = {}, &block) ⇒ Object

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

Docker API: POST /build

Parameters:

  • path (String) —

    : Path to the tar file.

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

  • authentication (Hash) (defaults to: {}) —

    : Authentication parameters.

  • &block: —

    Replace the default output to stdout behavior.

Raises:

See Also:



185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/docker/api/image.rb', line 185

def build path, params = {}, authentication = {}, &block
    raise Docker::API::Error.new("Expected path or params[:remote]") unless path || params[:remote] 

    headers = {"Content-type": "application/x-tar"}
    headers.merge!({"X-Registry-Config": auth_encoder(authentication) }) if authentication.any?

    if path == nil and params.has_key? :remote
        response = @connection.request(method: :post, path: build_path("/build", params), headers: headers, response_block: block_given? ? block : default_streamer)
    else
        default_reader(path, build_path("/build", params), headers)
    end
end

#commit(params = {}, body = {}) ⇒ Object

Create a new image from a container.

Docker API: POST /commit

Parameters:

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

  • body (Hash) (defaults to: {}) —

    : Request body to be sent as json.

See Also:



148
149
150
151
152
 
# File 'lib/docker/api/image.rb', line 148

def commit params = {}, body = {}
    container = Docker::API::Container.new.details(params[:container])
    return container if [404, 301].include? container.status
    @connection.request(method: :post, path: build_path("/commit", params), headers: {"Content-Type": "application/json"}, body: container.json["Config"].merge(body).to_json)
end

#create(params = {}, authentication = {}, &block) ⇒ Object

Create an image by either pulling it from a registry or importing it.

Docker API: POST /images/create

Parameters:

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

  • authentication (Hash) (defaults to: {}) —

    : Authentication parameters.

  • &block: —

    Replace the default output to stdout behavior.

See Also:



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/docker/api/image.rb', line 163

def create params = {}, authentication = {}, &block
    request = {method: :post, path: build_path("/images/create", params), response_block: block_given? ? block : default_streamer }
    if params.has_key? :fromSrc and !params[:fromSrc].match(/^(http|https)/) # then it's using a tar file
        path = params[:fromSrc]
        params[:fromSrc] = "-"
        default_reader(path, build_path("/images/create", params))
    else
        request[:headers] = { "X-Registry-Auth" => auth_encoder(authentication) } if authentication.any?
        @connection.request(request)
    end
end

#delete_cache(params = {}) ⇒ Object

Delete builder cache.

Docker API: POST /build/prune

Parameters:

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

See Also:



205
206
207
 
# File 'lib/docker/api/image.rb', line 205

def delete_cache params = {}
    @connection.post(build_path("/build/prune", params))
end

#details(name) ⇒ Object

Return low-level information about an image.

Docker API: GET /images/name/json

Parameters:

  • name (String) —

    : The ID or name of the image.

See Also:



13
14
15
 
# File 'lib/docker/api/image.rb', line 13

def details name
    @connection.get("/images/#{name}/json")
end

#distribution(name, authentication = {}) ⇒ Object

Return image digest and platform information by contacting the registry.

Docker API: GET /distribution/name/json

Parameters:

  • name (String) —

    : The ID or name of the image.

  • authentication (Hash) (defaults to: {}) —

    : Authentication parameters.

See Also:



25
26
27
28
29
 
# File 'lib/docker/api/image.rb', line 25

def distribution name, authentication = {}
    request = {method: :get, path: "/distribution/#{name}/json"}
    request[:headers] = {"X-Registry-Auth" => auth_encoder(authentication)} if authentication.any?
    @connection.request(request)
end

#export(name, path, &block) ⇒ Object

Export an image.

Docker API: GET /images/name/get

Parameters:

  • name (String) —

    : The ID or name of the image.

  • path (String) —

    : Path to the exported file.

  • &block: —

    Replace the default file writing behavior.

See Also:



110
111
112
 
# File 'lib/docker/api/image.rb', line 110

def export name, path, &block
    @connection.request(method: :get, path: build_path("/images/#{name}/get") , response_block: block_given? ? block : default_writer(path))
end

#history(name) ⇒ Object

Return parent layers of an image.

Docker API: GET /images/name/history

Parameters:

  • name (String) —

    : The ID or name of the image.

See Also:



38
39
40
 
# File 'lib/docker/api/image.rb', line 38

def history name
    @connection.get("/images/#{name}/history")
end

#import(path, params = {}) ⇒ Object

Import images.

Docker API: POST /images/load

Parameters:

  • name (String) —

    : The ID or name of the image.

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

See Also:



122
123
124
 
# File 'lib/docker/api/image.rb', line 122

def import path, params = {}
    default_reader(path, build_path("/images/load", params))
end

#list(params = {}) ⇒ Object

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

Docker API: GET /images/json

Parameters:

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

See Also:



49
50
51
 
# File 'lib/docker/api/image.rb', line 49

def list params = {}
    @connection.get(build_path("/images/json", params)) 
end

#prune(params = {}) ⇒ Object

Delete unused images.

Docker API: POST /images/prune

Parameters:

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

See Also:



83
84
85
 
# File 'lib/docker/api/image.rb', line 83

def prune params = {}
    @connection.post(build_path("/images/prune", params))
end

#push(name, params = {}, authentication = {}) ⇒ Object

Push an image to a registry.

Docker API: POST /images/name/push

Parameters:

  • name (String) —

    : The ID or name of the image.

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

  • authentication (Hash) (defaults to: {}) —

    : Authentication parameters.

Raises:

See Also:



135
136
137
138
 
# File 'lib/docker/api/image.rb', line 135

def push name, params = {}, authentication = {}
    raise Docker::API::Error.new("Provide authentication parameters to push an image") unless authentication.any?
    @connection.request(method: :post, path: build_path("/images/#{name}/push", params), headers: { "X-Registry-Auth" => auth_encoder(authentication) } )
end

#remove(name, params = {}) ⇒ Object

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.

Docker API: DELETE /images/name

Parameters:

  • name (String) —

    : The ID or name of the image.

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

See Also:



97
98
99
 
# File 'lib/docker/api/image.rb', line 97

def remove name, params = {}
    @connection.delete(build_path("/images/#{name}", params))
end

#search(params = {}) ⇒ Object

Search for an image on Docker Hub.

Docker API: GET /images/search

Parameters:

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

See Also:



60
61
62
 
# File 'lib/docker/api/image.rb', line 60

def search params = {}
    @connection.get(build_path("/images/search", params)) 
end

#tag(name, params = {}) ⇒ Object

Tag an image so that it becomes part of a repository.

Docker API: POST /images/name/tag

Parameters:

  • name (String) —

    : The ID or name of the image.

  • params (Hash) (defaults to: {}) —

    : Parameters that are appended to the URL.

See Also:



72
73
74
 
# File 'lib/docker/api/image.rb', line 72

def tag name, params = {}
    @connection.post(build_path("/images/#{name}/tag", params))
end