class AWS::EC2::Instance

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] 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_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.

Attributes

id[R]

@return [String] Returns the instance id.

instance_id[R]

@return [String] Returns the instance id.

Public Class Methods

describe_call_attribute(name, options = {}) click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 186
def self.describe_call_attribute name, options = {}, &block
  attr = attribute(name, options, &block)
  describe_call_attributes[attr.name] = attr
end

describe_call_attributes() click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 176
def self.describe_call_attributes
  @describe_call_attributes ||= {}
end

mutable_describe_attribute(name, options = {}) click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 198
def self.mutable_describe_attribute name, options = {}, &block
  attr = mutable_attribute(name, options, &block)
  mutable_describe_attributes[attr.name] = attr
end

mutable_describe_attributes() click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 181
def self.mutable_describe_attributes
  @mutable_describe_attributes ||= {}
end

mutable_describe_call_attribute(name, options = {}) click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 192
def self.mutable_describe_call_attribute name, options = {}, &block
  attr = mutable_attribute(name, options, &block)
  describe_call_attributes[attr.name] = attr
end

new(instance_id, opts = {}) click to toggle source

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 {AWS::EC2::InstanceCollection#each}.

# File lib/aws/ec2/instance.rb, line 155
def initialize(instance_id, opts = {})
  super
  @id = instance_id
end

reservation_attribute(name, options = {}) click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 170
def self.reservation_attribute name, options = {}, &block
  attr = attribute(name, options, &block)
  reservation_attributes[attr.name] = attr
end

reservation_attributes() click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 165
def self.reservation_attributes
  @reservation_attributes ||= {}
end

Public Instance Methods

associate_elastic_ip(elastic_ip) click to toggle source

Associates the elastic IP address with this instance.

@param [ElasticIp,String] #elastic_ip Either a public IP address

string or an {ElasticIp} object to associate to this 
instance.

@return [nil]

# File lib/aws/ec2/instance.rb, line 481
def associate_elastic_ip elastic_ip
  client.associate_address(
    :public_ip => elastic_ip.to_s,
    :instance_id => self.id
  )
  nil
end

Also aliased as: ip_address=

availability_zone() click to toggle source

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

running.

# File lib/aws/ec2/instance.rb, line 411
def availability_zone
  if p = placement
    p.availability_zone
  end
end

block_device_mappings() click to toggle source

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

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

# File lib/aws/ec2/instance.rb, line 367
def block_device_mappings
  (block_device_mapping || []).inject({}) do |m, mapping|
    device = mapping.device_name
    volume = Volume.new(mapping.ebs.volume_id, :config => config)
    attachment = Attachment.new(volume, self, device, :config => config)
    m[device] = attachment
    m
  end
end

console_output() click to toggle source

Retrieves the console output for the instance.

@return [String] the console output.

# File lib/aws/ec2/instance.rb, line 470
def console_output
  output = client.get_console_output(:instance_id => self.id).output
  Base64.decode64(output) if output
end

create_image(name, options = {}) click to toggle source

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.

# File lib/aws/ec2/instance.rb, line 462
def create_image name, options = {}
  images = ImageCollection.new(:config => config)
  images.create(options.merge(:instance_id => id, :name => name))
end

dedicated_tenancy?() click to toggle source

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

# File lib/aws/ec2/instance.rb, line 420
def dedicated_tenancy?
  if p = placement
    p.tenancy == 'dedicated'
  else
    false
  end
end

delete() click to toggle source

Alias for: terminate

disable_monitoring() click to toggle source

Disables monitoring for this instance. @return [nil]

# File lib/aws/ec2/instance.rb, line 386
def disable_monitoring
  client.unmonitor_instances(:instance_ids => [id])
  nil
end

disassociate_elastic_ip() click to toggle source

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

# File lib/aws/ec2/instance.rb, line 494
def disassociate_elastic_ip
  if ip = self.elastic_ip
    ip.disassociate
  else
    raise "instance #{id} does not have an associated elastic ip"
  end
end

elastic_ip() click to toggle source

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

is associated with this instance, nil otherwise.

# File lib/aws/ec2/instance.rb, line 504
def elastic_ip
  ips = ElasticIpCollection.new(:config => config)
  ips.filter('instance-id', id).first
end

enable_monitoring() click to toggle source

Enables monitoring for this instance. @return [nil]

# File lib/aws/ec2/instance.rb, line 379
def enable_monitoring
  client.monitor_instances(:instance_ids => [id])
  nil
end

exists?() click to toggle source

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

EC2.

# File lib/aws/ec2/instance.rb, line 517
def exists?
  client.describe_instances(:filters => [
    { :name => "instance-id", :values => [id] }
  ]).instance_index.key?(id)
end

groups() click to toggle source

Alias for: security_groups

has_elastic_ip?() click to toggle source

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

associated with this instance, false otherwise.

# File lib/aws/ec2/instance.rb, line 511
def has_elastic_ip?
  !elastic_ip.nil?
end

image() click to toggle source

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

# File lib/aws/ec2/instance.rb, line 429
def image
  Image.new(image_id, :config => config)
end

ip_address=(elastic_ip) click to toggle source

Alias for: associate_elastic_ip

key_pair() click to toggle source

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

associated at launch.

# File lib/aws/ec2/instance.rb, line 435
def key_pair
  KeyPair.new(key_name, :config => config) if key_name
end

monitoring_enabled=(value) click to toggle source

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.

# File lib/aws/ec2/instance.rb, line 394
def monitoring_enabled= value
  value ? enable_monitoring : disable_monitoring
end

monitoring_enabled?() click to toggle source

@return [Booelan] Returns true if CloudWatch monitoring is

enabled for this instance.

# File lib/aws/ec2/instance.rb, line 400
def monitoring_enabled?
  monitoring == :enabled
end

reboot() click to toggle source

Reboots the instance. @return [nil]

# File lib/aws/ec2/instance.rb, line 544
def reboot
  instance_action :reboot
end

reset_kernel_id() click to toggle source

Resets the kernel to its default value.

# File lib/aws/ec2/instance.rb, line 524
def reset_kernel_id
  client.reset_instance_attribute(
    :instance_id => id, :attribute => "kernel").return
end

reset_ramdisk_id() click to toggle source

Resets the RAM disk to its default value.

# File lib/aws/ec2/instance.rb, line 530
def reset_ramdisk_id
  client.reset_instance_attribute(
    :instance_id => id, :attribute => "ramdisk").return
end

security_groups() click to toggle source

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

groups the instance belongs to.

# File lib/aws/ec2/instance.rb, line 356
def security_groups
  (group_set || []).collect do |g|
    SecurityGroup.new(g.group_id, :name => g.group_name, :config => config)
  end
end

Also aliased as: groups

spot_instance?() click to toggle source

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

# File lib/aws/ec2/instance.rb, line 405
def spot_instance?
  instance_lifecycle == :spot
end

start() click to toggle source

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

# File lib/aws/ec2/instance.rb, line 551
def start
  instance_action :start
end

stop() click to toggle source

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

# File lib/aws/ec2/instance.rb, line 557
def stop
  instance_action :stop
end

terminate() click to toggle source

Terminates the instance. @return [nil]

# File lib/aws/ec2/instance.rb, line 537
def terminate
  instance_action :terminate
end

Also aliased as: delete

Protected Instance Methods

attributes_from_response_object(obj) click to toggle source

# File lib/aws/ec2/instance.rb, line 584
def attributes_from_response_object(obj)
  if atts = super(obj)
    atts[:status] = obj.instance_state.name.tr("-","_").to_sym if
      obj.respond_to?(:instance_state)
    atts
  end
end

find_in_response(resp) click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 563
def find_in_response resp
  resp.instance_index[id]
end

get_resource(attribute) click to toggle source

# File lib/aws/ec2/instance.rb, line 575
def get_resource attribute
  if self.class.mutable_describe_attributes.include?(attribute.name)
    describe_attribute_call(attribute)
  else
    describe_call
  end
end

instance_action(name) click to toggle source

@private

# File lib/aws/ec2/instance.rb, line 569
def instance_action name 
  client.send("#{name}_instances", :instance_ids => [id])
  nil
end