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
@return [String] Returns the instance id.
@return [String] Returns the instance id.
@api private
# File lib/aws/ec2/instance.rb, line 201 def self.describe_call_attribute name, options = {}, &block attr = attribute(name, options, &block) describe_call_attributes[attr.name] = attr end
@api private
# File lib/aws/ec2/instance.rb, line 191 def self.describe_call_attributes @describe_call_attributes ||= {} end
@api private
# File lib/aws/ec2/instance.rb, line 213 def self.mutable_describe_attribute name, options = {}, &block attr = mutable_attribute(name, options, &block) mutable_describe_attributes[attr.name] = attr end
@api private
# File lib/aws/ec2/instance.rb, line 196 def self.mutable_describe_attributes @mutable_describe_attributes ||= {} end
@api private
# File lib/aws/ec2/instance.rb, line 207 def self.mutable_describe_call_attribute name, options = {}, &block attr = mutable_attribute(name, options, &block) describe_call_attributes[attr.name] = attr end
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}.
# File lib/aws/ec2/instance.rb, line 170 def initialize(instance_id, opts = {}) super @id = instance_id end
@api private
# File lib/aws/ec2/instance.rb, line 185 def self.reservation_attribute name, options = {}, &block attr = attribute(name, options, &block) reservation_attributes[attr.name] = attr end
@api private
# File lib/aws/ec2/instance.rb, line 180 def self.reservation_attributes @reservation_attributes ||= {} end
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]
# File lib/aws/ec2/instance.rb, line 601 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
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 AWS::EC2::NetworkInterface#attach)
@return [nil]
# File lib/aws/ec2/instance.rb, line 430 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
@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}
# File lib/aws/ec2/instance.rb, line 454 def attachments (block_device_mapping || []).inject({}) do |m, mapping| if mapping[:ebs] device = mapping[:device_name] volume = Volume.new(mapping[:ebs][:volume_id], :config => config) attachment = Attachment.new(volume, self, device, :config => config) m[device] = attachment end m end end
@return [String] The availability zone where the instance is
running.
# File lib/aws/ec2/instance.rb, line 526 def availability_zone if p = placement p.availability_zone end end
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.
# File lib/aws/ec2/instance.rb, line 488 def block_devices block_device_mapping.to_a end
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
# File lib/aws/ec2/instance.rb, line 584 def console_output output = client.get_console_output(:instance_id => self.id)[:output] Base64.decode64(output) if output end
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 575 def create_image name, options = {} images = ImageCollection.new(:config => config) images.create(options.merge(:instance_id => id, :name => name)) end
@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 535 def dedicated_tenancy? if p = placement p.tenancy == 'dedicated' else false end end
Disables monitoring for this instance. @return [nil]
# File lib/aws/ec2/instance.rb, line 501 def disable_monitoring client.unmonitor_instances(:instance_ids => [id]) nil end
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 624 def disassociate_elastic_ip if ip = self.elastic_ip ip.disassociate else raise "instance #{id} does not have an associated elastic ip" end end
@return [ElasticIp,nil] Returns an elastic IP address if one
is associated with this instance, nil otherwise.
# File lib/aws/ec2/instance.rb, line 634 def elastic_ip ips = ElasticIpCollection.new(:config => config) ips.filter('instance-id', id).first end
Enables monitoring for this instance. @return [nil]
# File lib/aws/ec2/instance.rb, line 494 def enable_monitoring client.monitor_instances(:instance_ids => [id]) nil end
@return [Boolean] Returns true if the instance exists according to
EC2.
# File lib/aws/ec2/instance.rb, line 647 def exists? client.describe_instances(:filters => [ { :name => "instance-id", :values => [id] } ]).instance_index.key?(id) end
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]
# File lib/aws/ec2/instance.rb, line 748 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
@return [Boolean] Returns true if an elastic IP address is
associated with this instance, false otherwise.
# File lib/aws/ec2/instance.rb, line 641 def has_elastic_ip? !elastic_ip.nil? end
@return [Image] The AMI used to launch the instance.
# File lib/aws/ec2/instance.rb, line 544 def image Image.new(image_id, :config => config) end
@return [KeyPair] The key pair with which this instance was
associated at launch.
# File lib/aws/ec2/instance.rb, line 550 def key_pair KeyPair.new(key_name, :config => config) if key_name end
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 509 def monitoring_enabled= state state ? enable_monitoring : disable_monitoring end
@return [Booelan] Returns `true` if CloudWatch monitoring is
enabled for this instance.
# File lib/aws/ec2/instance.rb, line 515 def monitoring_enabled? monitoring == :enabled end
@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.
# File lib/aws/ec2/instance.rb, line 412 def network_interfaces network_interface_set.collect do |ni| NetworkInterface.new_from(:describe_network_interfaces, ni, ni.network_interface_id, :config => config) end end
Reboots the instance. @return [nil]
# File lib/aws/ec2/instance.rb, line 674 def reboot instance_action :reboot end
Resets the kernel to its default value.
# File lib/aws/ec2/instance.rb, line 654 def reset_kernel_id client.reset_instance_attribute( :instance_id => id, :attribute => "kernel").return end
Resets the RAM disk to its default value.
# File lib/aws/ec2/instance.rb, line 660 def reset_ramdisk_id client.reset_instance_attribute( :instance_id => id, :attribute => "ramdisk").return end
@return [Array<SecurityGroup>] Returns a list of security
groups the instance belongs to.
# File lib/aws/ec2/instance.rb, line 442 def security_groups (group_set || []).collect do |g| SecurityGroup.new(g.group_id, :name => g.group_name, :config => config) end end
@return [Boolean] true if the instance is a Spot instance.
# File lib/aws/ec2/instance.rb, line 520 def spot_instance? instance_lifecycle == :spot end
Starts the instance, assuming it is in a stopped state. @see stop @return [nil]
# File lib/aws/ec2/instance.rb, line 681 def start instance_action :start end
Stops the instance, eventually putting it into a stopped state. @return [nil]
# File lib/aws/ec2/instance.rb, line 687 def stop instance_action :stop end
@return [Subnet,nil] Returns the VPC subnet this instance was
launched in. Returns nil if this was not launched in a VPC.
# File lib/aws/ec2/instance.rb, line 403 def subnet if subnet_id Subnet.new(subnet_id, :vpc_id => vpc_id, :config => config) end end
Terminates the instance. @return [nil]
# File lib/aws/ec2/instance.rb, line 667 def terminate instance_action :terminate end
@return [VPC,nil] Returns the VPC this instance was launched in.
If this instance was not launched inside a VPC, nil is returned.
# File lib/aws/ec2/instance.rb, line 395 def vpc if vpc_id VPC.new(vpc_id, :config => config) end end
# File lib/aws/ec2/instance.rb, line 791 def attributes_from_response_object(obj) if atts = super(obj) if obj[:instance_state] atts[:status] = obj[:instance_state].name.tr("-","_").to_sym end atts end end
# File lib/aws/ec2/instance.rb, line 774 def find_in_response resp resp.instance_index[id] end
# File lib/aws/ec2/instance.rb, line 783 def get_resource attribute if self.class.mutable_describe_attributes.include?(attribute.name) describe_attribute_call(attribute) else describe_call end end
# File lib/aws/ec2/instance.rb, line 778 def instance_action name client.send("#{name}_instances", :instance_ids => [id]) nil end