Class: AWS::EC2::Instance

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

Overview

Represents an EC2 instance.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from TaggedItem

#add_tag, #clear_tags, #tags

Constructor Details

#initialize(instance_id, opts = {}) ⇒ Instance

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



157
158
159
160
 
# File 'lib/aws/ec2/instance.rb', line 157

def initialize(instance_id, opts = {})
  super
  @id = instance_id
end

Instance Attribute Details

#ami_launch_index ⇒ Integer (readonly)

The AMI launch index, which can be used to find this instance within the launch group.

Returns:

  • (Integer) —

    the current value of ami_launch_index



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def ami_launch_index
  @ami_launch_index
end

#api_termination_disabled ⇒ Boolean

True if the instance cannot be terminated using the #terminate method. This attribute can be changed at any time.

Returns:

  • (Boolean) —

    the current value of api_termination_disabled



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def api_termination_disabled
  @api_termination_disabled
end

#architecture ⇒ Symbol (readonly)

The architecture of the image.

Returns:

  • (Symbol) —

    the current value of architecture



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def architecture
  @architecture
end

#client_token ⇒ String (readonly)

Idempotency token you provided when you launched the instance.

Returns:

  • (String) —

    the current value of client_token



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def client_token
  @client_token
end

#dns_name ⇒ String (readonly) Also known as: public_dns_name

The DNS name of the instance on the internet.

Returns:

  • (String) —

    the current value of dns_name



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def dns_name
  @dns_name
end

#hypervisor ⇒ Symbol (readonly)

The instance’s hypervisor type. Valid values:

  • :ovm

  • :xen

Returns:

  • (Symbol) —

    the current value of hypervisor



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def hypervisor
  @hypervisor
end

#id ⇒ String (readonly)

Returns the instance id.

Returns:

  • (String) —

    Returns the instance id.



163
164
165
 
# File 'lib/aws/ec2/instance.rb', line 163

def id
  @id
end

#image_id ⇒ String (readonly)

Image ID of the AMI used to launch the instance.

Returns:

  • (String) —

    the current value of image_id



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def image_id
  @image_id
end

#instance_initiated_shutdown_behavior ⇒ String

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.

Returns:

  • (String) —

    the current value of instance_initiated_shutdown_behavior



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def instance_initiated_shutdown_behavior
  @instance_initiated_shutdown_behavior
end

#instance_type ⇒ String

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

Returns:

  • (String) —

    the current value of instance_type



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def instance_type
  @instance_type
end

#ip_address ⇒ String (readonly) Also known as: public_ip_address

The IP address of the instance.

Returns:

  • (String) —

    the current value of ip_address



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def ip_address
  @ip_address
end

#kernel_id ⇒ String

The ID of the kernel that the image currently uses. The instance must be in a stopped state to change this attribute.

Returns:

  • (String) —

    the current value of kernel_id



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def kernel_id
  @kernel_id
end

#key_name ⇒ String (readonly)

The name of the key pair with which this instance was associated at launch.

Returns:

  • (String) —

    the current value of key_name



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def key_name
  @key_name
end

#launch_time ⇒ Time (readonly)

The time at which the instance was launched.

Returns:

  • (Time) —

    the current value of launch_time



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def launch_time
  @launch_time
end

#monitoring ⇒ Symbol (readonly)

The status of CloudWatch monitoring for the instance. Valid values:

  • :enabled

  • :disabled

  • :pending

Returns:

  • (Symbol) —

    the current value of monitoring



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def monitoring
  @monitoring
end

#owner_id ⇒ String (readonly)

ID of the AWS account that owns the reservation in which the instance was launched.

Returns:

  • (String) —

    the current value of owner_id



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def owner_id
  @owner_id
end

#platform ⇒ String (readonly)

A string describing the platform of the image (e.g. “windows”).

Returns:

  • (String) —

    the current value of platform



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def platform
  @platform
end

#private_dns_name ⇒ String (readonly)

The DNS name of the instance within the EC2 network.

Returns:

  • (String) —

    the current value of private_dns_name



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def private_dns_name
  @private_dns_name
end

#private_ip_address ⇒ String (readonly)

The private IP address assigned to the instance.

Returns:

  • (String) —

    the current value of private_ip_address



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def private_ip_address
  @private_ip_address
end

#ramdisk_id ⇒ String

The ID of the RAM disk that the image currently uses. The instance must be in a stopped state to change this attribute.

Returns:

  • (String) —

    the current value of ramdisk_id



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def ramdisk_id
  @ramdisk_id
