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

Class: AWS::EC2::Image

Inherits:
Resource
  • Object
show all
Includes:
HasPermissions, TaggedItem
Defined in:
lib/aws/ec2/image.rb

Overview

Represents an Amazon Machine Image (AMI).

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from HasPermissions

#permissions, #private?, #public=, #public?

Methods included from TaggedItem

#add_tag, #clear_tags, #tags

Constructor Details

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

Returns a new instance of Image

Parameters:

  • image_id (String) 


97
98
99
100
 
# File 'lib/aws/ec2/image.rb', line 97

def initialize image_id, options = {}
  @image_id = image_id
  super
end

Instance Attribute Details

#architecture ⇒ Symbol (readonly)

The architecture of the image (e.g. :i386).

Returns:

  • (Symbol) —

    the current value of architecture



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def architecture
  @architecture
end

#creation_date ⇒ String (readonly)

The date and time the image was created in ISO-8601 format

Returns:

  • (String) —

    the current value of creation_date



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def creation_date
  @creation_date
end

#description ⇒ String

A description of the image.

Returns:

  • (String) —

    the current value of description



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def description
  @description
end

#hypervisor ⇒ Symbol (readonly)

The image's hypervisor type. Possible values are:

  • :ovm
  • :xen

Returns:

  • (Symbol) —

    the current value of hypervisor



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def hypervisor
  @hypervisor
end

#image_id ⇒ String (readonly) Also known as: id

Returns The ID of the AMI.

Returns:

  • (String) —

    The ID of the AMI.



103
104
105
 
# File 'lib/aws/ec2/image.rb', line 103

def image_id
  @image_id
end

#kernel_id ⇒ String (readonly)

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

Returns:

  • (String) —

    the current value of kernel_id



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def kernel_id
  @kernel_id
end

#location ⇒ String (readonly)

The location of the AMI.

Returns:

  • (String) —

    the current value of location



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def location
  @location
end

#name ⇒ String (readonly)

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

Returns:

  • (String) —

    the current value of name



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def name
  @name
end

#owner_alias ⇒ String (readonly)

The AWS account alias (e.g., "amazon") or AWS account ID that owns the AMI.

Returns:

  • (String) —

    the current value of owner_alias



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def owner_alias
  @owner_alias
end

#owner_id ⇒ String (readonly)

The AWS account ID of the image owner.

Returns:

  • (String) —

    the current value of owner_id



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def owner_id
  @owner_id
end

#platform ⇒ String (readonly)

Value is windows for Windows AMIs; otherwise blank.

Returns:

  • (String) —

    the current value of platform



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def platform
  @platform
end

#product_codes ⇒ Array<String> (readonly)

Returns an array of product codes attached to this instance.

Returns:

  • (Array<String>) —

    the current value of product_codes



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def product_codes
  @product_codes
end

#ramdisk_id ⇒ String (readonly)

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

Returns:

  • (String) —

    the current value of ramdisk_id



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def ramdisk_id
  @ramdisk_id
end

#root_device_name ⇒ String (readonly)

The root device name (e.g., "/dev/sda1", or "xvda").

Returns:

  • (String) —

    the current value of root_device_name



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def root_device_name
  @root_device_name
end

#root_device_type ⇒ Symbol (readonly)

The root device type used by the AMI. Possible values:

  • :ebs
  • :instance_store

Returns:

  • (Symbol) —

    the current value of root_device_type



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def root_device_type
  @root_device_type
end

#state ⇒ Symbol (readonly)

Current state of the AMI. If the state is :available, the image is successfully registered and available for launching. Valid values:

  • :available
  • :pending
  • :failed

Returns:

  • (Symbol) —

    the current value of state



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def state
  @state
end

#state_reason ⇒ Object (readonly)

The reason for the image's most recent state change. The return value is an object with the following methods:

  • code - Reason code for the state change.
  • message - A textual description of the state change.

Returns:

  • (Object) —

    the current value of state_reason



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def state_reason
  @state_reason
end

#type ⇒ Symbol (readonly)

The type of image. Valid values are:

  • :machine
  • :kernel
  • :ramdisk

Returns:

  • (Symbol) —

    the current value of type



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def type
  @type
end

#virtualization_type ⇒ Symbol (readonly)

The type of virtualization of the AMI. Possible values:

  • :paravirtual
  • :hvm

Returns:

  • (Symbol) —

    the current value of virtualization_type



91
92
93
 
# File 'lib/aws/ec2/image.rb', line 91

def virtualization_type
  @virtualization_type
end

Instance Method Details

#add_product_codes(*product_codes) ⇒ nil

Adds one or more product codes:

image.add_product_codes 'ABCXYZ', 'MNOPQR'

You can also pass an array of product codes:

image.add_product_codes ['ABCXYZ', 'MNOPQR']

Parameters:

  • product_codes (Array<String>)

Returns:

  • (nil) 


258
259
260
261
262
263
264
 
# File 'lib/aws/ec2/image.rb', line 258

def add_product_codes *product_codes
  client_opts = {}
  client_opts[:image_id] = self.id
  client_opts[:product_codes] = product_codes.flatten
  client.modify_image_attribute(client_opts)
  nil
end

#block_device_mappings ⇒ Hash

Note:

This method will not return data for ephemeral volumes.

Returns a hash of block device mappings for the image. In each entry, the key is the device name (e.g. "/dev/sda1") and the value is an hash with the following keys that return information about the block device:

  • :snapshot_id - The ID of the snapshot that will be used to create this device (may be nil).
  • :volume_size - The size of the volume, in GiBs.
  • :delete_on_termination - True if the Amazon EBS volume is deleted on instance termination.

Returns:

  • (Hash) —

    Returns a hash of block device mappings for the image. In each entry, the key is the device name (e.g. "/dev/sda1") and the value is an hash with the following keys that return information about the block device:

    • :snapshot_id - The ID of the snapshot that will be used to create this device (may be nil).
    • :volume_size - The size of the volume, in GiBs.
    • :delete_on_termination - True if the Amazon EBS volume is deleted on instance termination.

