Module: Hyperkit::Client::Images

Included in:
Hyperkit::Client
Defined in:
lib/hyperkit/client/images.rb

Overview

Methods for the images API

See Also:

Retrieval collapse

Creation and deletion collapse

Editing collapse

Export collapse

Aliases collapse

Instance Method Details

#create_image_alias(fingerprint, alias_name, options = {}) ⇒ Sawyer::Resource

Assign an alias for an image

Examples:

Assign alias “ubuntu/xenial/amd64” to an image

Hyperkit.create_image_alias(
  "878cf0c70e14fec80aaf4d5e923670e68c45aa89fb05a481019bf086aec42649",
  "ubuntu/xenial/amd64")

Assign alias “ubuntu/xenial/amd64” with a description

Hyperkit.create_image_alias(
  "878cf0c70e14fec80aaf4d5e923670e68c45aa89fb05a481019bf086aec42649",
  "ubuntu/xenial/amd64",
  description: "Ubuntu Xenial amd64")

Parameters:

  • fingerprint (String) —

    Fingerprint of the image

  • alias_name (String) —

    Alias to assign to the image

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

    Additional data to be passed

Options Hash (options):

  • :description (String) —

    Alias description

Returns:

  • (Sawyer::Resource) 


582
583
584
585
586
587
588
589
 
# File 'lib/hyperkit/client/images.rb', line 582

def create_image_alias(fingerprint, alias_name, options={})
  opts = options.slice(:description).merge({
    target: fingerprint,
    name: alias_name
  })

  post(image_aliases_path, opts).metadata
end

#create_image_from_container(name, options = {}) ⇒ Sawyer::Resource

Create an image from an existing container.

Examples:

Create a private image from container ‘test-container’

Hyperkit.create_image_from_container("test-container")

Create a public image from container ‘test-container’

Hyperkit.create_image_from_container("test-container", public: true)

Store properties with the new image, and override its filename

Hyperkit.create_image_from_container("test-container",
  filename: "ubuntu-trusty.tar.gz",
  properties: {
    os: "ubuntu"
    codename: "trusty"
    version: "14.04"
  }
)

Parameters:

  • name (String) —

    Source container name

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

    Additional data to be passed

Options Hash (options):

  • :filename (String) —

    Tarball filename to store with the image on the server and used when exporting the image (default: name of file being uploaded).

  • :public (Boolean) —

    Whether or not the image should be publicly-accessible by unauthenticated users (default: false).

  • :properties (Hash) —

    Hash of additional properties to store with the image

  • :sync (Boolean) —

    If false, returns an asynchronous operation that must be passed to Operations#wait_for_operation. If true, automatically waits and returns the result of the operation. Defaults to value of Hyperkit::Configurable#auto_sync.

Returns:

  • (Sawyer::Resource) —

    Operation or result, depending value of :sync parameter and/or auto_sync

Asynchronous:



317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/hyperkit/client/images.rb', line 317

def create_image_from_container(name, options={})

  opts = options.slice(:filename, :public, :description)
  opts[:properties] = stringify_hash(options[:properties]) if options[:properties]
  opts[:source] = {
    type: "container",
    name: name
  }

  response = post(images_path, opts).metadata
  handle_async(response, options[:sync])
end

#create_image_from_file(file, options = {}) ⇒ Sawyer::Resource

Upload an image from a local file

Examples:

Upload a private image

Hyperkit.create_image_from_file("/tmp/ubuntu-14.04-amd64-lxc.tar.gz")

Upload a public image

Hyperkit.create_image_from_file("/tmp/ubuntu-14.04-amd64-lxc.tar.gz", public: true)

Store properties with the uploaded image, and override its filename

Hyperkit.create_image_from_file("/tmp/ubuntu-14.04-amd64-lxc.tar.gz",
  filename: "ubuntu-trusty.tar.gz",
  properties: {
    os: "ubuntu"
    codename: "trusty"
    version: "14.04"
  }
)

Upload an image, but only store it if the uploaded file has the same fingerprint

Hyperkit.create_image_from_file("/tmp/ubuntu-14.04-amd64-lxc.tar.gz",
  fingerprint: "3dc37b8185cc811bcad5e319a9f38daeae823065dd6264334ac07b8324a42f2d")

Parameters:

  • file (String) —

    Path of image tarball to be uploaded

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

    Additional data to be passed

Options Hash (options):

  • :fingerprint (String) —

    SHA-256 fingerprint of the tarball. If the fingerprint of the uploaded image does not match, the image will not be saved on the server.

  • :filename (String) —

    Tarball filename to store with the image on the server and used when exporting the image (default: name of file being uploaded).

  • :public (Boolean) —

    Whether or not the image should be publicly-accessible by unauthenticated users (default: false).

  • :properties (Hash) —

    Hash of additional properties to store with the image

  • :sync (Boolean) —

    If false, returns an asynchronous operation that must be passed to Operations#wait_for_operation. If true, automatically waits and returns the result of the operation. Defaults to value of Hyperkit::Configurable#auto_sync.

Returns:

  • (Sawyer::Resource) —

    Operation or result, depending value of :sync parameter and/or auto_sync

Asynchronous:



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/hyperkit/client/images.rb', line 133

def create_image_from_file(file, options={})
  headers = { "Content-Type" => "application/octet-stream" }

  headers["X-LXD-fingerprint"] = options[:fingerprint] if options[:fingerprint]
  headers["X-LXD-filename"] = options[:filename] || File.basename(file)
  headers["X-LXD-public"] = 1.to_s if options[:public]

  if options[:properties]
    properties = options[:properties].map do |k,v|
      "#{URI.escape(k.to_s)}=#{URI.escape(v.to_s)}"
    end
    headers["X-LXD-properties"] = properties.join("&")
  end

  response = post(images_path, {
    raw_body: File.read(file),
    headers: headers
  }).metadata

  handle_async(response, options[:sync])
end

#create_image_from_remote(server, options = {}) ⇒ Sawyer::Resource

Import an image from a remote server

Examples:

Import image by alias

Hyperkit.create_image_from_remote("https://images.linuxcontainers.org:8443",
  alias: "ubuntu/xenial/amd64")

Import image by fingerprint

Hyperkit.create_image_from_remote("https://images.linuxcontainers.org:8443",
  fingerprint: "b1cf3d836196c316897d39872ff25e2d912ea933207b0c591334a67b290a5f1b")

Import image and automatically update it when it is updated on the remote server

Hyperkit.create_image_from_remote("https://images.linuxcontainers.org:8443",
  alias: "ubuntu/xenial/amd64",
  auto_update: true)

Store properties with the imported image (will be applied on top of any source properties)

Hyperkit.create_image_from_remote("https://images.linuxcontainers.org:8443",
  alias: "ubuntu/xenial/amd64",
  properties: {
    hello: "world"
  }
)

Parameters:

  • server (String) —

    Source server

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

    Additional data to be passed

Options Hash (options):

  • :alias (String) —

    Alias of the source image to import. Either :alias or :fingerprint must be specified.

  • :auto_update (Boolean) —

    Whether or not the image should be automatically updated from the source server (source image must be public and must be referenced by alias – not fingerprint; default: false).

  • :certificate (String) —

    PEM certificate to use to authenticate with the source server. If not specified, and the source image is private, the target LXD server’s certificate is used for authentication.

  • :filename (String) —

    Tarball filename to store with the image on the server and used when exporting the image (default: filename retrieved from the source server).

  • :fingerprint (String) —

    SHA-256 fingerprint of the source image to import. Depending on the version of the source LXD server, you may be able to specify an image by its fingerprint prefix rather than a full fingerprint, as long as the prefix is unambiguous. Either :alias or :fingerprint must be specified.

  • :protocol (String) —

    Protocol to use in transferring the image (lxd or simplestreams; defaults to lxd)

  • :public (Boolean) —

    Whether or not the image should be publicly-accessible by unauthenticated users (default: false).

  • :properties (Hash) —

    Hash of additional properties to store with the image

  • :secret (String) —

    Secret to use to retrieve the image

  • :sync (Boolean) —

    If false, returns an asynchronous operation that must be passed to Operations#wait_for_operation. If true, automatically waits and returns the result of the operation. Defaults to value of Hyperkit::Configurable#auto_sync.

Returns:

  • (Sawyer::Resource) —

    Operation or result, depending value of :sync parameter and/or auto_sync

Asynchronous:



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/hyperkit/client/images.rb', line 193

def create_image_from_remote(server, options={})

  opts = options.slice(:filename, :public, :auto_update)

  if options[:protocol] && ! %w[lxd simplestreams].include?(options[:protocol])
    raise Hyperkit::InvalidProtocol.new("Invalid protocol.  Valid choices: lxd, simplestreams")
  end

  opts[:source] = options.slice(:secret, :protocol, :certificate)
  opts[:source].merge!({
    type: "image",
    mode: "pull",
    server: server
  })

  if options[:alias].nil? && options[:fingerprint].nil?
    raise Hyperkit::ImageIdentifierRequired.new("Please specify either :alias or :fingerprint")
  end

  opts[:properties] = stringify_hash(options[:properties]) if options[:properties]

  if options[:alias]
    opts[:source][:alias] = options[:alias]
  else
    opts[:source][:fingerprint] = options[:fingerprint]
  end

  response = post(images_path, opts).metadata
  handle_async(response, options[:sync])
end

#create_image_from_snapshot(container, snapshot, options = {}) ⇒ Sawyer::Resource

Create an image from an existing snapshot.

Examples:

Create a private image from snapshot ‘test-container/snapshot1’

Hyperkit.create_image_from_snapshot("test-container", "snapshot1")

Create a public image from snapshot ‘test-container/snapshot1’

Hyperkit.create_image_from_snapshot("test-container", "snapshot1", public: true)

Store properties with the new image, and override its filename

Hyperkit.create_image_from_snapshot("test-container", "snapshot1",
  filename: "ubuntu-trusty.tar.gz",
  properties: {
    os: "ubuntu"
    codename: "trusty"
    version: "14.04"
  }
)

Parameters:

  • container (String) —

    Source container name

  • snapshot (String) —

    Source snapshot name

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

    Additional data to be passed

Options Hash (options):

  • :filename (String) —

    Tarball filename to store with the image on the server and used when exporting the image (default: name of file being uploaded).

  • :public (Boolean) —

    Whether or not the image should be publicly-accessible by unauthenticated users (default: false).

  • :properties (Hash) —

    Hash of additional properties to store with the image

  • :sync (Boolean) —

    If false, returns an asynchronous operation that must be passed to Operations#wait_for_operation. If true, automatically waits and returns the result of the operation. Defaults to value of Hyperkit::Configurable#auto_sync.

Returns:

  • (Sawyer::Resource) —

    Operation or result, depending value of :sync parameter and/or auto_sync

Asynchronous:



358
359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/hyperkit/client/images.rb', line 358

def create_image_from_snapshot(container, snapshot, options={})

  opts = options.slice(:filename, :public, :description)
  opts[:properties] = stringify_hash(options[:properties]) if options[:properties]
  opts[:source] = {
    type: "snapshot",
    name: "#{container}/#{snapshot}"
  }

  response = post(images_path, opts).metadata
  handle_async(response, options[:sync])
end

#create_image_from_url(url, options = {}) ⇒ Sawyer::Resource

Import an image from a remote URL.

Note: the URL passed to this method is not the URL of a tarball. Instead, the URL must return the following headers:

  • LXD-Image-URL - URL of the image tarball

  • LXD-Image-Hash - SHA-256 fingerprint of the image tarball

The LXD server will first access the URL to obtain the values of these headers. It will then download the tarball specified in the LXD-Image-URL header and verify that its fingerprint matches the value in the LXD-Image-Hash header. If they match, the image will be imported.

In Apache, you can set this up using a .htaccess file. See the Examples section for a sample.

Examples:

Import a private image

Hyperkit.create_image_from_url("http://example.com/ubuntu-14.04")

Import a public image

Hyperkit.create_image_from_url("http://example.com/ubuntu-14.04", public: true)

Store properties with the uploaded image, and override its filename

Hyperkit.create_image_from_url("http://example.com/ubuntu-14.04",
  filename: "ubuntu-trusty.tar.gz",
  properties: {
    os: "ubuntu"
    codename: "trusty"
    version: "14.04"
  }
)