end

#requester_id ⇒ String (readonly)

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

Returns:

  • (String) —

    the current value of requester_id



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def requester_id
  @requester_id
end

#reservation_id ⇒ String (readonly)

The ID of the reservation in which this instance was launched.

Returns:

  • (String) —

    the current value of reservation_id



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def reservation_id
  @reservation_id
end

#root_device_name ⇒ String (readonly)

The name of the root device.

Returns:

  • (String) —

    the current value of root_device_name



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def root_device_name
  @root_device_name
end

#root_device_type ⇒ Symbol (readonly)

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

Returns:

  • (Symbol) —

    the current value of root_device_type



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def root_device_type
  @root_device_type
end

#state_transition_reason ⇒ String (readonly)

A string describing the reason for the last state transition.

Returns:

  • (String) —

    the current value of state_transition_reason



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def state_transition_reason
  @state_transition_reason
end

#status ⇒ Symbol (readonly)

The instance status. Valid values are:

  • :pending

  • :running

  • :shutting_down

  • :terminated

  • :stopping

  • :stopped

Returns:

  • (Symbol) —

    the current value of status



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def status
  @status
end

#status_code ⇒ Integer (readonly)

The numeric instance status code.

Returns:

  • (Integer) —

    the current value of status_code



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def status_code
  @status_code
end

#user_data ⇒ String

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"

Returns:

  • (String) —

    the current value of user_data



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def user_data
  @user_data
end

#virtualization_type ⇒ Symbol (readonly)

The instance’s virtualization type. Valid values:

  • :paravirtual

  • :hvm

Returns:

  • (Symbol) —

    the current value of virtualization_type



149
150
151
 
# File 'lib/aws/ec2/instance.rb', line 149

def virtualization_type
  @virtualization_type
end

Instance Method Details

#associate_elastic_ip(elastic_ip) ⇒ nil Also known as: ip_address=

Associates the elastic IP address with this instance.

Parameters:

  • elastic_ip (ElasticIp, String) —

    Either a public IP address string or an ElasticIp object to associate to this instance.

Returns:

  • (nil) 


458
459
460
461
462
463
464
 
# File 'lib/aws/ec2/instance.rb', line 458

def associate_elastic_ip elastic_ip
  client.associate_address(
    :public_ip => elastic_ip.to_s,
    :instance_id => self.id
  )
  nil
end

#availability_zone ⇒ String

Returns The availability zone where the instance is running.

Returns:

  • (String) —

    The availability zone where the instance is running.



407
408
409
410
411
 
# File 'lib/aws/ec2/instance.rb', line 407

def availability_zone
  if p = placement
    p.availability_zone
  end
end

#block_device_mappings ⇒ 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.

Returns:

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



363
364
365
366
367
368
369
370
371
 
# File 'lib/aws/ec2/instance.rb', line 363

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

#create_image(name, options = {}) ⇒ Image

Creates an AMI from this instance.

Parameters:

  • name (String) —

    A name for the new image you’re creating. Constraints: 3-128 alphanumeric characters, parenthesis (()), commas (,), slashes (/), dashes (-), or underscores(_)

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

    Additional options for creating the image.

Options Hash (options):

  • :description (String) —

    A description of the new image.

  • :no_reboot (Boolean) —

    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.

Returns:

  • (Image) —

    The newly created image.



447
448
449
450
 
# File 'lib/aws/ec2/instance.rb', line 447

def create_image name, options = {}
  images = ImageCollection.new(:config => config)
  images.create(options.merge(:instance_id => id, :name => name))
end

#disable_monitoring ⇒ nil

Disables monitoring for this instance.

Returns:

  • (nil) 


382
383
384
385
 
# File 'lib/aws/ec2/instance.rb', line 382

def disable_monitoring
  client.unmonitor_instances(:instance_ids => [id])
  nil
end

#disassociate_elastic_ip ⇒ Object

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



471
472
473
474
475
476
477
 
# File 'lib/aws/ec2/instance.rb', line 471

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 ⇒ ElasticIp?

Returns an elastic IP address if one is associated with this instance, nil otherwise.

Returns:

  • (ElasticIp, nil) —

    Returns an elastic IP address if one is associated with this instance, nil otherwise.



481
482
483
484
 
# File 'lib/aws/ec2/instance.rb', line 481

def elastic_ip
  ips = ElasticIpCollection.new(:config => config)
  ips.filter('instance-id', id).first
end

#enable_monitoring ⇒ nil

Enables monitoring for this instance.

Returns:

  • (nil) 


