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:



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

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:



272
273
274
275
276
277
278
279
280
281
282
283
284
285
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 272

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:



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

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.



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

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)


299
300
301
302
303
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 299

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:



325
326
327
328
329
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 325

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.



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

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)


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

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.

  • :description (Types::AttributeValue)

    A description for the AMI.

  • :launch_permission (Types::LaunchPermissionModifications)

    A launch permission modification.

  • :operation_type (String)

    The operation type.

  • :product_codes (Array<String>)

    One or more product codes. After you add a product code to an AMI, it can't be removed. This is only valid when modifying the productCodes attribute.

  • :user_groups (Array<String>)

    One or more user groups. This is only valid when modifying the launchPermission attribute.

  • :user_ids (Array<String>)

    One or more AWS account IDs. This is only valid when modifying the launchPermission attribute.

  • :value (String)

    The value of the attribute being modified. This is only valid when modifying the description 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)


385
386
387
388
389
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 385

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)


407
408
409
410
411
# File 'gems/aws-sdk-ec2/lib/aws-sdk-ec2/image.rb', line 407

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 (for example, /dev/sda1 or /dev/xvda).

Returns:

  • (String)


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

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)


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

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)


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

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:



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

def state_reason
  data.state_reason
end

#tagsArray<Types::Tag>

Any tags assigned to the image.

Returns:



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

def tags
  data.tags
end

#virtualization_typeString

The type of virtualization of the AMI.

Returns:

  • (String)


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

def virtualization_type
  data.virtualization_type
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:



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

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