Class AWS::EC2::Instance
In: lib/aws/ec2/instance.rb
Parent: Resource

Represents an EC2 instance.

@attr [String] user_data Arbitrary metadata that is available

  to the instance while it is running.  This interface handles
  the details of encoding the user data for transmission; you
  should set the user data exactly as you want it to be made
  available to the instance.

  The instance must be in a stopped state to change user data;
  for example:

      i.user_data             # => "HELLO"
      i.status                # => :running
      i.user_data = "GOODBYE" # raises an exception
      i.stop; sleep 1 until i.status == :stopped
      i.user_data = "GOODBYE" # => "GOODBYE"

@attr [String] instance_type The instance type,

  e.g. "m1.small".  The instance must be in a stopped state to
  change the instance type.

@attr [Boolean] ebs_optimized The instance must be in a stopped state to

  change the ebs_optimized state.

@attr [Boolean] api_termination_disabled True if the instance

  cannot be terminated using the {#terminate} method.  This
  attribute can be changed at any time.

@attr [String] instance_initiated_shutdown_behavior Valid

  values are:

    * "stop"] When the instance shuts down, it will go into a
      "stopped" state.
    * "terminate"] When the instance shuts down, it will be
      terminated.

@attr [Boolean] source_dest_check

@attr_reader [String] image_id Image ID of the AMI used to

  launch the instance.

@attr_reader [String] key_name The name of the key pair with

  which this instance was associated at launch.

@attr [String] kernel_id The ID of the kernel that the image

  currently uses.  The instance must be in a stopped state to
  change this attribute.

@attr [String] ramdisk_id The ID of the RAM disk that the

  image currently uses.  The instance must be in a stopped
  state to change this attribute.

@attr_reader [Symbol] root_device_type The root device type

  used by the AMI. The AMI can use an Amazon EBS or instance
  store root device.  Valid values:

    * `:ebs`
    * `:instance_store`

@attr_reader [String] root_device_name The name of the root

  device.

@attr_reader [String] private_dns_name The DNS name of the

  instance within the EC2 network.

@attr_reader [String] dns_name The DNS name of the instance on

  the internet.

@attr_reader [Integer] ami_launch_index The AMI launch index,

  which can be used to find this instance within the launch
  group.

@attr_reader [String] private_ip_address The private IP

  address assigned to the instance.

@attr_reader [String] ip_address The IP address of the

  instance.

@attr_reader [Symbol] status The instance status.

  Valid values are:

    * `:pending`
    * `:running`
    * `:shutting_down`
    * `:terminated`
    * `:stopping`
    * `:stopped`

@attr_reader [Integer] status_code The numeric instance status code.

@attr_reader [Symbol] architecture The architecture of the image.

@attr_reader [Symbol] virtualization_type The instance‘s

  virtualization type.  Valid values:

    * `:paravirtual`
    * `:hvm`

@attr_reader [String] reservation_id The ID of the reservation

  in which this instance was launched.

@attr_reader [String] requester_id ID of the requester that

  launched the instance on your behalf (e.g., AWS Management
  Console, Auto Scaling).

@attr_reader [String] owner_id ID of the AWS account that owns

  the reservation in which the instance was launched.

@attr_reader [Symbol] monitoring The status of CloudWatch

  monitoring for the instance.  Valid values:

    * `:enabled`
    * `:disabled`
    * `:pending`

@attr_reader [String] state_transition_reason A string

  describing the reason for the last state transition.

@attr_reader [Time] launch_time The time at which the instance

  was launched.

@attr_reader [String] platform A string describing the

  platform of the image (e.g. "windows").

@attr_reader [Symbol] hypervisor The instance‘s hypervisor

  type.  Valid values:

    * `:ovm`
    * `:xen`

@attr_reader [String] client_token Idempotency token you

  provided when you launched the instance.

@attr_reader [String,nil] vpc_id Instances launched in a VPC have

  a vpc_id.  Normal EC2 instances return nil.

@attr_reader [String,nil] subnet_id Instances launched in a VPC have

  a subnet_id.  Normal EC2 instances return nil.

@attr_reader [String,nil] iam_instance_profile_id

@attr_reader [String,nil] iam_instance_profile_arn

Methods

Included Modules

TaggedItem

External Aliases

id -> instance_id
dns_name -> public_dns_name
ip_address -> public_ip_address
source_dest_check -> source_dest_check?

Attributes

id  [R]  @return [String] Returns the instance id.

Public Class methods

