Package org.jclouds.ec2.features

Interface InstanceApi

  • All Known Subinterfaces:
    AWSInstanceApi
    public interface InstanceApi
    Provides access to EC2 Instance Services via their REST API.

    • Method Detail

      • runInstancesInRegion

        @Named("RunInstances")
@POST
@Path("/")
Reservation<? extends RunningInstance> runInstancesInRegion​(@Nullable
                                                            String region,
                                                            @Nullable
                                                            String nullableAvailabilityZone,
                                                            @FormParam("ImageId")
                                                            String imageId,
                                                            @FormParam("MinCount")
                                                            int minCount,
                                                            @FormParam("MaxCount")
                                                            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

        @Named("TerminateInstances")
@POST
@Path("/")
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...),

      • getUserDataForInstanceInRegion

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
String getUserDataForInstanceInRegion​(@Nullable
                                      String region,
                                      @FormParam("InstanceId")
                                      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

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
String getRootDeviceNameForInstanceInRegion​(@Nullable
                                            String region,
                                            @FormParam("InstanceId")
                                            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

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
String getRamdiskForInstanceInRegion​(@Nullable
                                     String region,
                                     @FormParam("InstanceId")
                                     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

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
String getKernelForInstanceInRegion​(@Nullable
                                    String region,
                                    @FormParam("InstanceId")
                                    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

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
boolean isApiTerminationDisabledForInstanceInRegion​(@Nullable
                                                    String region,
                                                    @FormParam("InstanceId")
                                                    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

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
String getInstanceTypeForInstanceInRegion​(@Nullable
                                          String region,
                                          @FormParam("InstanceId")
                                          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

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
Volume.InstanceInitiatedShutdownBehavior getInstanceInitiatedShutdownBehaviorForInstanceInRegion​(@Nullable
                                                                                                 String region,
                                                                                                 @FormParam("InstanceId")
                                                                                                 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

        @Named("DescribeInstanceAttribute")
@POST
@Path("/")
Map<String,​BlockDevice> getBlockDeviceMappingForInstanceInRegion​(@Nullable
                                                                       String region,
                                                                       @FormParam("InstanceId")
                                                                       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

        @Named("ResetInstanceAttribute")
@POST
@Path("/")
void resetRamdiskForInstanceInRegion​(@Nullable
                                     String region,
                                     @FormParam("InstanceId")
                                     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

      • resetKernelForInstanceInRegion

        @Named("ResetInstanceAttribute")
@POST
@Path("/")
void resetKernelForInstanceInRegion​(@Nullable
                                    String region,
                                    @FormParam("InstanceId")
                                    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

      • setUserDataForInstanceInRegion

        @Named("ModifyInstanceAttribute")
@POST
@Path("/")
void setUserDataForInstanceInRegion​(@Nullable
                                    String region,
                                    @FormParam("InstanceId")
                                    String instanceId,
                                    @FormParam("Value")
                                    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

        @Named("ModifyInstanceAttribute")
@POST
@Path("/")
void setRamdiskForInstanceInRegion​(@Nullable
                                   String region,
                                   @FormParam("InstanceId")
                                   String instanceId,
                                   @FormParam("Value")
                                   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

        @Named("ModifyInstanceAttribute")
@POST
@Path("/")
void setKernelForInstanceInRegion​(@Nullable
                                  String region,
                                  @FormParam("InstanceId")
                                  String instanceId,
                                  @FormParam("Value")
                                  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

        @Named("ModifyInstanceAttribute")
@POST
@Path("/")
void setApiTerminationDisabledForInstanceInRegion​(@Nullable
                                                  String region,
                                                  @FormParam("InstanceId")
                                                  String instanceId,
                                                  @FormParam("Value")
                                                  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

        @Named("ModifyInstanceAttribute")
@POST
@Path("/")
void setInstanceTypeForInstanceInRegion​(@Nullable
                                        String region,
                                        @FormParam("InstanceId")
                                        String instanceId,
                                        @FormParam("Value")
                                        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

        @Named("ModifyInstanceAttribute")
@POST
@Path("/")
void setInstanceInitiatedShutdownBehaviorForInstanceInRegion​(@Nullable
                                                             String region,
                                                             @FormParam("InstanceId")
                                                             String instanceId,
                                                             @FormParam("Value")
                                                             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

        @Named("ModifyInstanceAttribute")
@POST
@Path("/")
void setBlockDeviceMappingForInstanceInRegion​(@Nullable
                                              String region,
                                              @FormParam("InstanceId")
                                              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:

      • getConsoleOutputForInstanceInRegion

        @Named("GetConsoleOutput")
@POST
@Path("/")
String getConsoleOutputForInstanceInRegion​(@Nullable
                                           String region,
                                           @FormParam("InstanceId")
                                           String instanceId)
        Retrieves console output for the specified instance. Instance console output is buffered and posted shortly after instance boot, reboot, and termination. Amazon EC2 preserves the most recent 64 KB output which will be available for at least one hour after the most recent post.
        Parameters:
        region - Instances are tied to Availability Zones. However, the instance ID is tied to the Region.
        instanceId - which instance to retrieve console output for
        Returns:
        The console output
        See Also:
        ApiReference query GetConsoleOutput