Class: AWS::EC2::Instance

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

Overview

Represents an EC2 instance.

Instance Attribute Summary collapse

Attributes included from Core::Model

#config

Class Method Summary collapse

Instance Method Summary collapse

Methods included from TaggedItem

#add_tag, #cached_tags, #clear_tags, #tagging_resource_type, #tags

Methods inherited from Core::Resource

attribute_providers, attribute_providers_for, attributes, #attributes_from_response, define_attribute_type, #eql?, #inspect, new_from

Methods included from Core::Cacheable

included, #retrieve_attribute

Methods included from Core::Model

#client, #config_prefix, #inspect

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.



155
156
157
158
 
# File 'lib/aws/ec2/instance.rb', line 155

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.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def api_termination_disabled
  @api_termination_disabled
end

#architecture ⇒ Symbol (readonly)

The architecture of the image.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def architecture
  @architecture
end

#client_token ⇒ String (readonly)

Idempotency token you provided when you launched the instance.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def dns_name
  @dns_name
end

#hypervisor ⇒ Symbol (readonly)

The instance’s hypervisor type. Valid values:

  • :ovm

  • :xen



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def hypervisor
  @hypervisor
end

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



161
162
163
 
# File 'lib/aws/ec2/instance.rb', line 161

def id
  @id
end

#image_id ⇒ String (readonly)

Image ID of the AMI used to launch the instance.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def instance_type
  @instance_type
end

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

The IP address of the instance.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def kernel_id
  @kernel_id
end

#key_name ⇒ String (readonly)

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



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def key_name
  @key_name
end

#launch_time ⇒ Time (readonly)

The time at which the instance was launched.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def launch_time
  @launch_time
end

#monitoring ⇒ Symbol (readonly)

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

  • :enabled

  • :disabled

  • :pending



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def monitoring
  @monitoring
end

#owner_id ⇒ String (readonly)

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



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def owner_id
  @owner_id
end

#platform ⇒ String (readonly)

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



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def platform
  @platform
end

#private_dns_name ⇒ String (readonly)

The DNS name of the instance within the EC2 network.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def private_dns_name
  @private_dns_name
end

#private_ip_address ⇒ String (readonly)

The private IP address assigned to the instance.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def requester_id
  @requester_id
end

#reservation_id ⇒ String (readonly)

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



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def reservation_id
  @reservation_id
end

#root_device_name ⇒ String (readonly)

The name of the root device.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

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



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def root_device_type
  @root_device_type
end

#state_transition_reason ⇒ String (readonly)

A string describing the reason for the last state transition.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def state_transition_reason
  @state_transition_reason
end

#status ⇒ Symbol (readonly)

The instance status. Valid values are:

  • :pending

  • :running

  • :shutting_down

  • :terminated

  • :stopping

  • :stopped



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def status
  @status
end

#status_code ⇒ Integer (readonly)

The numeric instance status code.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def status_code
  @status_code
end

#subnet_id ⇒ String? (readonly)

Instances launched in a VPC have a subnet_id. Normal EC2 instances return nil.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def subnet_id
  @subnet_id
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"



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def user_data
  @user_data
end

#virtualization_type ⇒ Symbol (readonly)

The instance’s virtualization type. Valid values:

  • :paravirtual

  • :hvm



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def virtualization_type
  @virtualization_type
end

#vpc_id ⇒ String? (readonly)

Instances launched in a VPC have a vpc_id. Normal EC2 instances return nil.



147
148
149
 
# File 'lib/aws/ec2/instance.rb', line 147

def vpc_id
  @vpc_id
end

Class Method Details

.describe_call_attribute(name, options = {}, &block) ⇒ Object 



186
187
188
189
 
# 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 ⇒ Object 



176
177
178
 
# File 'lib/aws/ec2/instance.rb', line 176

def self.describe_call_attributes
  @describe_call_attributes ||= {}
end

.mutable_describe_attribute(name, options = {}, &block) ⇒ Object 



198
199
200
201
 
# 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 ⇒ Object 



181
182
183
 
# File 'lib/aws/ec2/instance.rb', line 181

def self.mutable_describe_attributes
  @mutable_describe_attributes ||= {}
end

.mutable_describe_call_attribute(name, options = {}, &block) ⇒ Object 



192
193
194
195
 
# 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

.reservation_attribute(name, options = {}, &block) ⇒ Object 



170
171
172
173
 
# 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 ⇒ Object 



165
166
167
 
# File 'lib/aws/ec2/instance.rb', line 165

def self.reservation_attributes
  @reservation_attributes ||= {}
end

Instance Method Details

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

Associates the elastic IP address with this instance.



544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
 
# File 'lib/aws/ec2/instance.rb', line 544

def associate_elastic_ip elastic_ip

  client_opts = {}
  client_opts[:instance_id] = self.id

  if vpc?
    client_opts[:allocation_id] = elastic_ip.is_a?(ElasticIp) ?
      elastic_ip.allocation_id :
      elastic_ip.to_s
  else
    client_opts[:public_ip] = elastic_ip.to_s
  end

  client.associate_address(client_opts)
  nil