375
376
377
378
 
# File 'lib/aws/ec2/instance.rb', line 375

def enable_monitoring
  client.monitor_instances(:instance_ids => [id])
  nil
end

#exists? ⇒ Boolean

Returns true if the instance exists according to EC2.

Returns:

  • (Boolean) —

    Returns true if the instance exists according to EC2.



494
495
496
497
498
 
# File 'lib/aws/ec2/instance.rb', line 494

def exists?
  client.describe_instances(:filters => [
    { :name => "instance-id", :values => [id] }
  ]).instance_index.key?(id)
end

#has_elastic_ip? ⇒ Boolean

Returns true if an elastic IP address is associated with this instance, false otherwise.

Returns:

  • (Boolean) —

    Returns true if an elastic IP address is associated with this instance, false otherwise.



488
489
490
 
# File 'lib/aws/ec2/instance.rb', line 488

def has_elastic_ip?
  !elastic_ip.nil?
end

#image ⇒ Image

Returns The AMI used to launch the instance.

Returns:

  • (Image) —

    The AMI used to launch the instance.



414
415
416
 
# File 'lib/aws/ec2/instance.rb', line 414

def image
  Image.new(image_id, :config => config)
end

#key_pair ⇒ KeyPair

Returns The key pair with which this instance was associated at launch.

Returns:

  • (KeyPair) —

    The key pair with which this instance was associated at launch.



420
421
422
 
# File 'lib/aws/ec2/instance.rb', line 420

def key_pair
  KeyPair.new(key_name, :config => config) if key_name
end

#monitoring_enabled=(value) ⇒ Object

Enables or disables monitoring for this instance.

Parameters:

  • state (Boolean) —

    A true or false value. Enables monintoring for a true value, disables it for a false value.



390
391
392
 
# File 'lib/aws/ec2/instance.rb', line 390

def monitoring_enabled= value
  value ? enable_monitoring : disable_monitoring
end

#monitoring_enabled? ⇒ Booelan

Returns true if CloudWatch monitoring is enabled for this instance.

Returns:

  • (Booelan) —

    Returns true if CloudWatch monitoring is enabled for this instance.



396
397
398
 
# File 'lib/aws/ec2/instance.rb', line 396

def monitoring_enabled?
  monitoring == :enabled
end

#reboot ⇒ nil

Reboots the instance.

Returns:

  • (nil) 


521
522
523
 
# File 'lib/aws/ec2/instance.rb', line 521

def reboot
  instance_action :reboot
end

#reset_kernel_id ⇒ Object

Resets the kernel to its default value.



501
502
503
504
 
# File 'lib/aws/ec2/instance.rb', line 501

def reset_kernel_id
  client.reset_instance_attribute(
    :instance_id => id, :attribute => "kernel").return
end

#reset_ramdisk_id ⇒ Object

Resets the RAM disk to its default value.



507
508
509
510
 
# File 'lib/aws/ec2/instance.rb', line 507

def reset_ramdisk_id
  client.reset_instance_attribute(
    :instance_id => id, :attribute => "ramdisk").return
end

#security_groups ⇒ Array<SecurityGroup> Also known as: groups

Returns a list of security groups the instance belongs to.

Returns:

  • (Array<SecurityGroup>) —

    Returns a list of security groups the instance belongs to.



352
353
354
355
356
 
# File 'lib/aws/ec2/instance.rb', line 352

def security_groups
  (group_set || []).collect do |g|
    SecurityGroup.new(g.group_id, :name => g.group_name, :config => config)
  end
end

#spot_instance? ⇒ Boolean

Returns true if the instance is a Spot instance.

Returns:

  • (Boolean) —

    true if the instance is a Spot instance.



401
402
403
 
# File 'lib/aws/ec2/instance.rb', line 401

def spot_instance?
  instance_lifecycle == :spot
end

#start ⇒ nil

Starts the instance, assuming it is in a stopped state.

Returns:

  • (nil)

See Also:



528
529
530
 
# File 'lib/aws/ec2/instance.rb', line 528

def start
  instance_action :start
end

#stop ⇒ nil

Stops the instance, eventually putting it into a stopped state.

Returns:

  • (nil) 


534
535
536
 
# File 'lib/aws/ec2/instance.rb', line 534

def stop
  instance_action :stop
end

#terminate ⇒ nil Also known as: delete

Terminates the instance.

Returns:

  • (nil) 


514
515
516
 
# File 'lib/aws/ec2/instance.rb', line 514

def terminate
  instance_action :terminate
end