org.jclouds.ec2.services

Interface InstanceClient

All Known Subinterfaces:

AWSInstanceClient

public interface InstanceClient

Provides access to EC2 via their REST API.

Author:

Adrian Cole

Method Summary

Methods

Modifier and Type	Method and Description
Set<? extends Reservation<? extends RunningInstance>>	describeInstancesInRegion(String region, String... instanceIds) Returns information about instances that you own.
Map<String,BlockDevice>	getBlockDeviceMappingForInstanceInRegion(String region, String instanceId)
Volume.InstanceInitiatedShutdownBehavior	getInstanceInitiatedShutdownBehaviorForInstanceInRegion(String region, String instanceId)
String	getInstanceTypeForInstanceInRegion(String region, String instanceId)
String	getKernelForInstanceInRegion(String region, String instanceId)
String	getRamdiskForInstanceInRegion(String region, String instanceId)
String	getRootDeviceNameForInstanceInRegion(String region, String instanceId)
String	getUserDataForInstanceInRegion(String region, String instanceId)
boolean	isApiTerminationDisabledForInstanceInRegion(String region, String instanceId)
void	rebootInstancesInRegion(String region, String... instanceIds) Requests a reboot of one or more instances.
String	resetKernelForInstanceInRegion(String region, String instanceId) Resets an attribute of an instance to its default value.
String	resetRamdiskForInstanceInRegion(String region, String instanceId) Resets an attribute of an instance to its default value.
Reservation<? extends RunningInstance>	runInstancesInRegion(String region, String nullableAvailabilityZone, String imageId, int minCount, int maxCount, RunInstancesOptions... options) Launches a specified number of instances of an AMI for which you have permissions.
void	setApiTerminationDisabledForInstanceInRegion(String region, String instanceId, boolean apiTerminationDisabled) This command works while the instance is running and controls whether or not the api can be used to terminate the instance.
void	setBlockDeviceMappingForInstanceInRegion(String region, String instanceId, Map<String,BlockDevice> blockDeviceMapping) Sets the blockDeviceMapping used for an instance.
void	setInstanceInitiatedShutdownBehaviorForInstanceInRegion(String region, String instanceId, Volume.InstanceInitiatedShutdownBehavior instanceInitiatedShutdownBehavior) Specifies whether the instance's Amazon EBS volumes are stopped or terminated when the instance is shut down.
void	setInstanceTypeForInstanceInRegion(String region, String instanceId, String instanceType) Sets the instanceType used for starting the instance.
void	setKernelForInstanceInRegion(String region, String instanceId, String kernel) Sets the kernelId used for starting the instance.
void	setRamdiskForInstanceInRegion(String region, String instanceId, String ramdisk) Sets the ramdisk used for starting the instance.
void	setUserDataForInstanceInRegion(String region, String instanceId, byte[] unencodedData) Sets the userData used for starting the instance.
Set<? extends InstanceStateChange>	startInstancesInRegion(String region, String... instanceIds) Starts an instance that uses an Amazon EBS volume as its root device.
Set<? extends InstanceStateChange>	stopInstancesInRegion(String region, boolean force, String... instanceIds) Stops an instance that uses an Amazon EBS volume as its root device.
Set<? extends InstanceStateChange>	terminateInstancesInRegion(String region, String... instanceIds) Shuts down one or more instances.

Method Detail

describeInstancesInRegion

Set<? extends Reservation<? extends RunningInstance>> describeInstancesInRegion(@Nullable
                                                                              String region,
                                                                              String... instanceIds)

Returns information about instances that you own.

If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an invalid instance ID, a fault is returned. If you specify an instance that you do not own, it will not be included in the returned results.

Recently terminated instances might appear in the returned results.This interval is usually less than one hour.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

See Also:

runInstancesInRegion(java.lang.String, java.lang.String, java.lang.String, int, int, org.jclouds.ec2.options.RunInstancesOptions...), terminateInstancesInRegion(java.lang.String, java.lang.String...),

runInstancesInRegion

Reservation<? extends RunningInstance> runInstancesInRegion(@Nullable
                                                          String region,
                                                          @Nullable
                                                          String nullableAvailabilityZone,
                                                          String imageId,
                                                          int minCount,
                                                          int maxCount,
                                                          RunInstancesOptions... options)

Launches a specified number of instances of an AMI for which you have permissions.

If Amazon EC2 cannot launch the minimum number AMIs you request, no instances will be launched. If there is insufficient capacity to launch the maximum number of AMIs you request, Amazon EC2 launches the minimum number specified for each AMI and allocate the remaining available instances using round robin.

Security Groups

Note: Every instance is launched in a security group (created using the CreateSecurityGroup operation.

Key Pair

You can provide an optional key pair ID for each image in the launch request (created using the CreateKeyPair operation). All instances that are created from images that use this key pair will have access to the associated public key at boot. You can use this key to provide secure access to an instance of an image on a per-instance basis. Amazon EC2 public images use this feature to provide secure access without passwords.

Note: Launching public images without a key pair ID will leave them inaccessible.

The public key material is made available to the instance at boot time by placing it in the openssh_id.pub file on a logical device that is exposed to the instance as /dev/sda2 (the instance store). The format of this file is suitable for use as an entry within ~/.ssh/authorized_keys (the OpenSSH format). This can be done at boot (e.g., as part of rc.local) allowing for secure access without passwords.

User Data

Optional user data can be provided in the launch request. All instances that collectively comprise the launch request have access to this data. For more information, go the Amazon Elastic Compute Cloud Developer Guide.

Product Codes

Note: If any of the AMIs have a product code attached for which the user has not subscribed, the RunInstances call will fail.

Kernel

Important: We strongly recommend using the 2.6.18 Xen stock kernel with High-CPU and High-Memory instances. Although the default Amazon EC2 kernels will work, the new kernels provide greater stability and performance for these instance types. For more information about kernels, go the Amazon Elastic Compute Cloud Developer Guide.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

nullableAvailabilityZone - Specifies the placement constraints (Availability Zones) for launching the instances. If null, Amazon will determine the best availability zone to place the instance.

imageId - Unique ID of a machine image, returned by a call to

minCount - Minimum number of instances to launch. If the value is more than Amazon EC2 can launch, no instances a re launched at all. Constraints: Between 1 and the maximum number allowed for your account (default: 20).

maxCount - Maximum number of instances to launch. If the value is more than Amazon EC2 can launch, the largest possible number above minCount will be launched instead. Constraints: Between 1 and the maximum number allowed for your account (default: 20).

See Also:

describeInstancesInRegion(java.lang.String, java.lang.String...), terminateInstancesInRegion(java.lang.String, java.lang.String...), #authorizeSecurityGroupIngressInRegion, #revokeSecurityGroupIngressInRegion, #describeSecurityGroupsInRegion, #createSecurityGroupInRegion, #createKeyPairInRegion, , RunInstancesOptions

terminateInstancesInRegion

Set<? extends InstanceStateChange> terminateInstancesInRegion(@Nullable
                                                            String region,
                                                            String... instanceIds)

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

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

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceIds - Instance ID to terminate.

See Also:

describeInstancesInRegion(java.lang.String, java.lang.String...),

stopInstancesInRegion

Set<? extends InstanceStateChange> stopInstancesInRegion(@Nullable
                                                       String region,
                                                       boolean force,
                                                       String... instanceIds)

Stops an instance that uses an Amazon EBS volume as its root device.

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.

Note

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.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

force - Forces the instance to stop. The instance will not have an opportunity to flush file system caches nor file system meta data. If you use this option, you must perform file system check and repair procedures. This option is not recommended for Windows instances.

instanceIds - Instance ID to stop.

See Also:

startInstancesInRegion(java.lang.String, java.lang.String...), runInstancesInRegion(java.lang.String, java.lang.String, java.lang.String, int, int, org.jclouds.ec2.options.RunInstancesOptions...), describeInstancesInRegion(java.lang.String, java.lang.String...), terminateInstancesInRegion(java.lang.String, java.lang.String...),

rebootInstancesInRegion

void rebootInstancesInRegion(@Nullable
                           String region,
                           String... instanceIds)

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

Note

If a Linux/UNIX instance does not cleanly shut down within four minutes, Amazon EC2 will perform a hard reboot.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceIds - Instance ID to reboot.

See Also:

startInstancesInRegion(java.lang.String, java.lang.String...), runInstancesInRegion(java.lang.String, java.lang.String, java.lang.String, int, int, org.jclouds.ec2.options.RunInstancesOptions...), describeInstancesInRegion(java.lang.String, java.lang.String...), terminateInstancesInRegion(java.lang.String, java.lang.String...),

startInstancesInRegion

Set<? extends InstanceStateChange> startInstancesInRegion(@Nullable
                                                        String region,
                                                        String... instanceIds)

Starts an instance that uses an Amazon EBS volume as its root device.

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.

Note

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.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceIds - Instance ID to start.

See Also:

stopInstancesInRegion(java.lang.String, boolean, java.lang.String...), runInstancesInRegion(java.lang.String, java.lang.String, java.lang.String, int, int, org.jclouds.ec2.options.RunInstancesOptions...), describeInstancesInRegion(java.lang.String, java.lang.String...), terminateInstancesInRegion(java.lang.String, java.lang.String...),

getUserDataForInstanceInRegion

String getUserDataForInstanceInRegion(@Nullable
                                    String region,
                                    String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

unencoded user data

getRootDeviceNameForInstanceInRegion

String getRootDeviceNameForInstanceInRegion(@Nullable
                                          String region,
                                          String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

The root device name (e.g., /dev/sda1).

getRamdiskForInstanceInRegion

String getRamdiskForInstanceInRegion(@Nullable
                                   String region,
                                   String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

the ID of the RAM disk associated with the AMI.

getKernelForInstanceInRegion

String getKernelForInstanceInRegion(@Nullable
                                  String region,
                                  String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

the ID of the kernel associated with the AMI.

isApiTerminationDisabledForInstanceInRegion

boolean isApiTerminationDisabledForInstanceInRegion(@Nullable
                                                  String region,
                                                  String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

Specifies whether the instance can be terminated using the APIs. You must modify this attribute before you can terminate any "locked" instances from the APIs.

getInstanceTypeForInstanceInRegion

String getInstanceTypeForInstanceInRegion(@Nullable
                                        String region,
                                        String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

The instance type of the instance.

getInstanceInitiatedShutdownBehaviorForInstanceInRegion

Volume.InstanceInitiatedShutdownBehavior getInstanceInitiatedShutdownBehaviorForInstanceInRegion(String region,
                                                                                               String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

whether the instance's Amazon EBS volumes are stopped or terminated when the instance is shut down.

getBlockDeviceMappingForInstanceInRegion

Map<String,BlockDevice> getBlockDeviceMappingForInstanceInRegion(@Nullable
                                                               String region,
                                                               String instanceId)

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to describe the attribute of

Returns:

Describes the mapping that defines native device names to use when exposing virtual devices.

resetRamdiskForInstanceInRegion

String resetRamdiskForInstanceInRegion(@Nullable
                                     String region,
                                     String instanceId)

Resets an attribute of an instance to its default value.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to reset the attribute of

Returns:

the ID of the RAM disk associated with the AMI.

resetKernelForInstanceInRegion

String resetKernelForInstanceInRegion(@Nullable
                                    String region,
                                    String instanceId)

Resets an attribute of an instance to its default value.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to reset the attribute of

Returns:

the ID of the kernel associated with the AMI.

setUserDataForInstanceInRegion

void setUserDataForInstanceInRegion(@Nullable
                                  String region,
                                  String instanceId,
                                  byte[] unencodedData)

Sets the userData used for starting the instance.

The instance needs to be in a InstanceState.STOPPED state, which implies two things:

1. The instance was launched from an EBS-backed AMI so that it can stop
2. You have stopped and waited for the instance to transition from InstanceState.STOPPING to InstanceState.STOPPED

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to change the attribute of

unencodedData - unencoded data to set as userData

See Also:

setRamdiskForInstanceInRegion

void setRamdiskForInstanceInRegion(@Nullable
                                 String region,
                                 String instanceId,
                                 String ramdisk)

Sets the ramdisk used for starting the instance.

The instance needs to be in a InstanceState.STOPPED state, which implies two things:

1. The instance was launched from an EBS-backed AMI so that it can stop
2. You have stopped and waited for the instance to transition from InstanceState.STOPPING to InstanceState.STOPPED

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to change the attribute of

ramdisk - ramdisk used to start the instance

See Also:

setKernelForInstanceInRegion

void setKernelForInstanceInRegion(@Nullable
                                String region,
                                String instanceId,
                                String kernel)

Sets the kernelId used for starting the instance.

The instance needs to be in a InstanceState.STOPPED state, which implies two things:

1. The instance was launched from an EBS-backed AMI so that it can stop
2. You have stopped and waited for the instance to transition from InstanceState.STOPPING to InstanceState.STOPPED

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to change the attribute of

kernel - kernelId used to start the instance

See Also:

setApiTerminationDisabledForInstanceInRegion

void setApiTerminationDisabledForInstanceInRegion(@Nullable
                                                String region,
                                                String instanceId,
                                                boolean apiTerminationDisabled)

This command works while the instance is running and controls whether or not the api can be used to terminate the instance.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to reset the attribute of

apiTerminationDisabled - true to disable api termination

See Also:

setInstanceTypeForInstanceInRegion

void setInstanceTypeForInstanceInRegion(@Nullable
                                      String region,
                                      String instanceId,
                                      String instanceType)

Sets the instanceType used for starting the instance.

The instance needs to be in a InstanceState.STOPPED state, which implies two things:

1. The instance was launched from an EBS-backed AMI so that it can stop
2. You have stopped and waited for the instance to transition from InstanceState.STOPPING to InstanceState.STOPPED

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to change the attribute of

instanceType - instanceType used to start the instance

See Also:

setInstanceInitiatedShutdownBehaviorForInstanceInRegion

void setInstanceInitiatedShutdownBehaviorForInstanceInRegion(@Nullable
                                                           String region,
                                                           String instanceId,
                                                           Volume.InstanceInitiatedShutdownBehavior instanceInitiatedShutdownBehavior)

Specifies whether the instance's Amazon EBS volumes are stopped or terminated when the instance is shut down.

The instance needs to be in a InstanceState.STOPPED state, which implies two things:

1. The instance was launched from an EBS-backed AMI so that it can stop
2. You have stopped and waited for the instance to transition from InstanceState.STOPPING to InstanceState.STOPPED

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to change the attribute of

instanceInitiatedShutdownBehavior - whether the instance's Amazon EBS volumes are stopped or terminated when the instance is shut down.

See Also:

setBlockDeviceMappingForInstanceInRegion

void setBlockDeviceMappingForInstanceInRegion(@Nullable
                                            String region,
                                            String instanceId,
                                            Map<String,BlockDevice> blockDeviceMapping)

Sets the blockDeviceMapping used for an instance.

The instance needs to be in a InstanceState.STOPPED state, which implies two things:

1. The instance was launched from an EBS-backed AMI so that it can stop
2. You have stopped and waited for the instance to transition from InstanceState.STOPPING to InstanceState.STOPPED

To create the instances of BlockDevice, the constructor can be used with the following parameters: BlockDevice#EbsBlockDevice(String, String, boolean) , that are:

1. Volume id (required), for instance, "vol-blah"
2. Device name (optional), for instance, "/dev/sda1". To find out more about device names, read the next paragraph.
3. Delete on termination flag (optional), which defines whether the volume will be deleted upon instance's termination.

Note that the device names between Linux and Windows differ. For Linux, ensure that your device name is in the form /dev/sd[a-z] . For example, /dev/sda , /dev/sdb and /dev/sdh are all valid device names.

For Windows, the root device is still referred to as /dev/sda1 . For other devices, ensure that they are in the form /xvd[c-p] . For example, /xvde , /xvdf and /xvdp are all valid Windows device names.

NOTE: As of now 02/20/2010, this command only works to change the DeleteOnTermination property of the device. The volume must be attached to a stopped instance.

Parameters:

region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.

instanceId - which instance to change the attribute of

blockDeviceMapping - blockDeviceMapping used to start the instance

See Also: