docker-api 1.27.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a402451b60cf3ee27d968b6c406b763ba02fd064
-  data.tar.gz: 239c7b7261f471873819ade511325c785e632d0f
+SHA256:
+  metadata.gz: 7c8d229ece5b5b347a925c62c3f199a940393e58de0b02049aed295090739b04
+  data.tar.gz: 619467ed3697f6b9221f89bab145ba298bd47f5f26209e86df89347b6e83fe08
 SHA512:
-  metadata.gz: 68228f7e53d244b754ce9c26c3a2e412c4162595ae4fc069afea00aa5b89a499f205bcd2be5e055a274ce6e1f5ef2a9188dec364c2086505817176c4bb66a737
-  data.tar.gz: 128d69692f073e103aeef72af0743d5ab3db5020b770242f8df4964da3b0ec6c88c70e587e25822e0a66c80cd3c6bebfdf05f7fa90d501850960b71272c29df9
+  metadata.gz: 7a1a3a2a995c4a172217fc80eb573501502f7f05a337080bf4723d90bb2ba9053cde786aaa994993bd2841ebeeb18cc8a5e4dfa342792bb558fb84a3f4688b89
+  data.tar.gz: c9bbb7ae229ba1784859ddb0e3bc6e7df1651718d552779baac4e2ad49d34096aba760e6ce99fa41dfd14ef6ea0f3a5ddfc9178cf1c7c7f286a8385be1c59385

data/README.md

@@ -1,8 +1,8 @@
 docker-api
 ==========
