You are viewing documentation for version 3 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: Aws::EC2::Image

Inherits:
Object
  • Object
show all
Defined in:
gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb

Defined Under Namespace

Classes: Collection

Actions collapse

Read-Only Attributes collapse

Instance Method Summary collapse

Constructor Details

#initialize(id, options = {}) ⇒ Image #initialize(options = {}) ⇒ Image

Returns a new instance of Image

Overloads:

  • #initialize(id, options = {}) ⇒ Image

    Parameters:

    • id (String)

    Options Hash (options):

  • #initialize(options = {}) ⇒ Image

    Options Hash (options):

    • :id (required, String)
    • :client (Client)


19
20
21
22
23
24
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 19

def initialize(*args)
  options = Hash === args.last ? args.pop.dup : {}
  @id = extract_id(args, options)
  @data = options.delete(:data)
  @client = options.delete(:client) || Client.new(options)
end

Instance Method Details

#architectureString

The architecture of the image.

Returns:

  • (String)


36
37
38
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 36

def architecture
  data[:architecture]
end

#block_device_mappingsArray<Types::BlockDeviceMapping>

Any block device mapping entries.

Returns:



107
108
109
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 107

def block_device_mappings
  data[:block_device_mappings]
end

#clientClient

Returns:



183
184
185
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 183

def client
  @client
end

#create_tags(options = {}) ⇒ Tag::Collection

Examples:

Request syntax with placeholder values


tag = image.create_tags({
  dry_run: false,
  tags: [ # required
    {
      key: "String",
      value: "String",
    },
  ],
})

Parameters:

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

    ({})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :tags (required, Array<Types::Tag>)

    One or more tags. The value parameter is required, but if you don't want the tag to have a value, specify the parameter with no value, and we set the value to an empty string.

Returns:



366
367
368
369
370
371
372
373
374
375
376
377
378
379
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 366

def create_tags(options = {})
  batch = []
  options = Aws::Util.deep_merge(options, resources: [@id])
  resp = @client.create_tags(options)
  options[:tags].each do |t|
    batch << Tag.new(
      resource_id: @id,
      key: t[:key],
      value: t[:value],
      client: @client
    )
  end
  Tag::Collection.new([batch], size: batch.size)
end

#creation_dateString

The date and time the image was created.

Returns:

  • (String)


42
43
44
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 42

def creation_date
  data[:creation_date]
end

#dataTypes::Image

Returns the data for this Aws::EC2::Image. Calls Client#describe_images if #data_loaded? is false.

Returns:



203
204
205
206
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 203

def data
  load unless @data
  @data
end

#data_loaded?Boolean

Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.

Returns:

  • (Boolean)

    Returns true if this resource is loaded. Accessing attributes or #data on an unloaded resource will trigger a call to #load.



211
212
213
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 211

def data_loaded?
  !!@data
end

#deregister(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


image.deregister({
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (EmptyStructure)


393
394
395
396
397
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 393

def deregister(options = {})
  options = options.merge(image_id: @id)
  resp = @client.deregister_image(options)
  resp.data
end

#describe_attribute(options = {}) ⇒ Types::ImageAttribute

Examples:

Request syntax with placeholder values


image.describe_attribute({
  attribute: "description", # required, accepts description, kernel, ramdisk, launchPermission, productCodes, blockDeviceMapping, sriovNetSupport
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :attribute (required, String)

    The AMI attribute.

    Note: Depending on your account privileges, the blockDeviceMapping attribute may return a Client.AuthFailure error. If this happens, use DescribeImages to get information about the block device mapping for the AMI.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:



419
420
421
422
423
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 419

def describe_attribute(options = {})
  options = options.merge(image_id: @id)
  resp = @client.describe_image_attribute(options)
  resp.data
end

#descriptionString

The description of the AMI that was provided during image creation.

Returns:

  • (String)


113
114
115
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 113

def description
  data[:description]
end

#ena_supportBoolean

Specifies whether enhanced networking with ENA is enabled.

Returns:

  • (Boolean)


119
120
121
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 119

def ena_support
  data[:ena_support]
end

#exists?(options = {}) ⇒ Boolean

Returns true if the Image exists.

Parameters:

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

    ({})

Returns:

  • (Boolean)

    Returns true if the Image exists.



218
219
220
221
222
223
224
225
226
227
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 218

def exists?(options = {})
  begin
    wait_until_exists(options.merge(max_attempts: 1))
    true
  rescue Aws::Waiters::Errors::UnexpectedError => e
    raise e.error
  rescue Aws::Waiters::Errors::WaiterFailed
    false
  end
end

#hypervisorString

The hypervisor type of the image.

Returns:

  • (String)


125
126
127
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 125

def hypervisor
  data[:hypervisor]
end

#idString Also known as: image_id

Returns:

  • (String)


29
30
31
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 29

def id
  @id
end

#image_locationString

The location of the AMI.

Returns:

  • (String)


48
49
50
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 48

def image_location
  data[:image_location]
end

#image_owner_aliasString

The AWS account alias (for example, amazon, self) or the AWS account ID of the AMI owner.

Returns:

  • (String)


132
133
134
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 132

def image_owner_alias
  data[:image_owner_alias]
end

#image_typeString

The type of image.

Returns:

  • (String)


54
55
56
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 54

def image_type
  data[:image_type]
end

#kernel_idString

The kernel associated with the image, if any. Only applicable for machine images.

Returns:

  • (String)


69
70
71
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 69

def kernel_id
  data[:kernel_id]
end

#loadself Also known as: reload

Loads, or reloads #data for the current Aws::EC2::Image. Returns self making it possible to chain methods.

image.reload.data

Returns:

  • (self)


193
194
195
196
197
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 193

def load
  resp = @client.describe_images(image_ids: [@id])
  @data = resp.images[0]
  self
end

#modify_attribute(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


image.modify_attribute({
  attribute: "String",
  description: "value", # value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>
  launch_permission: {
    add: [
      {
        group: "all", # accepts all
        user_id: "String",
      },
    ],
    remove: [
      {
        group: "all", # accepts all
        user_id: "String",
      },
    ],
  },
  operation_type: "add", # accepts add, remove
  product_codes: ["String"],
  user_groups: ["String"],
  user_ids: ["String"],
  value: "String",
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :attribute (String)

    The name of the attribute to modify. The valid values are description, launchPermission, and productCodes.

  • :description (Types::AttributeValue)

    A new description for the AMI.

  • :launch_permission (Types::LaunchPermissionModifications)

    A new launch permission for the AMI.

  • :operation_type (String)

    The operation type. This parameter can be used only when the Attribute parameter is launchPermission.

  • :product_codes (Array<String>)

    One or more DevPay product codes. After you add a product code to an AMI, it can't be removed.

  • :user_groups (Array<String>)

    One or more user groups. This parameter can be used only when the Attribute parameter is launchPermission.

  • :user_ids (Array<String>)

    One or more AWS account IDs. This parameter can be used only when the Attribute parameter is launchPermission.

  • :value (String)

    The value of the attribute being modified. This parameter can be used only when the Attribute parameter is description or productCodes.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (EmptyStructure)


481
482
483
484
485
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 481

def modify_attribute(options = {})
  options = options.merge(image_id: @id)
  resp = @client.modify_image_attribute(options)
  resp.data
end

#nameString

The name of the AMI that was provided during image creation.

Returns:

  • (String)


138
139
140
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 138

def name
  data[:name]
end

#owner_idString

The AWS account ID of the image owner.

Returns:

  • (String)


75
76
77
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 75

def owner_id
  data[:owner_id]
end

#platformString

The value is Windows for Windows AMIs; otherwise blank.

Returns:

  • (String)


81
82
83
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 81

def platform
  data[:platform]
end

#product_codesArray<Types::ProductCode>

Any product codes associated with the AMI.

Returns:



87
88
89
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 87

def product_codes
  data[:product_codes]
end

#publicBoolean

Indicates whether the image has public launch permissions. The value is true if this image has public launch permissions or false if it has only implicit and explicit launch permissions.

Returns:

  • (Boolean)


62
63
64
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 62

def public
  data[:public]
end

#ramdisk_idString

The RAM disk associated with the image, if any. Only applicable for machine images.

Returns:

  • (String)


94
95
96
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 94

def ramdisk_id
  data[:ramdisk_id]
end

#reset_attribute(options = {}) ⇒ EmptyStructure

Examples:

Request syntax with placeholder values


image.reset_attribute({
  attribute: "launchPermission", # required, accepts launchPermission
  dry_run: false,
})

Parameters:

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

    ({})

Options Hash (options):

  • :attribute (required, String)

    The attribute to reset (currently you can only reset the launch permission attribute).

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (EmptyStructure)


503
504
505
506
507
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 503

def reset_attribute(options = {})
  options = options.merge(image_id: @id)
  resp = @client.reset_image_attribute(options)
  resp.data
end

#root_device_nameString

The device name of the root device volume (for example, /dev/sda1).

Returns:

  • (String)


144
145
146
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 144

def root_device_name
  data[:root_device_name]
end

#root_device_typeString

The type of root device used by the AMI. The AMI can use an EBS volume or an instance store volume.

Returns:

  • (String)


151
152
153
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 151

def root_device_type
  data[:root_device_type]
end

#sriov_net_supportString

Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.

Returns:

  • (String)


158
159
160
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 158

def sriov_net_support
  data[:sriov_net_support]
end

#stateString

The current state of the AMI. If the state is available, the image is successfully registered and can be used to launch an instance.

Returns:

  • (String)


101
102
103
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 101

def state
  data[:state]
end

#state_reasonTypes::StateReason

The reason for the state change.

Returns:



164
165
166
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 164

def state_reason
  data[:state_reason]
end

#tagsArray<Types::Tag>

Any tags assigned to the image.

Returns:



170
171
172
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 170

def tags
  data[:tags]
end

#virtualization_typeString

The type of virtualization of the AMI.

Returns:

  • (String)


176
177
178
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 176

def virtualization_type
  data[:virtualization_type]
end

#wait_until(options = {}, &block) ⇒ Resource

Deprecated.

Use [Aws::EC2::Client] #wait_until instead

Note:

The waiting operation is performed on a copy. The original resource remains unchanged

Waiter polls an API operation until a resource enters a desired state.

Basic Usage

Waiter will polls until it is successful, it fails by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop until condition is true
resource.wait_until(options) {|resource| condition}

Example

instance.wait_until(max_attempts:10, delay:5) {|instance| instance.state.name == 'running' }

Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. The waiting condition is set by passing a block to #wait_until:

# poll for ~25 seconds
resource.wait_until(max_attempts:5,delay:5) {|resource|...}

Callbacks

You can be notified before each polling attempt and before each delay. If you throw :success or :failure from these callbacks, it will terminate the waiter.

started_at = Time.now
# poll for 1 hour, instead of a number of attempts
proc = Proc.new do |attempts, response|
  throw :failure if Time.now - started_at > 3600
end

  # disable max attempts
instance.wait_until(before_wait:proc, max_attempts:nil) {...}

Handling Errors

When a waiter is successful, it returns the Resource. When a waiter fails, it raises an error.

begin
  resource.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

attempts attempt in seconds invoked before each attempt invoked before each wait

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :max_attempts (Integer) — default: 10

    Maximum number of

  • :delay (Integer) — default: 10

    Delay between each

  • :before_attempt (Proc) — default: nil

    Callback

  • :before_wait (Proc) — default: nil

    Callback

Returns:

  • (Resource)

    if the waiter was successful

Raises:

  • (Aws::Waiters::Errors::FailureStateError)

    Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

    yet successful.

  • (Aws::Waiters::Errors::UnexpectedError)

    Raised when an error is encountered while polling for a resource that is not expected.

  • (NotImplementedError)

    Raised when the resource does not



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 325

def wait_until(options = {}, &block)
  self_copy = self.dup
  attempts = 0
  options[:max_attempts] = 10 unless options.key?(:max_attempts)
  options[:delay] ||= 10
  options[:poller] = Proc.new do
    attempts += 1
    if block.call(self_copy)
      [:success, self_copy]
    else
      self_copy.reload unless attempts == options[:max_attempts]
      :retry
    end
  end
  Aws::Waiters::Waiter.new(options).wait({})
end

#wait_until_exists(options = {}) ⇒ Image

Parameters:

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

    ({})

Options Hash (options):

  • :max_attempts (Integer) — default: 40
  • :delay (Float) — default: 15
  • :before_attempt (Proc)
  • :before_wait (Proc)

Returns:



235
236
237
238
239
240
241
242
243
244
245
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 235

def wait_until_exists(options = {})
  options, params = separate_params_and_options(options)
  waiter = Waiters::ImageExists.new(options)
  yield_waiter_and_warn(waiter, &Proc.new) if block_given?
  resp = waiter.wait(params.merge(image_ids: [@id]))
  Image.new({
    id: @id,
    data: resp.data.images[0],
    client: @client
  })
end