Creates an object that represents the instance with the given ID. It‘s usually easier to get an instance of this class by calling {InstanceCollection#[]} or {InstanceCollection#each}.

Public Instance methods

Associates the elastic IP address with this instance.

@overload associate_elastic_ip(elastic_ip)

  @param [ElasticIp,String] elastic_ip An Elastic ip address
    (VPC or non-VPC) or a public ip address string (non-VPC only).

@overload associate_elastic_ip(allocation_id)

  @param [String] allocation_id The allocation id of a
    VPC elastic ip address.

@return [nil]

Attaches a network interface to this instance (VPC only).

@param [NetworkInterface,String] network_interface A network interface

  (or network interface id string) to attach to this vpc instance.

@param [Hash] options

@option (see NetworkInterface#attach)

@return [nil]

@return [Hash<String,Attachment>] Returns a hash of attachments.

  The keys are device name strings (e.g. '/dev/sda') and the values
  are {Attachment} objects.

@note This method will not return data for ephemeral volumes. @see {block_devices}

@return [String] The availability zone where the instance is

  running.
block_device_mappings()

Alias for attachments

Returns a list of block device mappings.

    instance.block_devices
    #=>
    [
      {
        :device_name => "/dev/sda2",
        :ebs => {
          :volume_id => "vol-123",
          :status => "attaching",
          :attach_time => time,
          :delete_on_termination => true
        }
      }, {
        :device_name => "/dev/sdb",
        :virtual_name => "ephemeral0",
      }
    ]

@return [Array<Hash>] Returns a list of block device mappings. This

  list may contain ephemeral volumes.

Retrieves the console output for the instance, returning nil if it is not available yet. @return [String] the console output @return [nil] if no output is available

Creates an AMI from this instance.

@param [String] name A name for the new image you‘re

  creating.  Constraints: 3-128 alphanumeric characters,
  parenthesis (()), commas (,), slashes (/), dashes (-), or
  underscores(_)

@param [Hash] options Additional options for creating the image.

@option options [String] :description A description of the new image.

@option options [Boolean] :no_reboot By default this

  option is set to `false`, which means Amazon EC2
  attempts to cleanly shut down the instance before image
  creation and reboots the instance afterwards. When the
  option is set to `true`, Amazon EC2 does not shut down
  the instance before creating the image. When this option
  is used, file system integrity on the created image cannot
  be guaranteed.

@return [Image] The newly created image.

@return [Boolean] Returns true if the instance has dedicated tenancy.

  This will be false for all non-VPC instances.  Dedicated Tenancy
  comes at extra cost.
delete()

Alias for terminate

Disables monitoring for this instance. @return [nil]

Disassociates an attached elastic IP address from this instance. Raises an exception if there is no elastic IP address associated with this instance.

@return [ElasticIp,nil] Returns an elastic IP address if one

  is associated with this instance, nil otherwise.

Enables monitoring for this instance. @return [nil]

@return [Boolean] Returns true if the instance exists according to

  EC2.

This produces an image of an EC2 instance for use in another virtualization environment and then writes the image to a S3 bucket.

## Granting EC2 write access to your bucket

Before you can export an image to an S3 bucket, you must modify the bucket ACL. You only need to do this once per bucket.

    s3.buckets['bucket-name'].acl.change do |acl|
      acl.grant(:read_acp).to(:amazon_customer_email => 'vm-import-export@amazon.com')
      acl.grant(:write).to(:amazon_customer_email => 'vm-import-export@amazon.com')
    end

## Performing the export

Simply call export_to_s3 on your instance. Only instances derived from your own ImportInstance tasks may be exported.

     task = ec2.instances['i-12345678'].export_to_s3('bucket-name')

## Downloading the results

Given a completed export task you can download the final image:

    File.open('image.ova', 'wb') {|f| f.write(task.s3_object.read) }

@param [S3::Bucket,String] bucket The destination bucket. May

  be the name of the bucket (string) or a {S3::Bucket} object. The
  bucket must exist and grant write permissiosn to the AWS account
  'vm-import-export@amazon.com.'.

@param [Hash] options

@option options [String] :target_environment (‘vmware’) The target

  virtualization environment.  Valid values include: 'vmware', 'citrix'
  and 'microsoft'.

@option options [String] :disk_image_format The format for the exported

   image.  Defaults to 'vmdk' if `:target_environemnt` is 'vmware',
   otherwise, 'vhd'.

@option options [String] :container_format The container format used to

  combine disk images with metadata (such as OVF). If absent, only
  the disk image will be exported.  Defaults to 'ova' if
  `:target_environment` is 'vmware', otherwise ommited.

@option options [String] :description Description of the conversion

  task or the resource being exported.

@option options [String] :prefix (nil) The image is written to a

  single object in the bucket at the key:

      "#{prefix}#{export_task_id}.#{disk_image_format}"

@return [ExportTask]

groups()

Alias for security_groups

@return [Boolean] Returns true if an elastic IP address is

  associated with this instance, false otherwise.

@return [Image] The AMI used to launch the instance.

ip_address=(elastic_ip)

@return [KeyPair] The key pair with which this instance was

  associated at launch.

Enables or disables monitoring for this instance. @param [Boolean] state A true or false value. Enables monintoring

  for a true value, disables it for a false value.

@return [Booelan] Returns `true` if CloudWatch monitoring is

  enabled for this instance.

@return [Array<NetworkInterface>] Returns a list of elastic network

  interfaces attached to this instance (VPC only).  Non-vpc
  instance may not have attached network interfaces.

Reboots the instance. @return [nil]

Resets the kernel to its default value.

Resets the RAM disk to its default value.

@return [Array<SecurityGroup>] Returns a list of security

  groups the instance belongs to.

@return [Boolean] true if the instance is a Spot instance.

Starts the instance, assuming it is in a stopped state. @see stop @return [nil]

Stops the instance, eventually putting it into a stopped state. @return [nil]

@return [Subnet,nil] Returns the VPC subnet this instance was

  launched in.  Returns nil if this was not launched in a VPC.

Terminates the instance. @return [nil]

@return [VPC,nil] Returns the VPC this instance was launched in.

  If this instance was not launched inside a VPC, nil is returned.

@return [Boolean] Returns true if this is an EC2 VPC instance.

Protected Instance methods

[Validate]