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.



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

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

Instance Attribute Details

#ami_launch_indexInteger (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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def ami_launch_index
  @ami_launch_index
end

#api_termination_disabledBoolean

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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def api_termination_disabled
  @api_termination_disabled
end

#architectureSymbol (readonly)

The architecture of the image.

Returns:

  • (Symbol)

    the current value of architecture



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def architecture
  @architecture
end

#client_tokenString (readonly)

Idempotency token you provided when you launched the instance.

Returns:

  • (String)

    the current value of client_token



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def client_token
  @client_token
end

#dns_nameString (readonly) Also known as: public_dns_name

The DNS name of the instance on the internet.

Returns:

  • (String)

    the current value of dns_name



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def dns_name
  @dns_name
end

#hypervisorSymbol (readonly)

The instance’s hypervisor type. Valid values:

  • :ovm

  • :xen

Returns:

  • (Symbol)

    the current value of hypervisor



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def hypervisor
  @hypervisor
end

#iam_instance_profile_arnString? (readonly)

Returns the current value of iam_instance_profile_arn.

Returns:

  • (String, nil)

    the current value of iam_instance_profile_arn



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def iam_instance_profile_arn
  @iam_instance_profile_arn
end

#iam_instance_profile_idString? (readonly)

Returns the current value of iam_instance_profile_id.

Returns:

  • (String, nil)

    the current value of iam_instance_profile_id



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def iam_instance_profile_id
  @iam_instance_profile_id
end

#idString (readonly) Also known as: instance_id

Returns the instance id.

Returns:

  • (String)

    Returns the instance id.



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

def id
  @id
end

#image_idString (readonly)

Image ID of the AMI used to launch the instance.

Returns:

  • (String)

    the current value of image_id



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def image_id
  @image_id
end

#instance_initiated_shutdown_behaviorString

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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def instance_initiated_shutdown_behavior
  @instance_initiated_shutdown_behavior
end

#instance_typeString

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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def instance_type
  @instance_type
end

#ip_addressString (readonly) Also known as: public_ip_address

The IP address of the instance.

Returns:

  • (String)

    the current value of ip_address



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def ip_address
  @ip_address
end

#kernel_idString

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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def kernel_id
  @kernel_id
end

#key_nameString (readonly)

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

Returns:

  • (String)

    the current value of key_name



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def key_name
  @key_name
end

#launch_timeTime (readonly)

The time at which the instance was launched.

Returns:

  • (Time)

    the current value of launch_time



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def launch_time
  @launch_time
end

#monitoringSymbol (readonly)

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

  • :enabled

  • :disabled

  • :pending

Returns:

  • (Symbol)

    the current value of monitoring



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def monitoring
  @monitoring
end

#owner_idString (readonly)

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

Returns:

  • (String)

    the current value of owner_id



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def owner_id
  @owner_id
end

#platformString (readonly)

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

Returns:

  • (String)

    the current value of platform



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def platform
  @platform
end

#private_dns_nameString (readonly)

The DNS name of the instance within the EC2 network.

Returns:

  • (String)

    the current value of private_dns_name



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def private_dns_name
  @private_dns_name
end

#private_ip_addressString (readonly)

The private IP address assigned to the instance.

Returns:

  • (String)

    the current value of private_ip_address



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def private_ip_address
  @private_ip_address
end

#ramdisk_idString

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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def ramdisk_id
  @ramdisk_id
end

#requester_idString (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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def requester_id
  @requester_id
end

#reservation_idString (readonly)

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

Returns:

  • (String)

    the current value of reservation_id



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def reservation_id
  @reservation_id
end

#root_device_nameString (readonly)

The name of the root device.

Returns:

  • (String)

    the current value of root_device_name



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def root_device_name
  @root_device_name
end

#root_device_typeSymbol (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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def root_device_type
  @root_device_type
end

#state_transition_reasonString (readonly)

A string describing the reason for the last state transition.

Returns:

  • (String)

    the current value of state_transition_reason



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def state_transition_reason
  @state_transition_reason
end

#statusSymbol (readonly)

The instance status. Valid values are:

  • :pending

  • :running

  • :shutting_down

  • :terminated

  • :stopping

  • :stopped

Returns:

  • (Symbol)

    the current value of status



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def status
  @status
end

#status_codeInteger (readonly)

The numeric instance status code.

Returns:

  • (Integer)

    the current value of status_code



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def status_code
  @status_code
end

#subnet_idString? (readonly)

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

Returns:

  • (String, nil)

    the current value of subnet_id



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def subnet_id
  @subnet_id
end

#user_dataString

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



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def user_data
  @user_data
end

#virtualization_typeSymbol (readonly)

The instance’s virtualization type. Valid values:

  • :paravirtual

  • :hvm

Returns:

  • (Symbol)

    the current value of virtualization_type



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

def virtualization_type
  @virtualization_type
end

#vpc_idString? (readonly)

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

Returns:

  • (String, nil)

    the current value of vpc_id



151
152
153
# File 'lib/aws/ec2/instance.rb', line 151

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

Overloads:

  • #associate_elastic_ip(elastic_ip) ⇒ nil

    Parameters:

    • elastic_ip (ElasticIp, String)

      An Elastic ip address (VPC or non-VPC) or a public ip address string (non-VPC only).

  • #associate_elastic_ip(allocation_id) ⇒ nil

    Parameters:

    • allocation_id (String)

      The allocation id of a VPC elastic ip address.

Returns:

  • (nil)


560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
# File 'lib/aws/ec2/instance.rb', line 560

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

Parameters:

  • network_interface (NetworkInterface, String)

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

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

Options Hash (options):

  • :device_index (Integer) — default: 1

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

Returns:

  • (nil)


417
418
419
420
421
422
423
424
425
# File 'lib/aws/ec2/instance.rb', line 417

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_zoneString

Returns The availability zone where the instance is running.

Returns:

  • (String)

    The availability zone where the instance is running.



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

def availability_zone
  if p = placement
    p.availability_zone
  end
end

#block_device_mappingsHash<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.



440
441
442
443
444
445
446
447
448
# File 'lib/aws/ec2/instance.rb', line 440

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_outputString

Retrieves the console output for the instance.

Returns:

  • (String)

    the console output.



543
544
545
546
# File 'lib/aws/ec2/instance.rb', line 543

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.

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.



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

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

#dedicated_tenancy?Boolean

Returns true if the instance has dedicated tenancy. This will be false for all non-VPC instances. Dedicated Tenancy comes at extra cost.

Returns:

  • (Boolean)

    Returns true if the instance has dedicated tenancy. This will be false for all non-VPC instances. Dedicated Tenancy comes at extra cost.



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

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

#disable_monitoringnil

Disables monitoring for this instance.

Returns:

  • (nil)


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

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

#disassociate_elastic_ipObject

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



583
584
585
586
587
588
589
# File 'lib/aws/ec2/instance.rb', line 583

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_ipElasticIp?

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.



593
594
595
596
# File 'lib/aws/ec2/instance.rb', line 593

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

#enable_monitoringnil

Enables monitoring for this instance.

Returns:

  • (nil)


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

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.



606
607
608
609
610
# File 'lib/aws/ec2/instance.rb', line 606

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

#export_to_s3(bucket, options = {}) ⇒ ExportTask

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 => '[email protected]')
  acl.grant(:write).to(:amazon_customer_email => '[email protected]')
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', 'w') {|f| f.write(task.s3_object.read) }

Parameters:

  • bucket (S3::Bucket, String)

    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 ‘[email protected].’.

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

Options Hash (options):

  • :target_environment (String) — default: 'vmware'

    The target virtualization environment. Valid values include: ‘vmware’, ‘citrix’ and ‘microsoft’.

  • :disk_image_format (String)

    The format for the exported image. Defaults to ‘vmdk’ if :target_environemnt is ‘vmware’, otherwise, ‘vhd’.

  • :container_format (String)

    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.

  • :description (String)

    Description of the conversion task or the resource being exported.

  • :prefix (String) — default: nil

    The image is written to a single object in the bucket at the key:

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