Example .htaccess file on the source server, located in the /ubuntu-14.04 directory:

# Put an empty index.html in the ubuntu-14.04 directory.
# Note that the 'headers' Apache module must be enabled (a2enmod headers).
<Files index.html>

# Image of the file to download
Header set LXD-Image-URL http://example.com/ubuntu-14.04/ubuntu-14.04-amd64-lxc.tar.xz

# SHA-256 of the file to download
Header set LXD-Image-Hash 097e75d6f7419d3a5e204d8125582f2d7bdd4ee4c35bd324513321c645f0c415
</Files>

Parameters:

  • url (String) —

    URL containing image headers (see above)

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

    Additional data to be passed

Options Hash (options):

  • :filename (String) —

    Tarball filename to store with the image on the server and used when exporting the image (default: name of file being uploaded).

  • :public (Boolean) —

    Whether or not the image should be publicly-accessible by unauthenticated users (default: false).

  • :properties (Hash) —

    Hash of additional properties to store with the image

  • :sync (Boolean) —

    If false, returns an asynchronous operation that must be passed to Operations#wait_for_operation. If true, automatically waits and returns the result of the operation. Defaults to value of Hyperkit::Configurable#auto_sync.

Returns:

  • (Sawyer::Resource) —

    Operation or result, depending value of :sync parameter and/or auto_sync

Asynchronous:



277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/hyperkit/client/images.rb', line 277

def create_image_from_url(url, options={})

  opts = options.slice(:filename, :public)
  opts[:properties] = stringify_hash(options[:properties]) if options[:properties]
  opts[:source] = {
    type: "url",
    url: url
  }

  response = post(images_path, opts).metadata
  handle_async(response, options[:sync])
end

#create_image_secret(fingerprint) ⇒ Sawyer::Response

Generate a secret for an image that can be used by an untrusted client to retrieve information on and/or export a private image.

The secret is automatically invalidated 5 seconds after first using it (e.g. after calling Hyperkit.image(fingerprint, secret: “…”). This allows one to both retrieve the image information and then export it with the same secret.

If you wish to delete a created secret without using it, you can pass the operation ID returned by this method to Hyperkit::Client::Images#Hyperkit#Hyperkit::Operations#Hyperkit::Operations::cancel_operation, as shown in the examples below.

Examples:

Generate a secret for an image

response = Hyperkit.create_image_secret("878cf0c70e14fec80aaf4d5e923670e68c45aa89fb05a481019bf086aec42649") #=> {
  :id => "c8e949d4-0b6e-45de-83c9-5b886ed0256b",
  :class => "token",
  :created_at => 2016-04-05 15:12:58 UTC,
  :updated_at => 2016-04-05 15:12:58 UTC,
  :status => "Running",
  :status_code => 103,
  :resources => {
    :images => ["/1.0/images/097e75d6f7419d3a5e204d8125582f2d7bdd4ee4c35bd324513321c645f0c415"]
  },
  :metadata => {
    :secret => "be517e0a22918980ab76013a78dc55fb62f1d7f1d97f445a77819fa0e643dd4f"
  },
  :may_cancel => true,
  :err => ""
}
secret = response.metadata.secret

Generate a secret for an image using a prefix of its fingerprint

Hyperkit.create_image_secret("878").metadata.secret

Delete a secret for an image without using it

response = Hyperkit.create_image_secret("878")
Hyperkit.cancel_operation(response.id)

Parameters:

  • fingerprint (String) —

    Fingerprint of the image. This can be a prefix of an image’s fingerprint, as long as it is unambiguous.

Returns:

  • (Sawyer::Response) —

    An asynchronous response containing the generated secret



472
473
474
 
# File 'lib/hyperkit/client/images.rb', line 472

def create_image_secret(fingerprint)
  post(File.join(image_path(fingerprint), "secret")).metadata
end

#delete_image(fingerprint, options = {}) ⇒ Sawyer::Resource

Delete an image

Examples:

Delete an image using its fingerprint

image = Hyperkit.image_by_alias("ubuntu/xenial/amd64")
Hyperkit.delete_image(image.fingerprint)

Delete an image using a prefix of its fingerprint