end

#attach_network_interface(network_interface, options = {}) ⇒ nil

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

Options Hash (options):

  • :device_index (Integer) — default: 1 —

    The index of the device for the network interface attachment on the instance. Defaults to 1.



401
402
403
404
405
406
407
408
409
 
# File 'lib/aws/ec2/instance.rb', line 401

def attach_network_interface network_interface, options = {}
  if network_interface.is_a?(NetworkInterface) 
    network_interface.attach(self, options)
  else
    i = NetworkInterface.new(network_interface, :config => config)
    i.attach(self, options)
  end
  nil
end

#availability_zone ⇒ String 



468
469
470
471
472
 
# File 'lib/aws/ec2/instance.rb', line 468

def availability_zone
  if p = placement
    p.availability_zone
  end
end

#block_device_mappings ⇒ Hash<String,Attachment> 



424
425
426
427
428
429
430
431
432
 
# File 'lib/aws/ec2/instance.rb', line 424

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 ⇒ String

Retrieves the console output for the instance.



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

def console_output
  output = client.get_console_output(:instance_id => self.id).output
  Base64.decode64(output) if output
end

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

Creates an AMI from this instance.

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.



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

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

#dedicated_tenancy? ⇒ Boolean 



477
478
479
480
481
482
483
 
# File 'lib/aws/ec2/instance.rb', line 477

def dedicated_tenancy?
  if p = placement
    p.tenancy == 'dedicated'
  else
    false
  end
end

#disable_monitoring ⇒ nil

Disables monitoring for this instance.



443
444
445
446
 
# File 'lib/aws/ec2/instance.rb', line 443

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.



567
568
569
570
571
572
573
 
# File 'lib/aws/ec2/instance.rb', line 567

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? 



577
578
579
580
 
# File 'lib/aws/ec2/instance.rb', line 577

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

#enable_monitoring ⇒ nil

Enables monitoring for this instance.



436
437
438
439
 
# File 'lib/aws/ec2/instance.rb', line 436

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

#exists? ⇒ Boolean 



590
591
592
593
594
 
# File 'lib/aws/ec2/instance.rb', line 590

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

#has_elastic_ip? ⇒ Boolean 



584
585
586
 
# File 'lib/aws/ec2/instance.rb', line 584

def has_elastic_ip?
  !elastic_ip.nil?
end

#image ⇒ Image 



486
487
488
 
# File 'lib/aws/ec2/instance.rb', line 486

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

#key_pair ⇒ KeyPair 



492
493
494
 
# File 'lib/aws/ec2/instance.rb', line 492

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

#monitoring_enabled=(state) ⇒ Object

Enables or disables monitoring for this instance.



451
452
453
 
# File 'lib/aws/ec2/instance.rb', line 451

def monitoring_enabled= state
  state ? enable_monitoring : disable_monitoring
end

#monitoring_enabled? ⇒ Booelan 



457
458
459
 
# File 'lib/aws/ec2/instance.rb', line 457

def monitoring_enabled?
  monitoring == :enabled
end

#network_interfaces ⇒ Array<NetworkInterface> 



383
384
385
386
387
388
 
# File 'lib/aws/ec2/instance.rb', line 383

def network_interfaces
  network_interface_set.collect do |ni|
    NetworkInterface.new_from(:describe_network_interfaces, ni,
      ni.network_interface_id, :config => config)
  end
end

#reboot ⇒ nil

Reboots the instance.



617
618
619
 
# File 'lib/aws/ec2/instance.rb', line 617

def reboot
  instance_action :reboot
end

#reset_kernel_id ⇒ Object

Resets the kernel to its default value.



597
598
599
600
 
# File 'lib/aws/ec2/instance.rb', line 597

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.



603
604
605
606
 
# File 'lib/aws/ec2/instance.rb', line 603

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

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



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

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

#spot_instance? ⇒ Boolean 



462
463
464
 
# File 'lib/aws/ec2/instance.rb', line 462

def spot_instance?
  instance_lifecycle == :spot
end

#start ⇒ nil

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

See Also:



624
625
626
 
# File 'lib/aws/ec2/instance.rb', line 624

def start
  instance_action :start
end

#stop ⇒ nil

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



630
631
632
 
# File 'lib/aws/ec2/instance.rb', line 630

def stop
  instance_action :stop
end

#subnet ⇒ Subnet? 



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

def subnet
  if subnet_id
    Subnet.new(subnet_id, :vpc_id => vpc_id, :config => config)
  end
end

#terminate ⇒ nil Also known as: delete

Terminates the instance.



610
611
612
 
# File 'lib/aws/ec2/instance.rb', line 610

def terminate
  instance_action :terminate
end

#vpc ⇒ VPC? 



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

def vpc
  if vpc_id
    VPC.new(vpc_id, :config => config)
  end
end

#vpc? ⇒ Boolean 



360
361
362
 
# File 'lib/aws/ec2/instance.rb', line 360

def vpc?
  !!vpc_id
end