You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 1 documentation can be found here.

Class: Aws::EC2::Instance

Inherits:
Resources::Resource show all
Defined in:
aws-sdk-resources/lib/aws-sdk-resources/services/ec2/instance.rb

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #load, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

#initialize(id, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object

Overloads:

  • #initialize(id, options = {}) ⇒ Object

    Parameters:

    • id (String)

    Options Hash (options):

    • :client (Client)

      When `:client is not given, the options hash is used to construct a new Client object.

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

    • :id (required, String)
    • :client (Client)

      When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#ami_launch_indexInteger (readonly)

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

Returns:

  • (Integer)

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

#architectureString (readonly)

The architecture of the image.

Possible values:

  • i386
  • x86_64

Returns:

  • (String)

    The architecture of the image.

#block_device_mappingsArray<Types::InstanceBlockDeviceMapping> (readonly)

Any block device mapping entries for the instance.

Returns:

#client_tokenString (readonly)

The idempotency token you provided when you launched the instance, if applicable.

Returns:

  • (String)

    The idempotency token you provided when you launched the instance, if applicable.

#ebs_optimizedBoolean (readonly)

Indicates whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal I/O performance. This optimization isn\'t available with all instance types. Additional usage charges apply when using an EBS Optimized instance.

Returns:

  • (Boolean)

    Indicates whether the instance is optimized for EBS I/O.

#ena_supportBoolean (readonly)

Specifies whether enhanced networking with ENA is enabled.

Returns:

  • (Boolean)

    Specifies whether enhanced networking with ENA is enabled.

#hypervisorString (readonly)

The hypervisor type of the instance.

Possible values:

  • ovm
  • xen

Returns:

  • (String)

    The hypervisor type of the instance.

#iam_instance_profileTypes::IamInstanceProfile (readonly)

The IAM instance profile associated with the instance, if applicable.

Returns:

#idString (readonly)

Returns:

  • (String)

#image_idString (readonly)

The ID of the AMI used to launch the instance.

Returns:

  • (String)

    The ID of the AMI used to launch the instance.

#instance_idString (readonly)

The ID of the instance.

Returns:

  • (String)

    The ID of the instance.

#instance_lifecycleString (readonly)

Indicates whether this is a Spot instance or a Scheduled Instance.

Possible values:

  • spot
  • scheduled

Returns:

  • (String)

    Indicates whether this is a Spot instance or a Scheduled Instance.

#instance_typeString (readonly)

The instance type.

Possible values:

  • t1.micro
  • t2.nano
  • t2.micro
  • t2.small
  • t2.medium
  • t2.large
  • t2.xlarge
  • t2.2xlarge
  • m1.small
  • m1.medium
  • m1.large
  • m1.xlarge
  • m3.medium
  • m3.large
  • m3.xlarge
  • m3.2xlarge
  • m4.large
  • m4.xlarge
  • m4.2xlarge
  • m4.4xlarge
  • m4.10xlarge
  • m4.16xlarge
  • m2.xlarge
  • m2.2xlarge
  • m2.4xlarge
  • cr1.8xlarge
  • r3.large
  • r3.xlarge
  • r3.2xlarge
  • r3.4xlarge
  • r3.8xlarge
  • r4.large
  • r4.xlarge
  • r4.2xlarge
  • r4.4xlarge
  • r4.8xlarge
  • r4.16xlarge
  • x1.16xlarge
  • x1.32xlarge
  • i2.xlarge
  • i2.2xlarge
  • i2.4xlarge
  • i2.8xlarge
  • i3.large
  • i3.xlarge
  • i3.2xlarge
  • i3.4xlarge
  • i3.8xlarge
  • i3.16xlarge
  • hi1.4xlarge
  • hs1.8xlarge
  • c1.medium
  • c1.xlarge
  • c3.large
  • c3.xlarge
  • c3.2xlarge
  • c3.4xlarge
  • c3.8xlarge
  • c4.large
  • c4.xlarge
  • c4.2xlarge
  • c4.4xlarge
  • c4.8xlarge
  • cc1.4xlarge
  • cc2.8xlarge
  • g2.2xlarge
  • g2.8xlarge
  • cg1.4xlarge
  • p2.xlarge
  • p2.8xlarge
  • p2.16xlarge
  • d2.xlarge
  • d2.2xlarge
  • d2.4xlarge
  • d2.8xlarge
  • f1.2xlarge
  • f1.16xlarge

Returns:

  • (String)

    The instance type.

#kernel_idString (readonly)

The kernel associated with this instance, if applicable.

Returns:

  • (String)

    The kernel associated with this instance, if applicable.

#key_nameString (readonly)

The name of the key pair, if this instance was launched with an associated key pair.

Returns:

  • (String)

    The name of the key pair, if this instance was launched with an associated key pair.

#launch_timeTime (readonly)

The time the instance was launched.

Returns:

  • (Time)

    The time the instance was launched.

#monitoringTypes::Monitoring (readonly)

The monitoring for the instance.

Returns:

#placementTypes::Placement (readonly)

The location where the instance launched, if applicable.

Returns:

  • (Types::Placement)

    The location where the instance launched, if applicable.

#platformString (readonly)

The value is Windows for Windows instances; otherwise blank.

Possible values:

  • Windows

Returns:

  • (String)

    The value is Windows for Windows instances; otherwise blank.

#private_dns_nameString (readonly)

(IPv4 only) The private DNS hostname name assigned to the instance. This DNS hostname can only be used inside the Amazon EC2 network. This name is not available until the instance enters the running state.

[EC2-VPC] The Amazon-provided DNS server will resolve Amazon-provided private DNS hostnames if you\'ve enabled DNS resolution and DNS hostnames in your VPC. If you are not using the Amazon-provided DNS server in your VPC, your custom domain name servers must resolve the hostname as appropriate.

Returns:

  • (String)

    (IPv4 only) The private DNS hostname name assigned to the instance.

#private_ip_addressString (readonly)

The private IPv4 address assigned to the instance.

Returns:

  • (String)

    The private IPv4 address assigned to the instance.

#product_codesArray<Types::ProductCode> (readonly)

The product codes attached to this instance, if applicable.

Returns:

  • (Array<Types::ProductCode>)

    The product codes attached to this instance, if applicable.

#public_dns_nameString (readonly)

(IPv4 only) The public DNS name assigned to the instance. This name is not available until the instance enters the running state. For EC2-VPC, this name is only available if you\'ve enabled DNS hostnames for your VPC.

Returns:

  • (String)

    (IPv4 only) The public DNS name assigned to the instance.

#public_ip_addressString (readonly)

The public IPv4 address assigned to the instance, if applicable.

Returns:

  • (String)

    The public IPv4 address assigned to the instance, if applicable.

#ramdisk_idString (readonly)

The RAM disk associated with this instance, if applicable.

Returns:

  • (String)

    The RAM disk associated with this instance, if applicable.

#root_device_nameString (readonly)

The root device name (for example, /dev/sda1 or /dev/xvda).

Returns:

  • (String)

    The root device name (for example, /dev/sda1 or /dev/xvda).

#root_device_typeString (readonly)

The root device type used by the AMI. The AMI can use an EBS volume or an instance store volume.

Possible values:

  • ebs
  • instance-store

Returns:

  • (String)

    The root device type used by the AMI.

#security_groupsArray<Types::GroupIdentifier> (readonly)

One or more security groups for the instance.

Returns:

#source_dest_checkBoolean (readonly)

Specifies whether to enable an instance launched in a VPC to perform NAT. This controls whether source/destination checking is enabled on the instance. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the instance to perform NAT. For more information, see NAT Instances in the Amazon Virtual Private Cloud User Guide.

Returns:

  • (Boolean)

    Specifies whether to enable an instance launched in a VPC to perform NAT.

#spot_instance_request_idString (readonly)

If the request is a Spot instance request, the ID of the request.

Returns:

  • (String)

    If the request is a Spot instance request, the ID of the request.

#sriov_net_supportString (readonly)

Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.

Returns:

  • (String)

    Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled.

#stateTypes::InstanceState (readonly)

The current state of the instance.

Returns:

#state_reasonTypes::StateReason (readonly)

The reason for the most recent state transition.

Returns:

#state_transition_reasonString (readonly)

The reason for the most recent state transition. This might be an empty string.

Returns:

  • (String)

    The reason for the most recent state transition.

#subnet_idString (readonly)

[EC2-VPC] The ID of the subnet in which the instance is running.

Returns:

  • (String)

    [EC2-VPC] The ID of the subnet in which the instance is running.

#tagsArray<Types::Tag> (readonly)

Any tags assigned to the instance.

Returns:

  • (Array<Types::Tag>)

    Any tags assigned to the instance.

#virtualization_typeString (readonly)

The virtualization type of the instance.

Possible values:

  • hvm
  • paravirtual

Returns:

  • (String)

    The virtualization type of the instance.

#vpc_idString (readonly)

[EC2-VPC] The ID of the VPC in which the instance is running.

Returns:

  • (String)

    [EC2-VPC] The ID of the VPC in which the instance is running.

Instance Method Details

Links an EC2-Classic instance to a ClassicLink-enabled VPC through one or more of the VPC's security groups. You cannot link an EC2-Classic instance to more than one VPC at a time. You can only link an instance that's in the running state. An instance is automatically unlinked from a VPC when it's stopped - you can link it to the VPC again when you restart it.

After you've linked an instance, you cannot change the VPC security groups that are associated with it. To change the security groups, you must first unlink the instance, and then link it again.

Linking your instance to a VPC is sometimes referred to as attaching your instance.

Examples:

Request syntax example with placeholder values


instance.attach_classic_link_vpc({
  dry_run: false,
  vpc_id: "String", # required
  groups: ["String"], # required
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :vpc_id (required, String)

    The ID of a ClassicLink-enabled VPC.

  • :groups (required, Array<String>)

    The ID of one or more of the VPC\'s security groups. You cannot specify security groups from a different VPC.

Returns:

See Also:

#attach_volume(options = {}) ⇒ Types::VolumeAttachment

Attaches an EBS volume to a running or stopped instance and exposes it to the instance with the specified device name.

Encrypted EBS volumes may only be attached to instances that support Amazon EBS encryption. For more information, see Amazon EBS Encryption in the Amazon Elastic Compute Cloud User Guide.

For a list of supported device names, see Attaching an EBS Volume to an Instance. Any device names that aren't reserved for instance store volumes can be used for EBS volumes. For more information, see Amazon EC2 Instance Store in the Amazon Elastic Compute Cloud User Guide.

If a volume has an AWS Marketplace product code:

  • The volume can be attached only to a stopped instance.

  • AWS Marketplace product codes are copied from the volume to the instance.

  • You must be subscribed to the product.

  • The instance type and operating system of the instance must support the product. For example, you can't detach a volume from a Windows instance and attach it to a Linux instance.

For an overview of the AWS Marketplace, see Introducing AWS Marketplace.

For more information about EBS volumes, see Attaching Amazon EBS Volumes in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.attach_volume({
  dry_run: false,
  volume_id: "String", # required
  device: "String", # required
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :volume_id (required, String)

    The ID of the EBS volume. The volume and instance must be within the same Availability Zone.

  • :device (required, String)

    The device name to expose to the instance (for example, /dev/sdh or xvdh).

Returns:

See Also:

#classic_addressClassicAddress?

Returns:

#console_output(options = {}) ⇒ Types::GetConsoleOutputResult

Gets the console output for the specified instance.

Instances do not have a physical monitor through which you can view their console output. They also lack physical controls that allow you to power up, reboot, or shut them down. To allow these actions, we provide them through the Amazon EC2 API and command line interface.

Instance console output is buffered and posted shortly after instance boot, reboot, and termination. Amazon EC2 preserves the most recent 64 KB output which is available for at least one hour after the most recent post.

For Linux instances, the instance console output displays the exact console output that would normally be displayed on a physical monitor attached to a computer. This output is buffered because the instance produces it and then posts it to a store where the instance's owner can retrieve it.

For Windows instances, the instance console output includes output from the EC2Config service.

Examples:

Request syntax example with placeholder values


instance.console_output({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

See Also:

#create_image(options = {}) ⇒ Image

Examples:

Request syntax example with placeholder values


instance.create_image({
  dry_run: false,
  name: "String", # required
  description: "String",
  no_reboot: false,
  block_device_mappings: [
    {
      virtual_name: "String",
      device_name: "String",
      ebs: {
        snapshot_id: "String",
        volume_size: 1,
        delete_on_termination: false,
        volume_type: "standard", # accepts standard, io1, gp2, sc1, st1
        iops: 1,
        encrypted: false,
      },
      no_device: "String",
    },
  ],
})

Basic usage

image = instance.create_image(options)
image.id
#=> "image-id"

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :name (required, String)

    A name for the new image.

    Constraints: 3-128 alphanumeric characters, parentheses (()), square brackets ([]), spaces ( ), periods (.), slashes (/), dashes (-), single quotes (\'), at-signs (@), or underscores(_)

  • :description (String)

    A description for the new image.

  • :no_reboot (Boolean)

    By default, Amazon EC2 attempts to shut down and reboot the instance before creating the image. If the \'No Reboot\' option is set, Amazon EC2 doesn\'t shut down the instance before creating the image. When this option is used, file system integrity on the created image can\'t be guaranteed.

  • :block_device_mappings (Array<Types::BlockDeviceMapping>)

    Information about one or more block device mappings.

Returns:

See Also:

#create_tags(options = {}) ⇒ Array<Tag>

Examples:

Request syntax example with placeholder values


instance.create_tags({
  dry_run: false,
  tags: [ # required
    {
      key: "String",
      value: "String",
    },
  ],
})

Basic usage

tags = instance.create_tags(options)
tags.map(&:value)
#=> ["tag-value", ...]

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :tags (required, Array<Types::Tag>)

    One or more tags. The value parameter is required, but if you don\'t want the tag to have a value, specify the parameter with no value, and we set the value to an empty string.

Returns:

See Also:

#decrypt_windows_password(key_pair_path) ⇒ String

Parameters:

  • key_pair_path (String, Pathname)

Returns:

  • (String)


9
10
11
12
13
14
# File 'aws-sdk-resources/lib/aws-sdk-resources/services/ec2/instance.rb', line 9

def decrypt_windows_password(key_pair_path)
  decoded = Base64.decode64(encrypted_password)
  pem_bytes = File.open(key_pair_path, 'rb') { |f| f.read }
  private_key = OpenSSL::PKey::RSA.new(pem_bytes)
  private_key.private_decrypt(decoded)
end

#describe_attribute(options = {}) ⇒ Types::InstanceAttribute

Describes the specified attribute of the specified instance. You can specify only one attribute at a time. Valid attribute values are: instanceType | kernel | ramdisk | userData | disableApiTermination | instanceInitiatedShutdownBehavior | rootDeviceName | blockDeviceMapping | productCodes | sourceDestCheck | groupSet | ebsOptimized | sriovNetSupport

Examples:

Request syntax example with placeholder values


instance.describe_attribute({
  dry_run: false,
  attribute: "instanceType", # required, accepts instanceType, kernel, ramdisk, userData, disableApiTermination, instanceInitiatedShutdownBehavior, rootDeviceName, blockDeviceMapping, productCodes, sourceDestCheck, groupSet, ebsOptimized, sriovNetSupport, enaSupport
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :attribute (required, String)

    The instance attribute.

    Note: The enaSupport attribute is not supported at this time.

Returns:

See Also:

Unlinks (detaches) a linked EC2-Classic instance from a VPC. After the instance has been unlinked, the VPC security groups are no longer associated with it. An instance is automatically unlinked from a VPC when it's stopped.

Examples:

Request syntax example with placeholder values


instance.detach_classic_link_vpc({
  dry_run: false,
  vpc_id: "String", # required
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :vpc_id (required, String)

    The ID of the VPC to which the instance is linked.

Returns:

See Also:

#detach_volume(options = {}) ⇒ Types::VolumeAttachment

Detaches an EBS volume from an instance. Make sure to unmount any file systems on the device within your operating system before detaching the volume. Failure to do so can result in the volume becoming stuck in the busy state while detaching. If this happens, detachment can be delayed indefinitely until you unmount the volume, force detachment, reboot the instance, or all three. If an EBS volume is the root device of an instance, it can't be detached while the instance is running. To detach the root volume, stop the instance first.

When a volume with an AWS Marketplace product code is detached from an instance, the product code is no longer associated with the instance.

For more information, see Detaching an Amazon EBS Volume in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.detach_volume({
  dry_run: false,
  volume_id: "String", # required
  device: "String",
  force: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :volume_id (required, String)

    The ID of the volume.

  • :device (String)

    The device name.

  • :force (Boolean)

    Forces detachment if the previous detachment attempt did not occur cleanly (for example, logging into an instance, unmounting the volume, and detaching normally). This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance won\'t have an opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures.

Returns:

See Also:

#exists?Boolean

Returns true if this Instance exists. Returns false otherwise.

Returns:

  • (Boolean)

    Returns true if this Instance exists. Returns false otherwise.

#imageImage?

Returns:

See Also:

#key_pairKeyPairInfo?

Returns:

#modify_attribute(options = {}) ⇒ Struct

Modifies the specified attribute of the specified instance. You can specify only one attribute at a time.

To modify some attributes, the instance must be stopped. For more information, see Modifying Attributes of a Stopped Instance in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.modify_attribute({
  dry_run: false,
  attribute: "instanceType", # accepts instanceType, kernel, ramdisk, userData, disableApiTermination, instanceInitiatedShutdownBehavior, rootDeviceName, blockDeviceMapping, productCodes, sourceDestCheck, groupSet, ebsOptimized, sriovNetSupport, enaSupport
  value: "String",
  block_device_mappings: [
    {
      device_name: "String",
      ebs: {
        volume_id: "String",
        delete_on_termination: false,
      },
      virtual_name: "String",
      no_device: "String",
    },
  ],
  source_dest_check: {
    value: false,
  },
  disable_api_termination: {
    value: false,
  },
  instance_type: "value", # value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>
  kernel: "value", # value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>
  ramdisk: "value", # value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>
  user_data: {
    value: "data",
  },
  instance_initiated_shutdown_behavior: "value", # value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>
  groups: ["String"],
  ebs_optimized: {
    value: false,
  },
  sriov_net_support: "value", # value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>
  ena_support: {
    value: false,
  },
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :attribute (String)

    The name of the attribute.

  • :value (String)

    A new value for the attribute. Use only with the kernel, ramdisk, userData, disableApiTermination, or instanceInitiatedShutdownBehavior attribute.

  • :block_device_mappings (Array<Types::InstanceBlockDeviceMappingSpecification>)

    Modifies the DeleteOnTermination attribute for volumes that are currently attached. The volume must be owned by the caller. If no value is specified for DeleteOnTermination, the default is true and the volume is deleted when the instance is terminated.

    To add instance store volumes to an Amazon EBS-backed instance, you must add them when you launch the instance. For more information, see Updating the Block Device Mapping when Launching an Instance in the Amazon Elastic Compute Cloud User Guide.

  • :source_dest_check (Types::AttributeBooleanValue)

    Specifies whether source/destination checking is enabled. A value of true means that checking is enabled, and false means checking is disabled. This value must be false for a NAT instance to perform NAT.

  • :disable_api_termination (Types::AttributeBooleanValue)

    If the value is true, you can\'t terminate the instance using the Amazon EC2 console, CLI, or API; otherwise, you can. You cannot use this paramater for Spot Instances.

  • :instance_type (Types::AttributeValue)

    Changes the instance type to the specified value. For more information, see Instance Types. If the instance type is not valid, the error returned is InvalidInstanceAttributeValue.

  • :kernel (Types::AttributeValue)

    Changes the instance\'s kernel to the specified value. We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB.

  • :ramdisk (Types::AttributeValue)

    Changes the instance\'s RAM disk to the specified value. We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB.

  • :user_data (Types::BlobAttributeValue)

    Changes the instance\'s user data to the specified value. If you are using an AWS SDK or command line tool, Base64-encoding is performed for you, and you can load the text from a file. Otherwise, you must provide Base64-encoded text.

  • :instance_initiated_shutdown_behavior (Types::AttributeValue)

    Specifies whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown).

  • :groups (Array<String>)

    [EC2-VPC] Changes the security groups of the instance. You must specify at least one security group, even if it\'s just the default security group for the VPC. You must specify the security group ID, not the security group name.

  • :ebs_optimized (Types::AttributeBooleanValue)

    Specifies whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal EBS I/O performance. This optimization isn\'t available with all instance types. Additional usage charges apply when using an EBS Optimized instance.

  • :sriov_net_support (Types::AttributeValue)

    Set to simple to enable enhanced networking with the Intel 82599 Virtual Function interface for the instance.

    There is no way to disable enhanced networking with the Intel 82599 Virtual Function interface at this time.

    This option is supported only for HVM instances. Specifying this option with a PV instance can make it unreachable.

  • :ena_support (Types::AttributeBooleanValue)

    Set to true to enable enhanced networking with ENA for the instance.

    This option is supported only for HVM instances. Specifying this option with a PV instance can make it unreachable.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#monitor(options = {}) ⇒ Types::MonitorInstancesResult

Enables detailed monitoring for a running instance. Otherwise, basic monitoring is enabled. For more information, see Monitoring Your Instances and Volumes in the Amazon Elastic Compute Cloud User Guide.

To disable detailed monitoring, see .

Examples:

Request syntax example with placeholder values


instance.monitor({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

See Also:

#network_interfacesArray<NetworkInterface>?

Returns:

#password_data(options = {}) ⇒ Types::GetPasswordDataResult

Retrieves the encrypted administrator password for an instance running Windows.

The Windows password is generated at boot if the EC2Config service plugin, Ec2SetPassword, is enabled. This usually only happens the first time an AMI is launched, and then Ec2SetPassword is automatically disabled. The password is not generated for rebundled AMIs unless Ec2SetPassword is enabled before bundling.

The password is encrypted using the key pair that you specified when you launched the instance. You must provide the corresponding key pair file.

Password generation and encryption takes a few moments. We recommend that you wait up to 15 minutes after launching an instance before trying to retrieve the generated password.

Examples:

Request syntax example with placeholder values


instance.password_data({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

See Also:

#placement_groupPlacementGroup?

Returns:

#reboot(options = {}) ⇒ Struct

Requests a reboot of one or more instances. This operation is asynchronous; it only queues a request to reboot the specified instances. The operation succeeds if the instances are valid and belong to you. Requests to reboot terminated instances are ignored.

If an instance does not cleanly shut down within four minutes, Amazon EC2 performs a hard reboot.

For more information about troubleshooting, see Getting Console Output and Rebooting Instances in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.reboot({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#report_status(options = {}) ⇒ Struct

Submits feedback about the status of an instance. The instance must be in the running state. If your experience with the instance differs from the instance status returned by DescribeInstanceStatus, use ReportInstanceStatus to report your experience with the instance. Amazon EC2 collects this information to improve the accuracy of status checks.

Use of this action does not change the value returned by DescribeInstanceStatus.

Examples:

Request syntax example with placeholder values


instance.report_status({
  dry_run: false,
  status: "ok", # required, accepts ok, impaired
  start_time: Time.now,
  end_time: Time.now,
  reason_codes: ["instance-stuck-in-state"], # required, accepts instance-stuck-in-state, unresponsive, not-accepting-credentials, password-not-available, performance-network, performance-instance-store, performance-ebs-volume, performance-other, other
  description: "String",
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :status (required, String)

    The status of all instances listed.

  • :start_time (Time)

    The time at which the reported instance health state began.

  • :end_time (Time)

    The time at which the reported instance health state ended.

  • :reason_codes (required, Array<String>)

    One or more reason codes that describes the health state of your instance.

    • instance-stuck-in-state: My instance is stuck in a state.

    • unresponsive: My instance is unresponsive.

    • not-accepting-credentials: My instance is not accepting my credentials.

    • password-not-available: A password is not available for my instance.

    • performance-network: My instance is experiencing performance problems which I believe are network related.

    • performance-instance-store: My instance is experiencing performance problems which I believe are related to the instance stores.

    • performance-ebs-volume: My instance is experiencing performance problems which I believe are related to an EBS volume.

    • performance-other: My instance is experiencing performance problems.

    • other: [explain using the description parameter]

  • :description (String)

    Descriptive text about the health state of your instance.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#reset_attribute(options = {}) ⇒ Struct

Resets an attribute of an instance to its default value. To reset the kernel or ramdisk, the instance must be in a stopped state. To reset the sourceDestCheck, the instance can be either running or stopped.

The sourceDestCheck attribute controls whether source/destination checking is enabled. The default value is true, which means checking is enabled. This value must be false for a NAT instance to perform NAT. For more information, see NAT Instances in the Amazon Virtual Private Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.reset_attribute({
  dry_run: false,
  attribute: "instanceType", # required, accepts instanceType, kernel, ramdisk, userData, disableApiTermination, instanceInitiatedShutdownBehavior, rootDeviceName, blockDeviceMapping, productCodes, sourceDestCheck, groupSet, ebsOptimized, sriovNetSupport, enaSupport
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :attribute (required, String)

    The attribute to reset.

    You can only reset the following attributes: kernel | ramdisk | sourceDestCheck. To change an instance attribute, use ModifyInstanceAttribute.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#reset_kernel(options = {}) ⇒ Struct

Resets an attribute of an instance to its default value. To reset the kernel or ramdisk, the instance must be in a stopped state. To reset the sourceDestCheck, the instance can be either running or stopped.

The sourceDestCheck attribute controls whether source/destination checking is enabled. The default value is true, which means checking is enabled. This value must be false for a NAT instance to perform NAT. For more information, see NAT Instances in the Amazon Virtual Private Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.reset_kernel({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#reset_ramdisk(options = {}) ⇒ Struct

Resets an attribute of an instance to its default value. To reset the kernel or ramdisk, the instance must be in a stopped state. To reset the sourceDestCheck, the instance can be either running or stopped.

The sourceDestCheck attribute controls whether source/destination checking is enabled. The default value is true, which means checking is enabled. This value must be false for a NAT instance to perform NAT. For more information, see NAT Instances in the Amazon Virtual Private Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.reset_ramdisk({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#reset_source_dest_check(options = {}) ⇒ Struct

Resets an attribute of an instance to its default value. To reset the kernel or ramdisk, the instance must be in a stopped state. To reset the sourceDestCheck, the instance can be either running or stopped.

The sourceDestCheck attribute controls whether source/destination checking is enabled. The default value is true, which means checking is enabled. This value must be false for a NAT instance to perform NAT. For more information, see NAT Instances in the Amazon Virtual Private Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.reset_source_dest_check({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#start(options = {}) ⇒ Types::StartInstancesResult

Starts an Amazon EBS-backed AMI that you've previously stopped.

Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When an instance is stopped, the compute resources are released and you are not billed for hourly instance usage. However, your root partition Amazon EBS volume remains, continues to persist your data, and you are charged for Amazon EBS volume usage. You can restart your instance at any time. Each time you transition an instance from stopped to started, Amazon EC2 charges a full instance hour, even if transitions happen multiple times within a single hour.

Before stopping an instance, make sure it is in a state from which it can be restarted. Stopping an instance does not preserve data stored in RAM.

Performing this operation on an instance that uses an instance store as its root device returns an error.

For more information, see Stopping Instances in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.start({
  additional_info: "String",
  dry_run: false,
})

Options Hash (options):

  • :additional_info (String)

    Reserved.

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

See Also:

#stop(options = {}) ⇒ Types::StopInstancesResult

Stops an Amazon EBS-backed instance.

We don't charge hourly usage for a stopped instance, or data transfer fees; however, your root partition Amazon EBS volume remains, continues to persist your data, and you are charged for Amazon EBS volume usage. Each time you transition an instance from stopped to started, Amazon EC2 charges a full instance hour, even if transitions happen multiple times within a single hour.

You can't start or stop Spot instances, and you can't stop instance store-backed instances.

When you stop an instance, we shut it down. You can restart your instance at any time. Before stopping an instance, make sure it is in a state from which it can be restarted. Stopping an instance does not preserve data stored in RAM.

Stopping an instance is different to rebooting or terminating it. For example, when you stop an instance, the root device and any other devices attached to the instance persist. When you terminate an instance, the root device and any other devices attached during the instance launch are automatically deleted. For more information about the differences between rebooting, stopping, and terminating instances, see Instance Lifecycle in the Amazon Elastic Compute Cloud User Guide.

When you stop an instance, we attempt to shut it down forcibly after a short while. If your instance appears stuck in the stopping state after a period of time, there may be an issue with the underlying host computer. For more information, see Troubleshooting Stopping Your Instance in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.stop({
  dry_run: false,
  force: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :force (Boolean)

    Forces the instances to stop. The instances do not have an opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures. This option is not recommended for Windows instances.

    Default: false

Returns:

See Also:

#subnetSubnet?

Returns:

#terminate(options = {}) ⇒ Types::TerminateInstancesResult

Shuts down one or more instances. This operation is idempotent; if you terminate an instance more than once, each call succeeds.

If you specify multiple instances and the request fails (for example, because of a single incorrect instance ID), none of the instances are terminated.

Terminated instances remain visible after termination (for approximately one hour).

By default, Amazon EC2 deletes all EBS volumes that were attached when the instance launched. Volumes attached after instance launch continue running.

You can stop, start, and terminate EBS-backed instances. You can only terminate instance store-backed instances. What happens to an instance differs if you stop it or terminate it. For example, when you stop an instance, the root device and any other devices attached to the instance persist. When you terminate an instance, any attached EBS volumes with the DeleteOnTermination block device mapping parameter set to true are automatically deleted. For more information about the differences between stopping and terminating instances, see Instance Lifecycle in the Amazon Elastic Compute Cloud User Guide.

For more information about troubleshooting, see Troubleshooting Terminating Your Instance in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.terminate({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

See Also:

#unmonitor(options = {}) ⇒ Types::UnmonitorInstancesResult

Disables detailed monitoring for a running instance. For more information, see Monitoring Your Instances and Volumes in the Amazon Elastic Compute Cloud User Guide.

Examples:

Request syntax example with placeholder values


instance.unmonitor({
  dry_run: false,
})

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Returns:

See Also:

#volumes(options = {}) ⇒ Collection<Volume>

Returns a Collection of Volume resources. No API requests are made until you call an enumerable method on the collection. Client#describe_volumes will be called multiple times until every Volume has been yielded.

Examples:

Request syntax example with placeholder values


instance.volumes({
  dry_run: false,
  volume_ids: ["String"],
  next_token: "String",
  max_results: 1,
})

Enumerating Volume resources.

instance.volumes.each do |volume|
  # yields each volume
end

Enumerating Volume resources with a limit.

instance.volumes.limit(10).each do |volume|
  # yields at most 10 volumes
end

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :volume_ids (Array<String>)

    One or more volume IDs.

  • :next_token (String)

    The NextToken value returned from a previous paginated DescribeVolumes request where MaxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the NextToken value. This value is null when there are no more results to return.

  • :max_results (Integer)

    The maximum number of volume results returned by DescribeVolumes in paginated output. When this parameter is used, DescribeVolumes only returns MaxResults results in a single page along with a NextToken response element. The remaining results of the initial request can be seen by sending another DescribeVolumes request with the returned NextToken value. This value can be between 5 and 500; if MaxResults is given a value larger than 500, only 500 results are returned. If this parameter is not used, then DescribeVolumes returns all results. You cannot specify this parameter and the volume IDs parameter in the same request.

Returns:

See Also:

#vpcVpc?

Returns:

#vpc_addresses(options = {}) ⇒ Collection<VpcAddress>

Returns a Collection of VpcAddress resources. No API requests are made until you call an enumerable method on the collection. Client#describe_addresses will be called multiple times until every VpcAddress has been yielded.

Examples:

Request syntax example with placeholder values


instance.vpc_addresses({
  dry_run: false,
  public_ips: ["String"],
  allocation_ids: ["String"],
})

Enumerating VpcAddress resources.

instance.vpc_addresses.each do |vpcaddress|
  # yields each vpcaddress
end

Enumerating VpcAddress resources with a limit.

instance.vpc_addresses.limit(10).each do |vpcaddress|
  # yields at most 10 vpc_addresses
end

Options Hash (options):

  • :dry_run (Boolean)

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

  • :public_ips (Array<String>)

    [EC2-Classic] One or more Elastic IP addresses.

    Default: Describes all your Elastic IP addresses.

  • :allocation_ids (Array<String>)

    [EC2-VPC] One or more allocation IDs.

    Default: Describes all your Elastic IP addresses.

Returns:

See Also:

#wait_until_exists {|waiter| ... } ⇒ Instance

Waits until this Instance is exists. This method waits by polling Client#describe_instances until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 5
#max_attempts 40

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

instance.wait_until_exists

Yield Parameters:

Returns:

  • (Instance)

    Returns a copy of this Instance with loaded data.

Raises:

See Also:

#wait_until_running {|waiter| ... } ⇒ Instance

Waits until this Instance is running. This method waits by polling Client#describe_instances until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 15
#max_attempts 40

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

instance.wait_until_running

Yield Parameters:

Returns:

  • (Instance)

    Returns a copy of this Instance with loaded data.

Raises:

See Also:

#wait_until_stopped {|waiter| ... } ⇒ Instance

Waits until this Instance is stopped. This method waits by polling Client#describe_instances until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 15
#max_attempts 40

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

instance.wait_until_stopped

Yield Parameters:

Returns:

  • (Instance)

    Returns a copy of this Instance with loaded data.

Raises:

See Also:

#wait_until_terminated {|waiter| ... } ⇒ Instance

Waits until this Instance is terminated. This method waits by polling Client#describe_instances until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 15
#max_attempts 40

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

instance.wait_until_terminated

Yield Parameters:

Returns:

  • (Instance)

    Returns a copy of this Instance with loaded data.

Raises:

See Also: