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

Instance Attribute Details

#architecture ⇒ Symbol (readonly)

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

Returns:

  • (Symbol) —

    the current value of architecture



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

def architecture
  @architecture
end

#description ⇒ String

A description of the image.

Returns:

  • (String) —

    the current value of description



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

def description
  @description
end

#hypervisor ⇒ Symbol (readonly)

The image’s hypervisor type.

Possible values are:

  • :ovm

  • :xen

Returns:

  • (Symbol) —

    the current value of hypervisor



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

def hypervisor
  @hypervisor
end

#id ⇒ String (readonly)

Returns The ID of the AMI.

Returns:

  • (String) —

    The ID of the AMI.



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

def id
  @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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

def kernel_id
  @kernel_id
end

#location ⇒ String (readonly)

The location of the AMI.

Returns:

  • (String) —

    the current value of location



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

def owner_id
  @owner_id
end

#platform ⇒ String (readonly)

Value is windows for Windows AMIs; otherwise blank.

Returns:

  • (String) —

    the current value of platform



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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



84
85
86
 
# File 'lib/aws/ec2/image.rb', line 84

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) 


248
249
250
251
252
253
254
 
# File 'lib/aws/ec2/image.rb', line 248

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}


161
162
163
164
165
166
167
168
 
# File 'lib/aws/ec2/image.rb', line 161

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.



172
173
174
 
# File 'lib/aws/ec2/image.rb', line 172

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) 


179
180
181
182
 
# File 'lib/aws/ec2/image.rb', line 179

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).



213
214
215
216
217
218
 
# File 'lib/aws/ec2/image.rb', line 213

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.



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

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.



230
231
232
233
234
 
# File 'lib/aws/ec2/image.rb', line 230

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 (Hash) —

    This must be a hash; the keys are device names to map, and the value for each entry determines how that device is mapped. Valid values include:

    • A string, which is interpreted as a virtual device name.

    • The symbol :no_device, which overrides the default mapping for a device so that it is not mapped to anything.

    • A hash with any of the following options. One of :snapshot, :snapshot_id or :volume_size is required.

      :snapshot

      A snapshot to use when creating the block device.

      :snapshot_id

      The ID of a snapshot to use when creating the block device.

      :volume_size

      The size of volume to create, in gigabytes.

      :delete_on_termination

      Setting this to true causes EC2 to delete the volume when the instance is terminated.

  • :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.

  • :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.

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.



191
192
193
194
 
# File 'lib/aws/ec2/image.rb', line 191

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 (Hash) —

    This must be a hash; the keys are device names to map, and the value for each entry determines how that device is mapped. Valid values include:

    • A string, which is interpreted as a virtual device name.

    • The symbol :no_device, which overrides the default mapping for a device so that it is not mapped to anything.

    • A hash with any of the following options. One of :snapshot, :snapshot_id or :volume_size is required.

      :snapshot

      A snapshot to use when creating the block device.

      :snapshot_id

      The ID of a snapshot to use when creating the block device.

      :volume_size

      The size of volume to create, in gigabytes.

      :delete_on_termination

      Setting this to true causes EC2 to delete the volume when the instance is terminated.

  • :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.

  • :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.

Returns:



207
208
209
 
# File 'lib/aws/ec2/image.rb', line 207

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