Class: Docker::Image
Overview
This class represents a Docker Image.
Instance Attribute Summary
Attributes included from Base
Class Method Summary collapse
-
.all(opts = {}, conn = Docker.connection) ⇒ Object
Return every Image.
-
.build(commands, opts = {}, connection = Docker.connection, &block) ⇒ Object
Given a Dockerfile as a string, builds an Image.
-
.build_from_dir(dir, opts = {}, connection = Docker.connection, creds = nil, &block) ⇒ Object
Given a directory that contains a Dockerfile, builds an Image.
-
.build_from_tar(tar, opts = {}, connection = Docker.connection, creds = nil, &block) ⇒ Object
Given File like object containing a tar file, builds an Image.
-
.create(opts = {}, creds = nil, conn = Docker.connection, &block) ⇒ Object
Create a new Image.
-
.exist?(id, opts = {}, conn = Docker.connection) ⇒ Boolean
Check if an image exists.
-
.get(id, opts = {}, conn = Docker.connection) ⇒ Object
Return a specific image.
-
.import(imp, opts = {}, conn = Docker.connection) ⇒ Object
Import an Image from the output of Docker::Container#export.
- .import_stream(options = {}, connection = Docker.connection, &block) ⇒ Object
-
.load(tar, opts = {}, conn = Docker.connection, creds = nil, &block) ⇒ Object
Load a tar Image.
-
.prune(conn = Docker.connection) ⇒ Object
Prune images.
-
.remove(id, opts = {}, conn = Docker.connection) ⇒ Object
(also: delete)
Delete a specific image.
-
.save(names, filename = nil, conn = Docker.connection) ⇒ NilClass, String
Save the raw binary representation or one or more Docker images.
-
.save_stream(names, opts = {}, conn = Docker.connection, &block) ⇒ Object
Stream the contents of Docker image(s) to a block.
-
.search(query = {}, connection = Docker.connection, creds = nil) ⇒ Object
Given a query like ‘{ :term => ’sshd’ }‘, queries the Docker Registry for a corresponding Image.
Instance Method Summary collapse
-
#delete ⇒ Object
Remove the Image from the server.
-
#insert_local(opts = {}) ⇒ Object
Given a path of a local file and the path it should be inserted, creates a new Image that has that file.
-
#push(creds = nil, options = {}, &block) ⇒ Object
Push the Image to the Docker registry.
-
#refresh! ⇒ Object
Update the @info hash, which is the only mutable state in this object.
-
#remove(opts = {}) ⇒ Object
Remove the Image from the server.
-
#run(cmd = nil, options = {}) ⇒ Object
Given a command and optional list of streams to attach to, run a command on an Image.
-
#save(filename = nil) ⇒ Object
Save the image as a tarball.
-
#save_stream(opts = {}, &block) ⇒ Object
Save the image as a tarball to an IO object.
-
#tag(opts = {}) ⇒ Object
Tag the Image.
-
#to_s ⇒ Object
Return a String representation of the Image.
Methods included from Base
Class Method Details
.all(opts = {}, conn = Docker.connection) ⇒ Object
Return every Image.
208 209 210 211 |
# File 'lib/docker/image.rb', line 208 def all(opts = {}, conn = Docker.connection) hashes = Docker::Util.parse_json(conn.get('/images/json', opts)) || [] hashes.map { |hash| new(conn, hash) } end |
.build(commands, opts = {}, connection = Docker.connection, &block) ⇒ Object
Given a Dockerfile as a string, builds an Image.
251 252 253 254 255 256 257 258 259 260 261 |
# File 'lib/docker/image.rb', line 251 def build(commands, opts = {}, connection = Docker.connection, &block) body = "" connection.post( '/build', opts, :body => Docker::Util.create_tar('Dockerfile' => commands), :response_block => response_block(body, &block) ) new(connection, 'id' => Docker::Util.extract_id(body)) rescue Docker::Error::ServerError raise Docker::Error::UnexpectedResponseError end |
.build_from_dir(dir, opts = {}, connection = Docker.connection, creds = nil, &block) ⇒ Object
Given a directory that contains a Dockerfile, builds an Image.
If a block is passed, chunks of output produced by Docker will be passed to that block.
289 290 291 292 293 294 295 296 297 298 299 |
# File 'lib/docker/image.rb', line 289 def build_from_dir(dir, opts = {}, connection = Docker.connection, creds = nil, &block) tar = Docker::Util.create_dir_tar(dir) build_from_tar tar, opts, connection, creds, &block ensure unless tar.nil? tar.close FileUtils.rm(tar.path, force: true) end end |
.build_from_tar(tar, opts = {}, connection = Docker.connection, creds = nil, &block) ⇒ Object
Given File like object containing a tar file, builds an Image.
If a block is passed, chunks of output produced by Docker will be passed to that block.
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 |
# File 'lib/docker/image.rb', line 267 def build_from_tar(tar, opts = {}, connection = Docker.connection, creds = nil, &block) headers = build_headers(creds) # The response_block passed to Excon will build up this body variable. body = "" connection.post( '/build', opts, :headers => headers, :response_block => response_block(body, &block) ) { tar.read(Excon.defaults[:chunk_size]).to_s } new(connection, 'id' => Docker::Util.extract_id(body), :headers => headers) end |
.create(opts = {}, creds = nil, conn = Docker.connection, &block) ⇒ Object
Create a new Image.
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 |
# File 'lib/docker/image.rb', line 110 def create(opts = {}, creds = nil, conn = Docker.connection, &block) credentials = creds.nil? ? Docker.creds : MultiJson.dump(creds) headers = credentials && Docker::Util.build_auth_header(credentials) || {} body = '' conn.post( '/images/create', opts, :headers => headers, :response_block => response_block(body, &block) ) # NOTE: see associated tests for why we're looking at image#end_with? image = opts['fromImage'] || opts[:fromImage] tag = opts['tag'] || opts[:tag] image = "#{image}:#{tag}" if tag && !image.end_with?(":#{tag}") get(image, {}, conn) end |
.exist?(id, opts = {}, conn = Docker.connection) ⇒ Boolean
Check if an image exists.
200 201 202 203 204 205 |
# File 'lib/docker/image.rb', line 200 def exist?(id, opts = {}, conn = Docker.connection) get(id, opts, conn) true rescue Docker::Error::NotFoundError false end |
.get(id, opts = {}, conn = Docker.connection) ⇒ Object
Return a specific image.
128 129 130 131 132 |
# File 'lib/docker/image.rb', line 128 def get(id, opts = {}, conn = Docker.connection) image_json = conn.get("/images/#{URI.encode(id)}/json", opts) hash = Docker::Util.parse_json(image_json) || {} new(conn, hash) end |
.import(imp, opts = {}, conn = Docker.connection) ⇒ Object
Import an Image from the output of Docker::Container#export. The first argument may either be a File or URI.
229 230 231 232 233 234 235 236 237 |
# File 'lib/docker/image.rb', line 229 def import(imp, opts = {}, conn = Docker.connection) open(imp) do |io| import_stream(opts, conn) do io.read(Excon.defaults[:chunk_size]).to_s end end rescue StandardError raise Docker::Error::IOError, "Could not import '#{imp}'" end |
.import_stream(options = {}, connection = Docker.connection, &block) ⇒ Object
239 240 241 242 243 244 245 246 247 248 |
# File 'lib/docker/image.rb', line 239 def import_stream( = {}, connection = Docker.connection, &block) body = connection.post( '/images/create', .merge('fromSrc' => '-'), :headers => { 'Content-Type' => 'application/tar', 'Transfer-Encoding' => 'chunked' }, &block ) new(connection, 'id'=> Docker::Util.parse_json(body)['status']) end |
.load(tar, opts = {}, conn = Docker.connection, creds = nil, &block) ⇒ Object
Load a tar Image
187 188 189 190 191 192 193 194 195 196 197 |
# File 'lib/docker/image.rb', line 187 def load(tar, opts = {}, conn = Docker.connection, creds = nil, &block) headers = build_headers(creds) io = tar.is_a?(String) ? File.open(tar, 'rb') : tar body = "" conn.post( '/images/load', opts, :headers => headers, :response_block => response_block(body, &block) ) { io.read(Excon.defaults[:chunk_size]).to_s } end |
.prune(conn = Docker.connection) ⇒ Object
Prune images
141 142 143 |
# File 'lib/docker/image.rb', line 141 def prune(conn = Docker.connection) conn.post("/images/prune", {}) end |
.remove(id, opts = {}, conn = Docker.connection) ⇒ Object Also known as: delete
Delete a specific image
135 136 137 |
# File 'lib/docker/image.rb', line 135 def remove(id, opts = {}, conn = Docker.connection) conn.delete("/images/#{id}", opts) end |
.save(names, filename = nil, conn = Docker.connection) ⇒ NilClass, String
Save the raw binary representation or one or more Docker images
representation of the binary data. If the filename is not nil, then return nil.
155 156 157 158 159 160 161 162 163 164 165 166 |
# File 'lib/docker/image.rb', line 155 def save(names, filename = nil, conn = Docker.connection) if filename File.open(filename, 'wb') do |file| save_stream(names, {}, conn, &response_block_for_save(file)) end nil else string = '' save_stream(names, {}, conn, &response_block_for_save(string)) string end end |
.save_stream(names, opts = {}, conn = Docker.connection, &block) ⇒ Object
Stream the contents of Docker image(s) to a block.
173 174 175 176 177 178 179 180 181 182 183 184 |
# File 'lib/docker/image.rb', line 173 def save_stream(names, opts = {}, conn = Docker.connection, &block) # By using compare_by_identity we can create a Hash that has # the same key multiple times. query = {}.tap(&:compare_by_identity) Array(names).each { |name| query['names'.dup] = URI.encode(name) } conn.get( '/images/get', query, opts.merge(:response_block => block) ) nil end |
.search(query = {}, connection = Docker.connection, creds = nil) ⇒ Object
Given a query like ‘{ :term => ’sshd’ }‘, queries the Docker Registry for a corresponding Image.
215 216 217 218 219 220 221 222 223 224 225 |
# File 'lib/docker/image.rb', line 215 def search(query = {}, connection = Docker.connection, creds = nil) credentials = creds.nil? ? Docker.creds : creds.to_json headers = credentials && Docker::Util.build_auth_header(credentials) || {} body = connection.get( '/images/search', query, :headers => headers, ) hashes = Docker::Util.parse_json(body) || [] hashes.map { |hash| new(connection, 'id' => hash['name']) } end |
Instance Method Details
#delete ⇒ Object
Remove the Image from the server.
71 72 73 74 |
# File 'lib/docker/image.rb', line 71 def remove(opts = {}) name = opts.delete(:name) || self.id connection.delete("/images/#{name}", opts) end |
#insert_local(opts = {}) ⇒ Object
Given a path of a local file and the path it should be inserted, creates a new Image that has that file.
51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
# File 'lib/docker/image.rb', line 51 def insert_local(opts = {}) local_paths = opts.delete('localPath') output_path = opts.delete('outputPath') local_paths = [ local_paths ] unless local_paths.is_a?(Array) file_hash = Docker::Util.file_hash_from_paths(local_paths) file_hash['Dockerfile'] = dockerfile_for(file_hash, output_path) tar = Docker::Util.create_tar(file_hash) body = connection.post('/build', opts, :body => tar) self.class.send(:new, connection, 'id' => Docker::Util.extract_id(body)) end |
#push(creds = nil, options = {}, &block) ⇒ Object
Push the Image to the Docker registry.
25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
# File 'lib/docker/image.rb', line 25 def push(creds = nil, = {}, &block) repo_tag = .delete(:repo_tag) || .first raise ArgumentError, "Image is untagged" if repo_tag.nil? repo, tag = Docker::Util.parse_repo_tag(repo_tag) raise ArgumentError, "Image does not have a name to push." if repo.nil? body = "" credentials = creds || Docker.creds || {} headers = Docker::Util.build_auth_header(credentials) opts = {:tag => tag}.merge() connection.post("/images/#{repo}/push", opts, :headers => headers, :response_block => self.class.response_block(body, &block)) self end |
#refresh! ⇒ Object
Update the @info hash, which is the only mutable state in this object.
98 99 100 101 102 103 104 105 |
# File 'lib/docker/image.rb', line 98 def refresh! img = Docker::Image.all({:all => true}, connection).find { |image| image.id.start_with?(self.id) || self.id.start_with?(image.id) } info.merge!(self.json) img && info.merge!(img.info) self end |
#remove(opts = {}) ⇒ Object
Remove the Image from the server.
67 68 69 70 |
# File 'lib/docker/image.rb', line 67 def remove(opts = {}) name = opts.delete(:name) || self.id connection.delete("/images/#{name}", opts) end |
#run(cmd = nil, options = {}) ⇒ Object
Given a command and optional list of streams to attach to, run a command on an Image. This will not modify the Image, but rather create a new Container to run the Image. If the image has an embedded config, no command is necessary, but it will fail with 500 if no config is saved with the image
9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
# File 'lib/docker/image.rb', line 9 def run(cmd = nil, = {}) opts = {'Image' => self.id}.merge() opts["Cmd"] = cmd.is_a?(String) ? cmd.split(/\s+/) : cmd begin Docker::Container.create(opts, connection) .tap(&:start!) rescue ServerError, ClientError => ex if cmd raise ex else raise ex, "No command specified." end end end |
#save(filename = nil) ⇒ Object
Save the image as a tarball
88 89 90 |
# File 'lib/docker/image.rb', line 88 def save(filename = nil) self.class.save(self.id, filename, connection) end |
#save_stream(opts = {}, &block) ⇒ Object
Save the image as a tarball to an IO object.
93 94 95 |
# File 'lib/docker/image.rb', line 93 def save_stream(opts = {}, &block) self.class.save_stream(self.id, opts, connection, &block) end |
#tag(opts = {}) ⇒ Object
Tag the Image.
41 42 43 44 45 46 47 |
# File 'lib/docker/image.rb', line 41 def tag(opts = {}) self.info['RepoTags'] ||= [] connection.post(path_for(:tag), opts) repo = opts['repo'] || opts[:repo] tag = opts['tag'] || opts[:tag] || 'latest' self.info['RepoTags'] << "#{repo}:#{tag}" end |
#to_s ⇒ Object
Return a String representation of the Image.
74 75 76 77 |
# File 'lib/docker/image.rb', line 74 def to_s "Docker::Image { :id => #{self.id}, :info => #{self.info.inspect}, "\ ":connection => #{self.connection} }" end |