-[![Gem Version](https://badge.fury.io/rb/docker-api.png)](https://badge.fury.io/rb/docker-api) [![travis-ci](https://travis-ci.org/swipely/docker-api.png?branch=master)](https://travis-ci.org/swipely/docker-api) [![Code Climate](https://codeclimate.com/github/swipely/docker-api.png)](https://codeclimate.com/github/swipely/docker-api) [![Dependency Status](https://gemnasium.com/swipely/docker-api.png)](https://gemnasium.com/swipely/docker-api)
+[![Gem Version](https://badge.fury.io/rb/docker-api.svg)](https://badge.fury.io/rb/docker-api) [![travis-ci](https://travis-ci.org/swipely/docker-api.svg?branch=master)](https://travis-ci.org/swipely/docker-api) [![Code Climate](https://codeclimate.com/github/swipely/docker-api.svg)](https://codeclimate.com/github/swipely/docker-api)
 
-This gem provides an object-oriented interface to the [Docker Remote API](https://docs.docker.com/reference/api/docker_remote_api/). Every method listed there is implemented. At the time of this writing, docker-api is meant to interface with Docker version 1.3.*
+This gem provides an object-oriented interface to the [Docker Engine API](https://docs.docker.com/develop/sdk/). Every method listed there is implemented. At the time of this writing, docker-api is meant to interface with Docker version 1.4.*
 
 If you're interested in using Docker to package your apps, we recommend the [dockly](https://github.com/swipely/dockly) gem. Dockly provides a simple DSL for describing Docker containers that install as Debian packages and are controlled by upstart scripts.
 
@@ -36,7 +36,7 @@ docker-api is designed to be very lightweight. Almost no state is cached (aside
 
 ## Starting up
 
-Follow the [installation instructions](https://docs.docker.com/installation/#installation), and then run:
+Follow the [installation instructions](https://docs.docker.com/install/), and then run:
 
 ```shell
 $ sudo docker -d
@@ -52,7 +52,7 @@ If you're running Docker locally as a socket, there is no setup to do in Ruby. I
 Docker.url = 'tcp://example.com:5422'
 ```
 
-Two things to note here. The first is that this gem uses [excon](http://www.github.com/geemus/excon), so any of the options that are valid for `Excon.new` are also valid for `Docker.options`. Second, by default Docker runs on a socket. The gem will assume you want to connect to the socket unless you specify otherwise.
+Two things to note here. The first is that this gem uses [excon](https://github.com/excon/excon), so any of the options that are valid for `Excon.new` are also valid for `Docker.options`. Second, by default Docker runs on a socket. The gem will assume you want to connect to the socket unless you specify otherwise.
 
 Also, you may set the above variables via `ENV` variables. For example:
 
@@ -94,6 +94,21 @@ Docker.options = {
 }
 ```
 
+If you want to load the cert files from a variable, e.g. you want to load them from ENV as needed on Heroku:
+
+```
+cert_store = OpenSSL::X509::Store.new
+certificate = OpenSSL::X509::Certificate.new ENV["DOCKER_CA"]
+cert_store.add_cert certificate
+
+Docker.options = {
+  client_cert_data: ENV["DOCKER_CERT"],
+  client_key_data: ENV["DOCKER_KEY"],
+  ssl_cert_store: cert_store,
+  scheme: 'https'
+}
+```
+
 If you need to disable SSL verification, set the DOCKER_SSL_VERIFY variable to 'false'.
 
 ## Global calls
@@ -108,13 +123,17 @@ require 'docker'
 Docker.version
 # => { 'Version' => '0.5.2', 'GoVersion' => 'go1.1' }
 
-# docker command for reference: docker info 
+# docker command for reference: docker info
 Docker.info
 # => { "Debug" => false, "Containers" => 187, "Images" => 196, "NFd" => 10, "NGoroutines" => 9, "MemoryLimit" => true }
 
 # docker command for reference: docker login
 Docker.authenticate!('username' => 'docker-fan-boi', 'password' => 'i<3docker', 'email' => 'dockerboy22@aol.com')
 # => true
+
+# docker command for reference: docker login registry.gitlab.com
+Docker.authenticate!('username' => 'docker-fan-boi', 'password' => 'i<3docker', 'email' => 'dockerboy22@aol.com', 'serveraddress' => 'https://registry.gitlab.com/v1/')
+# => true
 ```
 
 ## Images
@@ -245,6 +264,16 @@ Docker::Image.get('df4f1bdecf40')
 Docker::Image.exist?('ef723dcdac09')
 # => true
 
+# Load an image from the file system
+Docker::Image.load('./my-image.tar')
+# => ""
+
+# An IO object may also be specified for loading
+File.open('./my-image.tar', 'rb') do |file|
+  Docker::Image.load(file)
+end
+# => ""
+
 # Export multiple images to a single tarball
 # docker command for reference: docker save my_image1 my_image2:not_latest > my_export.tar
 names = %w( my_image1 my_image2:not_latest )
@@ -314,9 +343,77 @@ container.kill(:signal => "SIGHUP")
 container.top
 # => [{"PID"=>"4851", "TTY"=>"pts/0", "TIME"=>"00:00:00", "CMD"=>"lxc-start"}]
 
+# Same as above, but uses the original format
+container.top(format: :hash)
+# => {
+#      "Titles" => ["PID", "TTY", "TIME", "CMD"],
+#      "Processes" => [["4851", "pts/0", "00:00:00", "lxc-start"]]
+#    }
+
+# To expose 1234 to bridge
+# In Dockerfile: EXPOSE 1234/tcp
+# docker run resulting-image-name
+Docker::Container.create(
+  'Image' => 'image-name',
+  'HostConfig' => {
+    'PortBindings' => {
+      '1234/tcp' => [{}]
+    }
+  }
+)
+
+# To expose 1234 to host with any port
+# docker run -p 1234 image-name
+Docker::Container.create(
+  'Image' => 'image-name',
+  'ExposedPorts' => { '1234/tcp' => {} },
+  'HostConfig' => {
+    'PortBindings' => {
+      '1234/tcp' => [{}]
+    }
+  }
+)
+
+# To expose 1234 to host with a specified host port
+# docker run -p 1234:1234 image-name
+Docker::Container.create(
+  'Image' => 'image-name',
+  'ExposedPorts' => { '1234/tcp' => {} },
+  'HostConfig' => {
+    'PortBindings' => {
+      '1234/tcp' => [{ 'HostPort' => '1234' }]
+    }
+  }
+)
+
+# To expose 1234 to host with a specified host port and host IP
+# docker run -p 192.168.99.100:1234:1234 image-name
+Docker::Container.create(
+  'Image' => 'image-name',
+  'ExposedPorts' => { '1234/tcp' => {} },
+  'HostConfig' => {
+    'PortBindings' => {
+      '1234/tcp' => [{ 'HostPort' => '1234', 'HostIp' => '192.168.99.100' }]
+    }
+  }
+)
+
+# To set container name pass `name` key to options
+Docker::Container.create(
+  'name' => 'my-new-container',
+  'Image' => 'image-name'
+)
+
+# Stores a file with the given content in the container
+container.store_file("/test", "Hello world")
+
+# Reads a file from the container
+container.read_file("/test")
+# => "Hello world"
+
 # Export a Container. Since an export is typically at least 300M, chunks of the
 # export are yielded instead of just returning the whole thing.
-File.open('export.tar', 'w') do |f|
+File.open('export.tar', 'w') do |file|
   container.export { |chunk| file.write(chunk) }
 end
 # => nil
@@ -391,6 +488,10 @@ container = Docker::Container.create('Image' => 'ubuntu', 'Cmd' => command, 'Tty
 container.tap(&:start).attach(:tty => true)
 # => [["I'm a TTY!"], []]
 
+# Obtaining the current statistics of a container
+container.stats
+# => {"read"=>"2016-02-29T20:47:05.221608695Z", "precpu_stats"=>{"cpu_usage"=> ... }
+
 # Create an Image from a Container's changes.
 container.commit
 # => Docker::Image { :id => eaeb8d00efdf, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }
@@ -436,6 +537,9 @@ container.exec(command, wait: 120)
 container.delete(:force => true)
 # => nil
 
+# Update the container.
+container.update("CpuShares" => 50000")
+
 # Request a Container by ID or name.
 Docker::Container.get('500f53b25e6e')
 # => Docker::Container { :id => , :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }
@@ -518,10 +622,6 @@ image 'repo:new_tag' => 'repo:tag' do
 end
 ```
 
-## Known issues
-
-*   If the docker daemon is always responding to your requests with a 400 Bad Request when using UNIX sockets, verify you're running Excon version 0.46.0 or greater. [Link](https://github.com/swipely/docker-api/issues/381)
-
 ## Not supported (yet)
 
 *   Generating a tarball of images and metadata for a repository specified by a name: https://docs.docker.com/engine/reference/api/docker_remote_api_v1.14/#get-a-tarball-containing-all-images-and-tags-in-a-repository

data/lib/docker.rb

@@ -1,5 +1,5 @@
 require 'cgi'
-require 'json'
+require 'multi_json'
 require 'excon'
 require 'tempfile'
 require 'base64'
@@ -14,7 +14,9 @@ require 'open-uri'
 require 'excon/middlewares/hijack'
 Excon.defaults[:middlewares].unshift Excon::Middleware::Hijack
 
-# The top-level module for this gem. It's purpose is to hold global
+Excon.defaults[:middlewares] << Excon::Middleware::RedirectFollower
+
+# The top-level module for this gem. Its purpose is to hold global
 # configuration variables that are used as defaults in other classes.
 module Docker
   attr_accessor :creds, :logger
@@ -119,25 +121,16 @@ module Docker
 
   # Login to the Docker registry.
   def authenticate!(options = {}, connection = self.connection)
-    creds = options.to_json
-    connection.post('/auth', {}, :body => creds)
+    creds = MultiJson.dump(options)
+    connection.post('/auth', {}, body: creds)
     @creds = creds
     true
   rescue Docker::Error::ServerError, Docker::Error::UnauthorizedError
     raise Docker::Error::AuthenticationError
   end
 
-  # When the correct version of Docker is installed, returns true. Otherwise,
-  # raises a VersionError.
-  def validate_version!
-    Docker.info
-    true
-  rescue Docker::Error::DockerError
-    raise Docker::Error::VersionError, "Expected API Version: #{API_VERSION}"
-  end
-
   module_function :default_socket_url, :env_url, :url, :url=, :env_options,
                   :options, :options=, :creds, :creds=, :logger, :logger=,
                   :connection, :reset!, :reset_connection!, :version, :info,
-                  :ping, :authenticate!, :validate_version!, :ssl_options
+                  :ping, :authenticate!, :ssl_options
 end

data/lib/docker/connection.rb

@@ -80,14 +80,14 @@ private
     user_agent = "Swipely/Docker-API #{Docker::VERSION}"
     {
       :method        => http_method,
-      :path          => "/v#{Docker::API_VERSION}#{path}",
+      :path          => path,
       :query         => query,
       :headers       => { 'Content-Type' => content_type,
                           'User-Agent'   => user_agent,
                         }.merge(headers),
-      :expects       => (200..204).to_a << 304,
+      :expects       => (200..204).to_a << 301 << 304,
       :idempotent    => http_method == :get,
-      :request_block => block
+      :request_block => block,
     }.merge(opts).reject { |_, v| v.nil? }
   end
 end

data/lib/docker/container.rb

@@ -11,17 +11,18 @@ class Docker::Container
     }
 
     info.merge!(self.json)
-    other && info.merge!(other.info)
+    other && info.merge!(other.info) { |key, info_value, other_value| info_value }
     self
   end
 
   # Return a List of Hashes that represents the top running processes.
   def top(opts = {})
+    format = opts.delete(:format) { :array }
     resp = Docker::Util.parse_json(connection.get(path_for(:top), opts))
     if resp['Processes'].nil?
-      []
+      format == :array ? [] : {}
     else
-      resp['Processes'].map { |ary| Hash[resp['Titles'].zip(ary)] }
+      format == :array ? resp['Processes'].map { |ary| Hash[resp['Titles'].zip(ary)] } : resp
     end
   end
 
@@ -51,33 +52,37 @@ class Docker::Container
   # @param options [Hash] The options to pass to Docker::Exec
   #
   # @return [Docker::Exec] The Exec instance
-  def exec(command, opts = {}, &block)
+  def exec(command, options = {}, &block)
     # Establish values
-    tty = opts.delete(:tty) || false
-    detach = opts.delete(:detach) || false
-    user = opts.delete(:user)
-    stdin = opts.delete(:stdin)
-    stdout = opts.delete(:stdout) || !detach
-    stderr = opts.delete(:stderr) || !detach
+    tty = options.delete(:tty) || false
+    detach = options.delete(:detach) || false
+    user = options.delete(:user)
+    stdin = options.delete(:stdin)
+    stdout = options.delete(:stdout) || !detach
+    stderr = options.delete(:stderr) || !detach
+    wait = options.delete(:wait)
+
+    opts = {
+      'Container' => self.id,
+      'User' => user,
+      'AttachStdin' => !!stdin,
+      'AttachStdout' => stdout,
+      'AttachStderr' => stderr,
+      'Tty' => tty,
+      'Cmd' => command
+    }.merge(options)
 
     # Create Exec Instance
     instance = Docker::Exec.create(
-      {
-        'Container' => self.id,
-        'User' => user,
-        'AttachStdin' => !!stdin,
-        'AttachStdout' => stdout,
-        'AttachStderr' => stderr,
-        'Tty' => tty,
-        'Cmd' => command
-      },
+      opts,
       self.connection
     )
 
     start_opts = {
       :tty => tty,
       :stdin => stdin,
-      :detach => detach
+      :detach => detach,
+      :wait => wait
     }
 
     if detach
@@ -95,7 +100,7 @@ class Docker::Container
   end
 
   # Attach to a container's standard streams / logs.
-  def attach(options = {}, &block)
+  def attach(options = {}, excon_params = {}, &block)
     stdin = options.delete(:stdin)
     tty   = options.delete(:tty)
 
@@ -105,8 +110,6 @@ class Docker::Container
     # Creates list to store stdout and stderr messages
     msgs = Docker::Messages.new
 
-    excon_params = {}
-
     if stdin
       # If attaching to stdin, we must hijack the underlying TCP connection
       # so we can stream stdin to the remote Docker process
@@ -132,10 +135,10 @@ class Docker::Container
     # Based on the link, the config passed as run, needs to be passed as the
     # body of the post so capture it, remove from the options, and pass it via
     # the post body
-    config = options.delete('run')
-    hash = Docker::Util.parse_json(connection.post('/commit',
-                                                   options,
-                                                   :body => config.to_json))
+    config = MultiJson.dump(options.delete('run'))
+    hash = Docker::Util.parse_json(
+      connection.post('/commit', options, body: config)
+    )
     Docker::Image.send(:new, self.connection, hash)
   end
 
@@ -156,24 +159,47 @@ class Docker::Container
     connection.get(path_for(:logs), opts)
   end
 
+  def stats(options = {})
+    if block_given?
+      options[:read_timeout] ||= 10
+      options[:idempotent] ||= false
+      parser = lambda do |chunk, remaining_bytes, total_bytes|
+        yield Docker::Util.parse_json(chunk)
+      end
+      begin
+        connection.get(path_for(:stats), nil, {response_block: parser}.merge(options))
+      rescue Docker::Error::TimeoutError
+        # If the container stops, the docker daemon will hold the connection
+        # open forever, but stop sending events.
+        # So this Timeout indicates the stream is over.
+      end
+    else
+      Docker::Util.parse_json(connection.get(path_for(:stats), {stream: 0}.merge(options)))
+    end
+  end
+
   def rename(new_name)
     query = {}
     query['name'] = new_name
     connection.post(path_for(:rename), query)
   end
 
+  def update(opts)
+    connection.post(path_for(:update), {}, body: MultiJson.dump(opts))
+  end
+
   def streaming_logs(opts = {}, &block)
-    stack_size = opts.delete('stack_size') || -1
+    stack_size = opts.delete('stack_size') || opts.delete(:stack_size) || -1
     tty = opts.delete('tty') || opts.delete(:tty) || false
     msgs = Docker::MessagesStack.new(stack_size)
-    excon_params = {response_block: Docker::Util.attach_for(block, msgs, tty)}
+    excon_params = {response_block: Docker::Util.attach_for(block, msgs, tty), idempotent: false}
 
     connection.get(path_for(:logs), opts, excon_params)
     msgs.messages.join
   end
 
   def start!(opts = {})
-    connection.post(path_for(:start), {}, :body => opts.to_json)
+    connection.post(path_for(:start), {}, body: MultiJson.dump(opts))
     self
   end
 
@@ -198,8 +224,18 @@ class Docker::Container
     define_method(:"#{method}!") do |opts = {}|
       timeout = opts.delete('timeout')
       query = {}
-      query['t'] = timeout if timeout
-      connection.post(path_for(method), query, :body => opts.to_json)
+      request_options = {
+        :body => MultiJson.dump(opts)
+      }
+      if timeout
+        query['t'] = timeout
+        # Ensure request does not timeout before Docker timeout
+        request_options.merge!(
+          read_timeout: timeout.to_i + 5,
+          write_timeout: timeout.to_i + 5
+        )
+      end
+      connection.post(path_for(method), query, request_options)
       self
     end
 
@@ -230,14 +266,6 @@ class Docker::Container
     end
   end
 
-  def copy(path, &block)
-    connection.post(path_for(:copy), {},
-      :body => { "Resource" => path }.to_json,
-      :response_block => block
-    )
-    self
-  end
-
   def archive_out(path, &block)
     connection.get(
       path_for(:archive),
@@ -269,19 +297,43 @@ class Docker::Container
     self
   end
 
+  def read_file(path)
+    content = StringIO.new
+    archive_out(path) do |chunk|
+      content.write chunk
+    end
+
+    content.rewind
+
+    Gem::Package::TarReader.new(content) do |tar|
+      tar.each do |tarfile|
+        return tarfile.read
+      end
+    end
+  end
+
+  def store_file(path, file_content)
+    output_io = StringIO.new(
+      Docker::Util.create_tar(
+        path => file_content
+      )
+    )
+
+    archive_in_stream("/", overwrite: true) { output_io.read }
+  end
+
   # Create a new Container.
   def self.create(opts = {}, conn = Docker.connection)
-    name = opts.delete('name')
-    query = {}
-    query['name'] = name if name
-    resp = conn.post('/containers/create', query, :body => opts.to_json)
+    query = opts.select {|key| ['name', :name].include?(key) }
+    clean_opts = opts.reject {|key| ['name', :name].include?(key) }
+    resp = conn.post('/containers/create', query, :body => MultiJson.dump(clean_opts))
     hash = Docker::Util.parse_json(resp) || {}
     new(conn, hash)
   end
 
   # Return the container with specified ID
   def self.get(id, opts = {}, conn = Docker.connection)
-    container_json = conn.get("/containers/#{URI.encode(id)}/json", opts)
+    container_json = conn.get("/containers/#{id}/json", opts)
     hash = Docker::Util.parse_json(container_json) || {}
     new(conn, hash)
   end
@@ -292,6 +344,12 @@ class Docker::Container
     hashes.map { |hash| new(conn, hash) }
   end
 
+  # Prune images
+  def self.prune(conn = Docker.connection)
+    conn.post("/containers/prune", {})
+    nil
+  end
+
   # Convenience method to return the path for a particular resource.
   def path_for(resource)
     "/containers/#{self.id}/#{resource}"