Hyperkit.delete_image("b41")

Parameters:

  • fingerprint (String) —

    Fingerprint of image to delete. Can be a prefix of a fingerprint, as long as it is unambiguous.

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

    Additional data to be passed

Options Hash (options):

Returns:

  • (Sawyer::Resource) —

    Operation or result, depending value of :sync parameter and/or auto_sync

Asynchronous:



386
387
388
389
 
# File 'lib/hyperkit/client/images.rb', line 386

def delete_image(fingerprint, options={})
  response = delete(image_path(fingerprint)).metadata
  handle_async(response, options[:sync])
end

#delete_image_alias(alias_name) ⇒ Sawyer::Resource

Delete an alias for an image

Examples:

Delete alias “ubuntu/xenial/amd64”

Hyperkit.delete_image_alias("ubuntu/xenial/amd64")

Parameters:

  • alias_name (String) —

    Alias to delete

Returns:

  • (Sawyer::Resource) 


598
599
600
 
# File 'lib/hyperkit/client/images.rb', line 598

def delete_image_alias(alias_name)
  delete(image_alias_path(alias_name)).metadata
end

#export_image(fingerprint, output_dir, options = {}) ⇒ String

Export an image to a local file.

Examples:

Export image

image = Hyperkit.image_by_alias("busybox/default/amd64")
Hyperkit.export_image(image.fingerprint, "/tmp") => "/tmp/busybox-v1.21.1-lxc.tar.xz"

Override output filename

image = Hyperkit.image_by_alias("busybox/default/amd64")
Hyperkit.export_image(image.fingerprint,
  "/tmp", filename: "test.tar.xz") => "/tmp/test.tar.xz"

Export private image via secret (created by #create_image_secret)

image = Hyperkit.image_by_alias("busybox/default/amd64")
Hyperkit.export_image(image.fingerprint,
  "/tmp", secret: "secret-issued-by-create_image_secret") => "/tmp/busybox-v1.21.1-lxc.tar.xz"

Parameters:

  • fingerprint (String) —

    Fingerprint of the image

  • output_dir (String) —

    Output directory

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

    Additional data to be passed

Options Hash (options):

  • :filename (String) —

    Name of file in which to store exported image (default: image filename obtained from the server)

  • :secret (String) —

    Secret to export private image by untrusted client

Returns:

  • (String) —

    The name of the file saved



502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/hyperkit/client/images.rb', line 502

def export_image(fingerprint, output_dir, options={})

  img = image(fingerprint)
  filename = options[:filename] || img.filename
  output_file = File.join(output_dir, filename)

  url = File.join(image_path(fingerprint), "export")
  url << "?secret=#{options[:secret]}" if options[:secret]

  response = get(url)

  File.open(output_file, "wb") do |f|
    f.write response
  end

  output_file

end

#image(fingerprint, options = {}) ⇒ Sawyer::Resource

Get information on an image by its fingerprint

Examples:

Get information about an image on images.linuxcontainers.org

Hyperkit.api_endpoint = "https://images.linuxcontainers.org:8443"
Hyperkit.image("45bcc353f629b23ce30ef4cca14d2a4990c396d85ea68905795cc7579c145123") #=> {
  :properties=>{:description=>"Centos 6 (amd64) (20160314_02:16)"},
  :expires_at=>1970-01-01 00:00:00 UTC,
  :filename=>"centos-6-amd64-default-20160314_02:16.tar.xz",
  :uploaded_at=>2016-03-15 01:20:10 UTC,
  :size=>54717798,
  :public=>true,
  :architecture=>"x86_64",
  :aliases=>[],
  :created_at=>2016-03-15 01:20:10 UTC,
  :fingerprint=> "45bcc353f629b23ce30ef4cca14d2a4990c396d85ea68905795cc7579c145123"
}

Get information about an image via an image fingerprint

Hyperkit.image("45b")

