Class: Docker::API::Client

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

Overview

A connection to one Docker daemon, and the way in to everything else.

A client owns its configuration and its connection. There is no global state behind it: two clients addressing two daemons share nothing, so a process can talk to a local daemon and a remote builder at the same time without either one noticing.

Examples:

The local daemon

client = Docker::API::Client.new
client.system.info["ServerVersion"]

A remote daemon over TLS

client = Docker::API::Client.new(
  url: "tcp://build.internal:2376",
  tls: { ca_file: "ca.pem", cert_file: "cert.pem", key_file: "key.pem" }
)

Reaching an endpoint with no ergonomic wrapper

client.operations.container_prune(filters: { "until" => ["24h"] })

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url: nil, tls: nil, api_version: :negotiate, logger: nil, read_timeout: 60, open_timeout: 10, transport: nil, env: ENV) ⇒ Client

Returns a new instance of Client.

Parameters:

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

    the daemon URL. Falls back to DOCKER_HOST, then to the platform's default socket.

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

    TLS material: :ca_file, :cert_file, :key_file, :verify. Falls back to DOCKER_CERT_PATH.

  • api_version (String, Symbol) (defaults to: :negotiate) —

    :negotiate to ask the daemon what it speaks, a version such as "1.44" to pin, or :none to send unprefixed paths

  • logger (Logger, nil) (defaults to: nil) —

    receives one debug line per request

  • read_timeout (Numeric) (defaults to: 60) —

    seconds to wait for response data

  • open_timeout (Numeric) (defaults to: 10) —

    seconds to wait for a connection

  • transport (Docker::API::Transport::Base, nil) (defaults to: nil) —

    a transport to use instead of building one from the URL. Mainly for tests, where Transport::Fake stands in for a daemon.

  • env (Hash) (defaults to: ENV) —

    the environment to resolve defaults from



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/docker/api/client.rb', line 48

def initialize(url: nil, tls: nil, api_version: :negotiate, logger: nil,
  read_timeout: 60, open_timeout: 10, transport: nil, env: ENV)
  @config = Config.from_env(
    env,
    url: url, api_version: api_version,
    read_timeout: read_timeout, open_timeout: open_timeout,
    **(tls.nil? ? {} : { tls: tls })
  )

  @connection = Connection.new(
    transport: transport || Transport.for(
      url: config.url, tls: config.tls, open_timeout: config.open_timeout
    ),
    api_version: config.api_version,
    logger: logger,
    read_timeout: config.read_timeout,
    open_timeout: config.open_timeout
  )
end

Instance Attribute Details

#config ⇒ Docker::API::Config (readonly)

Returns this client's frozen configuration.

Returns:



29
30
31
 
# File 'lib/docker/api/client.rb', line 29

def config
  @config
end

#connection ⇒ Docker::API::Connection (readonly)

Returns the connection in use.

Returns:



32
33
34
 
# File 'lib/docker/api/client.rb', line 32

def connection
  @connection
end

Instance Method Details

#api_version ⇒ String?

Returns the negotiated Engine API version.

Returns:

  • (String, nil) —

    the negotiated Engine API version



106
107
108
 
# File 'lib/docker/api/client.rb', line 106

def api_version
  connection.api_version
end

#containers ⇒ Docker::API::Containers

Returns:



81
82
83
 
# File 'lib/docker/api/client.rb', line 81

def containers
  @containers ||= Containers.new(self)
end

#images ⇒ Docker::API::Images

Returns:



86
87
88
 
# File 'lib/docker/api/client.rb', line 86

def images
  @images ||= Images.new(self)
end

#networks ⇒ Docker::API::Networks

Returns:



91
92
93
 
# File 'lib/docker/api/client.rb', line 91

def networks
  @networks ||= Networks.new(self)
end

#operations ⇒ Docker::API::Operations

Every Engine API operation, one method each.

This is public API rather than an escape hatch. The ergonomic collections below cover what most code needs; anything they have not grown sugar for is reachable here, fully documented and typed, with no loss of capability.

Returns:



76
77
78
 
# File 'lib/docker/api/client.rb', line 76

def operations
  @operations ||= Operations.new(connection)
end

#system ⇒ Docker::API::System

Returns:



101
102
103
 
# File 'lib/docker/api/client.rb', line 101

def system
  @system ||= System.new(self)
end

#to_s ⇒ String Also known as: inspect

Returns:

  • (String) 


111
112
113
 
# File 'lib/docker/api/client.rb', line 111

def to_s
  "#<Docker::API::Client url=#{config.url}>"
end

#volumes ⇒ Docker::API::Volumes

Returns:



96
97
98
 
# File 'lib/docker/api/client.rb', line 96

def volumes
  @volumes ||= Volumes.new(self)
end