See Also:

  • AWS::EC2::Image.{{#block_devices}


171
172
173
174
175
176
177
178
 
# File 'lib/aws/ec2/image.rb', line 171

def block_device_mappings
  (block_device_mapping || []).inject({}) do |h, mapping|
    if ebs = mapping[:ebs]
      h[mapping[:device_name]] = ebs
    end
    h
  end
end

#block_devices ⇒ Array<Hash>

Returns a list of all block device mappings. This list may contain ephemeral volumes.

Returns:

  • (Array<Hash>) —

    Returns a list of all block device mappings. This list may contain ephemeral volumes.



182
183
184
 
# File 'lib/aws/ec2/image.rb', line 182

def block_devices
  block_device_mapping.to_a
end

#deregister ⇒ nil Also known as: delete

Deregisters this AMI. Once deregistered, the AMI cannot be used to launch new instances.

Returns:

  • (nil) 


189
190
191
192
 
# File 'lib/aws/ec2/image.rb', line 189

def deregister
  client.deregister_image(:image_id => id)
  nil
end

#exists? ⇒ Boolean

Returns true if the AMI exists (is returned by the DescribeImages action).

Returns:

  • (Boolean) —

    Returns true if the AMI exists (is returned by the DescribeImages action).



223
224
225
226
227
228
 
# File 'lib/aws/ec2/image.rb', line 223

def exists?
  resp = client.describe_images(:filters => [
    { :name => "image-id", :values => [id] }
  ])
  !resp.images_set.empty?
end

#kernel ⇒ Image

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

Returns:

  • (Image) —

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



232
233
234
235
236
 
# File 'lib/aws/ec2/image.rb', line 232

def kernel
  if id = kernel_id
    Image.new(id, :config => config)
  end
end

#ramdisk ⇒ Image

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

Returns:

  • (Image) —

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



240
241
242
243
244
 
# File 'lib/aws/ec2/image.rb', line 240

def ramdisk
  if id = ramdisk_id
    Image.new(id, :config => config)
  end
end

#run_instance(options = {}) ⇒ Instance or Array

Runs a single instance of this image.

Parameters:

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

Options Hash (options):

  • :count (Integer) —

    How many instances to request. By default one instance is requested. You can specify this either as an integer or as a Range, to indicate the minimum and maximum number of instances to run. Note that for a new account you can request at most 20 instances at once.

  • :iam_instance_profile (String) —

    The name or ARN of an IAM instance profile. This provides credentials to the EC2 instance(s) via the instance metadata service.

  • :block_device_mappings (Array<Hash>) —

    Specifies how block devices are exposed to the instance. Each mapping is made up of a virtualName and a deviceName.

    • :virtual_name - (String) Specifies the virtual device name.
    • :device_name - (String) Specifies the device name (e.g., /dev/sdh).
    • :ebs - (Hash) Specifies parameters used to automatically setup Amazon EBS volumes when the instance is launched.
      • :snapshot_id - (String) The ID of the snapshot from which the volume will be created.
      • :volume_size - (Integer) The size of the volume, in gigabytes.
      • :delete_on_termination - (Boolean) Specifies whether the Amazon EBS volume is deleted on instance termination.
      • :volume_type - (String) Valid values include:
        • standard
        • io1
        • gp2
      • :iops - (Integer)
    • :no_device - (String) Specifies the device name to suppress during instance launch.
  • :monitoring_enabled (Boolean) —

    Setting this to true enables CloudWatch monitoring on the instances once they are started.

  • :availability_zone (String) —

    Specifies the availability zone where the instance should run. Without this option, EC2 will choose an availability zone for you.

  • :placement_group (String) —

    Specifies the cluster placement group where the instance should run.

  • :image_id (String) —

    ID of the AMI you want to launch.

  • :key_name (String) —

    The name of the key pair to use. Note: Launching public images without a key pair ID will leave them inaccessible.

  • :key_pair (KeyPair) —

    A KeyPair that should be used when launching an instance.

  • :security_groups (Array) —

    Security groups are used to determine network access rules for the instances. :security_groups can be a single value or an array of values. Values should be group name strings or SecurityGroup objects.

  • :security_group_ids (Array<String>) —

    Security groups are used to determine network access rules for the instances. :security_group_ids accepts a single ID or an array of security group IDs.

  • :user_data (String) —

    Arbitrary user data. You do not need to encode this value.

  • :instance_type (String) —

    The type of instance to launch, for example "m1.small".

  • :kernel_id (String) —

    The ID of the kernel with which to launch the instance.

  • :ramdisk_id (String) —

    The ID of the RAM disk to select. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk. To find kernel requirements, refer to the Resource Center and search for the kernel ID.

  • :disable_api_termination (Boolean) —

    Specifies whether you can terminate the instance using the EC2 API. A value of true means you can't terminate the instance using the API (i.e., the instance is "locked"); a value of false means you can. If you set this to true, and you later want to terminate the instance, you must first enable API termination. For example:

    i = ec2.instances.create(:image_id => "ami-8c1fece5",
                         :disable_api_termination => true)
i.api_termination_disabled?        # => true
i.terminate                        # raises an exception
i.api_termination_disabled = false
i.terminate                        # terminates the instance
  • :instance_initiated_shutdown_behavior (String) —

    Determines whether the instance stops or terminates on instance-initiated shutdown.

  • :subnet (Subnet, String) — default: nil —

    The VPC Subnet (or subnet id string) to launch the instance in.

  • :private_ip_address (String) — default: nil —

    If you're using VPC, you can optionally use this option to assign the instance a specific available IP address from the subnet (e.g., '10.0.0.25'). This option is not valid for instances launched outside a VPC (i.e. those launched without the :subnet option).

  • :dedicated_tenancy (Boolean) — default: false —

    Instances with dedicated tenancy will not share physical hardware with instances outside their VPC. NOTE: Dedicated tenancy incurs an additional service charge. This option is not valid for instances launched outside a VPC (e.g. those launched without the :subnet option).

  • :ebs_optimized (Boolean) — default: false —

    EBS-Optimized instances enable Amazon EC2 instances to fully utilize the IOPS provisioned on an EBS volume. EBS-optimized instances deliver dedicated throughput between Amazon EC2 and Amazon EBS, with options between 500 Mbps and 1000 Mbps depending on the instance type used. When attached to EBS-Optimized instances, Provisioned IOPS volumes are designed to deliver within 10% of their provisioned performance 99.9% of the time. NOTE: EBS Optimized instances incur an additional service charge. This optional is only valid for certain instance types.

  • :associate_public_ip_address (Boolean) — default: false

Returns:

  • (Instance or Array) —

    If a single instance is being created, this returns an AWS::EC2::Instance to represent the newly created instance. Otherwise it returns an array of instance objects.



201
202
203
204
 
# File 'lib/aws/ec2/image.rb', line 201

def run_instance options = {}
  instances = InstanceCollection.new(:config => config)
  instances.create(options.merge(:image => self))
end

#run_instances(count, options = {}) ⇒ Array<Instance>

Runs multiple instances of this image.

Parameters:

  • count (Integer) —

    How many instances to request. You can specify this either as an integer or as a Range, to indicate the minimum and maximum number of instances to run. Note that for a new account you can request at most 20 instances at a time.

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

Options Hash (options):

  • :count (Integer) —

    How many instances to request. By default one instance is requested. You can specify this either as an integer or as a Range, to indicate the minimum and maximum number of instances to run. Note that for a new account you can request at most 20 instances at once.

  • :iam_instance_profile (String) —

    The name or ARN of an IAM instance profile. This provides credentials to the EC2 instance(s) via the instance metadata service.

  • :block_device_mappings (Array<Hash>) —

    Specifies how block devices are exposed to the instance. Each mapping is made up of a virtualName and a deviceName.

    • :virtual_name - (String) Specifies the virtual device name.
    • :device_name - (String) Specifies the device name (e.g., /dev/sdh).
    • :ebs - (Hash) Specifies parameters used to automatically setup Amazon EBS volumes when the instance is launched.
      • :snapshot_id - (String) The ID of the snapshot from which the volume will be created.
      • :volume_size - (Integer) The size of the volume, in gigabytes.
      • :delete_on_termination - (Boolean) Specifies whether the Amazon EBS volume is deleted on instance termination.
      • :volume_type - (String) Valid values include:
        • standard
        • io1
        • gp2
      • :iops - (Integer)
    • :no_device - (String) Specifies the device name to suppress during instance launch.
  • :monitoring_enabled (Boolean) —

    Setting this to true enables CloudWatch monitoring on the instances once they are started.

  • :availability_zone (String) —

    Specifies the availability zone where the instance should run. Without this option, EC2 will choose an availability zone for you.

  • :placement_group (String) —

    Specifies the cluster placement group where the instance should run.

  • :image_id (String) —

    ID of the AMI you want to launch.

  • :key_name (String) —

    The name of the key pair to use. Note: Launching public images without a key pair ID will leave them inaccessible.

  • :key_pair (KeyPair) —

    A KeyPair that should be used when launching an instance.

  • :security_groups (Array) —

    Security groups are used to determine network access rules for the instances. :security_groups can be a single value or an array of values. Values should be group name strings or SecurityGroup objects.

  • :security_group_ids (Array<String>) —

    Security groups are used to determine network access rules for the instances. :security_group_ids accepts a single ID or an array of security group IDs.

  • :user_data (String) —

    Arbitrary user data. You do not need to encode this value.

  • :instance_type (String) —

    The type of instance to launch, for example "m1.small".

  • :kernel_id (String) —

    The ID of the kernel with which to launch the instance.

  • :ramdisk_id (String) —

    The ID of the RAM disk to select. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk. To find kernel requirements, refer to the Resource Center and search for the kernel ID.

  • :disable_api_termination (Boolean) —

    Specifies whether you can terminate the instance using the EC2 API. A value of true means you can't terminate the instance using the API (i.e., the instance is "locked"); a value of false means you can. If you set this to true, and you later want to terminate the instance, you must first enable API termination. For example:

    i = ec2.instances.create(:image_id => "ami-8c1fece5",
                         :disable_api_termination => true)
i.api_termination_disabled?        # => true
i.terminate                        # raises an exception
i.api_termination_disabled = false
i.terminate                        # terminates the instance
  • :instance_initiated_shutdown_behavior (String) —

    Determines whether the instance stops or terminates on instance-initiated shutdown.

  • :subnet (Subnet, String) — default: nil —

    The VPC Subnet (or subnet id string) to launch the instance in.

  • :private_ip_address (String) — default: nil —

    If you're using VPC, you can optionally use this option to assign the instance a specific available IP address from the subnet (e.g., '10.0.0.25'). This option is not valid for instances launched outside a VPC (i.e. those launched without the :subnet option).

  • :dedicated_tenancy (Boolean) — default: false —

    Instances with dedicated tenancy will not share physical hardware with instances outside their VPC. NOTE: Dedicated tenancy incurs an additional service charge. This option is not valid for instances launched outside a VPC (e.g. those launched without the :subnet option).

  • :ebs_optimized (Boolean) — default: false —

    EBS-Optimized instances enable Amazon EC2 instances to fully utilize the IOPS provisioned on an EBS volume. EBS-optimized instances deliver dedicated throughput between Amazon EC2 and Amazon EBS, with options between 500 Mbps and 1000 Mbps depending on the instance type used. When attached to EBS-Optimized instances, Provisioned IOPS volumes are designed to deliver within 10% of their provisioned performance 99.9% of the time. NOTE: EBS Optimized instances incur an additional service charge. This optional is only valid for certain instance types.

  • :associate_public_ip_address (Boolean) — default: false

Returns:



217
218
219
 
# File 'lib/aws/ec2/image.rb', line 217

def run_instances count, options = {}
  run_instance(options.merge(:count => count))
end