Get information about a private image using a secret (created with #create_image_secret):

Hyperkit.image("45bcc353f629b23ce30ef4cca14d2a4990c396d85ea68905795cc7579c145123",
  secret: "secret-issued-by-create_image_secret")

Parameters:

  • fingerprint (String) —

    The image’s fingerprint. Can be a prefix of a fingerprint, as long as it is unambiguous.

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

    Additional data to be passed

Options Hash (options):

  • :secret (String) —

    Secret to access private image by untrusted client

Returns:

  • (Sawyer::Resource) —

    Image information



53
54
55
56
57
58
59
 
# File 'lib/hyperkit/client/images.rb', line 53

def image(fingerprint, options={})

  url = image_path(fingerprint)
  url << "?secret=#{options[:secret]}" if options[:secret]

  get(url).metadata
end

#image_alias(alias_name) ⇒ Sawyer::Resource

Get information on an image alias

Examples:

Get information about an alias on images.linuxcontainers.org

Hyperkit.api_endpoint = "https://images.linuxcontainers.org:8443"
Hyperkit.image_alias("ubuntu/xenial/amd64/default") #=> {
  :name=>"ubuntu/xenial/amd64/default",
  :target=>"878cf0c70e14fec80aaf4d5e923670e68c45aa89fb05a481019bf086aec42649"
}

Parameters:

  • alias_name (String) —

    An image alias

Returns:

  • (Sawyer::Resource) —

    Alias information



560
561
562
 
# File 'lib/hyperkit/client/images.rb', line 560

def image_alias(alias_name)
  get(image_alias_path(alias_name)).metadata
end

#image_aliases ⇒ Array<String>

List of image aliases on the server (public or private)

Examples:

Get list of image aliases

Hyperkit.images #=> [
  "ubuntu/xenial/amd64/default",
  "ubuntu/xenial/amd64",
  "ubuntu/xenial/armhf/default",
  "ubuntu/xenial/armhf",
  "ubuntu/xenial/i386/default",
  "ubuntu/xenial/i386",
  "ubuntu/xenial/powerpc/default",
  "ubuntu/xenial/powerpc",
  "ubuntu/xenial/ppc64el/default",
  "ubuntu/xenial/ppc64el",
  "ubuntu/xenial/s390x/default",
  "ubuntu/xenial/s390x"
]

Returns:

  • (Array<String>) —

    An array of image aliases



544
545
546
547
 
# File 'lib/hyperkit/client/images.rb', line 544

def image_aliases
  response = get(image_aliases_path)
  response.metadata.map { |path| path.sub("#{image_aliases_path}/","") }
end

#image_by_alias(alias_name, options = {}) ⇒ Sawyer::Resource

Get information on an image by one of its aliases

Examples:

Get information about an image on images.linuxcontainers.org

Hyperkit.api_endpoint = "https://images.linuxcontainers.org:8443"
Hyperkit.image_by_alias("ubuntu/xenial/amd64") #=> {
  :fingerprint=> "878cf0c70e14fec80aaf4d5e923670e68c45aa89fb05a481019bf086aec42649",
  :expires_at=>1970-01-01 00:00:00 UTC,
  :size=>88239818,
  :architecture=>"x86_64",
  :created_at=>2016-03-16 04:53:46 UTC,
  :filename=>"ubuntu-xenial-amd64-default-20160316_03:49.tar.xz",
  :uploaded_at=>2016-03-16 04:53:46 UTC,
  :aliases=>
    [{:name=>"ubuntu/xenial/amd64/default",
      :target=>"ubuntu/xenial/amd64/default",
      :description=>"Ubuntu xenial (amd64) (default)"},
     {:name=>"ubuntu/xenial/amd64",
      :target=>"ubuntu/xenial/amd64",
      :description=>"Ubuntu xenial (amd64)"}],
  :properties=>{:description=>"Ubuntu xenial (amd64) (20160316_03:49)"},
  :public=>true}
}

Get information about a private image using a secret (created with #create_image_secret):

Hyperkit.image_by_alias("ubuntu/xenial/amd64",
  secret: "secret-issued-by-create_image_secret")

Parameters:

  • alias_name (String) —

    An alias of the image

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

    Additional data to be passed

Options Hash (options):

  • :secret (String) —

    Secret to access private image by untrusted client

Returns:

  • (Sawyer::Resource) —

    Image information



92
93
94
95
 
# File 'lib/hyperkit/client/images.rb', line 92

def image_by_alias(alias_name, options={})
  a = image_alias(alias_name)
  image(a.target, options)
end

#images ⇒ Array<String>

List of images on the server (public or private)

Examples:

Get list of images

Hyperkit.images #=> ["54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473",
                            "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc"]

