class Docker::API::Image

This class represents the Docker API endpoints regarding images. @see docs.docker.com/engine/api/v1.40/#tag/Image

Public Instance Methods

build(path, params = {}) click to toggle source

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

Docker API: POST /build @see docs.docker.com/engine/api/v1.40/#operation/ImageBuild

@param path [String]: Path to the tar file. @param params [Hash]: Parameters that are appended to the URL. @param authentication [Hash]: Authentication parameters. @param &block: Replace the default output to stdout behavior.

# 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 = {}) click to toggle source

Create a new image from a container.

Docker API: POST /commit @see docs.docker.com/engine/api/v1.40/#operation/ImageCommit

@param params [Hash]: Parameters that are appended to the URL. @param body [Hash]: Request body to be sent as json.

# 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 = {}) click to toggle source

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

Docker API: POST /images/create @see docs.docker.com/engine/api/v1.40/#operation/ImageCreate

@param params [Hash]: Parameters that are appended to the URL. @param authentication [Hash]: Authentication parameters. @param &block: Replace the default output to stdout behavior.

# 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 = {}) click to toggle source

Delete builder cache.

Docker API: POST /build/prune @see docs.docker.com/engine/api/v1.40/#operation/BuildPrune

@param params [Hash]: Parameters that are appended to the URL.

# File lib/docker/api/image.rb, line 205
def delete_cache params = {}
    @connection.post(build_path("/build/prune", params))
end
details(name) click to toggle source

Return low-level information about an image.

Docker API: GET /images/{name}/json @see docs.docker.com/engine/api/v1.40/#operation/ImageInspect

@param name [String]: The ID or name of the image.

# File lib/docker/api/image.rb, line 13
def details name
    @connection.get("/images/#{name}/json")
end
distribution(name, authentication = {}) click to toggle source

Return image digest and platform information by contacting the registry.

Docker API: GET /distribution/{name}/json @see docs.docker.com/engine/api/v1.40/#tag/Distribution

@param name [String]: The ID or name of the image. @param authentication [Hash]: Authentication parameters.

# 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) click to toggle source

Export an image.

Docker API: GET /images/{name}/get @see docs.docker.com/engine/api/v1.40/#operation/ImageGet

@param name [String]: The ID or name of the image. @param path [String]: Path to the exported file. @param &block: Replace the default file writing behavior.

# 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) click to toggle source

Return parent layers of an image.

Docker API: GET /images/{name}/history @see docs.docker.com/engine/api/v1.40/#operation/ImageHistory

@param name [String]: The ID or name of the image.

# File lib/docker/api/image.rb, line 38
def history name
    @connection.get("/images/#{name}/history")
end
import(path, params = {}) click to toggle source

Import images.

Docker API: POST /images/load @see docs.docker.com/engine/api/v1.40/#operation/ImageLoad

@param name [String]: The ID or name of the image. @param params [Hash]: Parameters that are appended to the URL.

# File lib/docker/api/image.rb, line 122
def import path, params = {}
    default_reader(path, build_path("/images/load", params))
end
list(params = {}) click to toggle source

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 @see docs.docker.com/engine/api/v1.40/#operation/ImageList

@param params [Hash]: Parameters that are appended to the URL.

# File lib/docker/api/image.rb, line 49
def list params = {}
    @connection.get(build_path("/images/json", params)) 
end
prune(params = {}) click to toggle source

Delete unused images.

Docker API: POST /images/prune @see docs.docker.com/engine/api/v1.40/#operation/ImagePrune

@param params [Hash]: Parameters that are appended to the URL.

# File lib/docker/api/image.rb, line 83
def prune params = {}
    @connection.post(build_path("/images/prune", params))
end
push(name, params = {}) click to toggle source

Push an image to a registry.

Docker API: POST /images/{name}/push @see docs.docker.com/engine/api/v1.40/#operation/ImagePush

@param name [String]: The ID or name of the image. @param params [Hash]: Parameters that are appended to the URL. @param authentication [Hash]: Authentication parameters.

# 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 = {}) click to toggle source

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} @see docs.docker.com/engine/api/v1.40/#operation/ImageDelete

@param name [String]: The ID or name of the image. @param params [Hash]: Parameters that are appended to the URL.

# File lib/docker/api/image.rb, line 97
def remove name, params = {}
    @connection.delete(build_path("/images/#{name}", params))
end
tag(name, params = {}) click to toggle source

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

Docker API: POST /images/{name}/tag @see docs.docker.com/engine/api/v1.40/#operation/ImageTag

@param name [String]: The ID or name of the image. @param params [Hash]: Parameters that are appended to the URL.

# File lib/docker/api/image.rb, line 72
def tag name, params = {}
    @connection.post(build_path("/images/#{name}/tag", params))
end