Returns:



707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
# File 'lib/aws/ec2/instance.rb', line 707

def export_to_s3 bucket, options = {}

  bucket_name = bucket.is_a?(S3::Bucket) ? bucket.name : bucket.to_s

  opts = {}
  opts[:instance_id] = instance_id
  opts[:description] = options[:description] if options[:description]
  opts[:target_environment] = options[:target_environment] || 'vmware'
  opts[:export_to_s3] = {}
  opts[:export_to_s3][:s3_bucket] = bucket_name
  [:disk_image_format, :container_format, :s3_prefix].each do |opt|
    opts[:export_to_s3][opt] = options[opt] if options.key?(opt)
  end

  resp = client.create_instance_export_task(opts)

  ExportTask.new_from(
    :create_instance_export_task,
    resp[:export_task],
    resp[:export_task][:export_task_id],
    :config => config)

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.



600
601
602
# File 'lib/aws/ec2/instance.rb', line 600

def has_elastic_ip?
  !elastic_ip.nil?
end

#imageImage

Returns The AMI used to launch the instance.

Returns:

  • (Image)

    The AMI used to launch the instance.



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

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

#key_pairKeyPair

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.



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

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

#monitoring_enabled=(state) ⇒ 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.



467
468
469
# File 'lib/aws/ec2/instance.rb', line 467

def monitoring_enabled= state
  state ? 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.



473
474
475
# File 'lib/aws/ec2/instance.rb', line 473

def monitoring_enabled?
  monitoring == :enabled
end

#network_interfacesArray<NetworkInterface>

Returns a list of elastic network interfaces attached to this instance (VPC only). Non-vpc instance may not have attached network interfaces.

Returns:

  • (Array<NetworkInterface>)

    Returns a list of elastic network interfaces attached to this instance (VPC only). Non-vpc instance may not have attached network interfaces.



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

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

#rebootnil

Reboots the instance.

Returns:

  • (nil)


633
634
635
# File 'lib/aws/ec2/instance.rb', line 633

def reboot
  instance_action :reboot
end

#reset_kernel_idObject

Resets the kernel to its default value.



613
614
615
616
# File 'lib/aws/ec2/instance.rb', line 613

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

#reset_ramdisk_idObject

Resets the RAM disk to its default value.



619
620
621
622
# File 'lib/aws/ec2/instance.rb', line 619

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

#security_groupsArray<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.



429
430
431
432
433
# File 'lib/aws/ec2/instance.rb', line 429

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.



478
479
480
# File 'lib/aws/ec2/instance.rb', line 478

def spot_instance?
  instance_lifecycle == :spot
end

#startnil

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

Returns:

  • (nil)

See Also:



640
641
642
# File 'lib/aws/ec2/instance.rb', line 640

def start
  instance_action :start
end

#stopnil

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

Returns:

  • (nil)


646
647
648
# File 'lib/aws/ec2/instance.rb', line 646

def stop
  instance_action :stop
end

#subnetSubnet?

Returns the VPC subnet this instance was launched in. Returns nil if this was not launched in a VPC.

Returns:

  • (Subnet, nil)

    Returns the VPC subnet this instance was launched in. Returns nil if this was not launched in a VPC.



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

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

#terminatenil Also known as: delete

Terminates the instance.

Returns:

  • (nil)


626
627
628
# File 'lib/aws/ec2/instance.rb', line 626

def terminate
  instance_action :terminate
end

#vpcVPC?

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

Returns:

  • (VPC, nil)

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



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

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

#vpc?Boolean

Returns true if this is an EC2 VPC instance.

Returns:

  • (Boolean)

    Returns true if this is an EC2 VPC instance.



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

def vpc?
  !!vpc_id
end