Returns:

  • (Array<String>) —

    An array of image fingerprints



20
21
22
23
 
# File 'lib/hyperkit/client/images.rb', line 20

def images
  response = get(images_path)
  response.metadata.map { |path| path.split('/').last }
end

#rename_image_alias(old_alias, new_alias) ⇒ Sawyer::Resource

Rename an image alias

Examples:

Rename alias “ubuntu/xenial/amd64” to “ubuntu/xenial/default”

Hyperkit.rename_image_alias("ubuntu/xenial/amd64", "ubuntu/xenial/default")

Parameters:

  • old_alias (String) —

    Alias to rename

  • new_alias (String) —

    New alias

Returns:

  • (Sawyer::Resource) 


610
611
612
 
# File 'lib/hyperkit/client/images.rb', line 610

def rename_image_alias(old_alias, new_alias)
  post(image_alias_path(old_alias), { name: new_alias }).metadata
end

#update_image(fingerprint, options = {}) ⇒ Sawyer::Resource

Update the attributes of an image

Examples:

Set image to be publicly-accessible

Hyperkit.update_image("b1cf3d836196c316897d39872ff25e2d912ea933207b0c591334a67b290a5f1b",
  public: true)

Overwrite image properties (removes all existing properties, sets “hello” property to “world”)

Hyperkit.update_image("b1cf3d836196c316897d39872ff25e2d912ea933207b0c591334a67b290a5f1b",
  properties: {
    hello: "world"
  }
)

Update image properties (leaves all existing properties intact, sets “hello” property to “world”)

fingerprint = "b1cf3d836196c316897d39872ff25e2d912ea933207b0c591334a67b290a5f1b"

image = Hyperkit.image(fingerprint)

Hyperkit.update_image(fingerprint)
  image.properties.to_hash.merge({
    hello: "world"
  })
)

Parameters:

  • fingerprint (String) —

    Fingerprint of image to update

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

    Additional data to be passed

Options Hash (options):

  • :auto_update (Boolean) —

    Whether or not the image should be automatically updated from the source server (source image must be public and must have been referenced by alias when originally created – not fingerprint)

  • :properties (Hash) —

    Hash of additional properties to store with the image. Existing properties are removed. See the Examples section.

  • :public (Boolean) —

    Whether or not the image should be publicly-accessible to unauthenticated users

Returns:

  • (Sawyer::Resource) 


425
426
427
428
429
430
 
# File 'lib/hyperkit/client/images.rb', line 425

def update_image(fingerprint, options={})
  opts = options.slice(:public, :auto_update)
  opts[:properties] = stringify_hash(options[:properties]) if options[:properties]

  put(image_path(fingerprint), opts).metadata
end

#update_image_alias(alias_name, options = {}) ⇒ Sawyer::Resource

Update an image alias

Examples:

Update alias “ubuntu/xenial/amd64” to point to image “097…”

Hyperkit.update_image_alias("ubuntu/xenial/amd64",
  target: "097e75d6f7419d3a5e204d8125582f2d7bdd4ee4c35bd324513321c645f0c415")

Update alias “ubuntu/xenial/amd64” with a new description

Hyperkit.update_image_alias("ubuntu/xenial/amd64", description: "Ubuntu 16.04")

Parameters:

  • alias_name (String) —

    Alias to update

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

    Additional data to be passed

Options Hash (options):

  • :target (String) —

    Image fingerprint

  • :description (String) —

    Alias description

Returns:

  • (Sawyer::Resource) 


628
629
630
631
632
633
634
635
636
637
638
639
 
# File 'lib/hyperkit/client/images.rb', line 628

def update_image_alias(alias_name, options={})

  if options.empty?
    raise Hyperkit::AliasAttributesRequired.new("At least one of :target or :description required")
  end

  existing_options = image_alias(alias_name).to_hash
  opts = existing_options.slice(:description, :target).
                          merge(options.slice(:description, :target))

  put(image_alias_path(alias_name), opts).metadata
end