Elastic Compute Service:Detect and handle spot instance interruptions

Build the request object

Before building the request, see the API documentation for parameter details.

// Build the request object
DescribeInstancesRequest request = new DescribeInstancesRequest().setRegionId("cn-hangzhou");

Make the call

When calling OpenAPI operations, you can configure runtime parameters such as timeout and proxy settings. See Advanced configuration.

// Set runtime options
RuntimeOptions runtime = new RuntimeOptions();
// Call the DescribeInstances operation
DescribeInstancesResponse response = client.describeInstancesWithOptions(request, runtime);
System.out.println(response.body.toMap());

Handle exceptions

The Java SDK categorizes exceptions into TeaUnretryableException and TeaException:

• TeaUnretryableException: Typically caused by network issues after the maximum retries are reached.

• TeaException: Primarily caused by business-related errors.

Implement proper exception handling, such as propagating exceptions, logging errors, or attempting recovery, to ensure system robustness.

Complete example

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeInstancesRequest;
import com.aliyun.ecs20140526.models.DescribeInstancesResponse;
import com.aliyun.ecs20140526.models.DescribeInstancesResponseBody;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import com.alibaba.fastjson.JSONArray;

import java.util.Arrays;

public class Sample {
    private static Client createClient() throws Exception {
        Config config = new Config()
                // Required. Ensure the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is set.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Ensure the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is set.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                // Endpoint reference: https://api.aliyun.com/product/Ecs
                .setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
        return new Client(config);
    }

    public static void main(String[] args) {
        try {
            Client client = Sample.createClient();
            // Build the request object
            // Specify one or more ECS instance IDs to query.
            JSONArray instanceIds = new JSONArray();
            instanceIds.addAll(Arrays.asList("i-bp145cvd0exyqj****","i-bp1gehfgfrrk4lah****"));
            DescribeInstancesRequest request = new DescribeInstancesRequest()
                    .setRegionId("cn-hangzhou")
                    .setInstanceIds(instanceIds.toJSONString());
            // Set runtime options
            RuntimeOptions runtime = new RuntimeOptions();
            while (!instanceIds.isEmpty()) {
              // Call the DescribeInstances operation
              DescribeInstancesResponse response = client.describeInstancesWithOptions(request, runtime);
              // Get instance details from the response.
              DescribeInstancesResponseBody responseBody = response.getBody();
              DescribeInstancesResponseBody.DescribeInstancesResponseBodyInstances instanceList = responseBody.getInstances();
              // Check instance details and evaluate lockReason values.
              if (instanceList != null && instanceList.getInstance()!= null && !instanceList.getInstance().isEmpty()) {
                  for (DescribeInstancesResponseBody.DescribeInstancesResponseBodyInstancesInstance instance : instanceList.getInstance()) {
                      // Print the queried instance ID and zone ID.
                      System.out.println("result:instance:" + instance.getInstanceId() + ",az:" + instance.getZoneId());
                      if (instance.getOperationLocks() != null ) {
                          DescribeInstancesResponseBody.DescribeInstancesResponseBodyInstancesInstanceOperationLocks operationLocks  = instance.getOperationLocks();
                          if(operationLocks.getLockReason()!=null && !operationLocks.getLockReason().isEmpty()){
                              for (DescribeInstancesResponseBody.DescribeInstancesResponseBodyInstancesInstanceOperationLocksLockReason lockReason : operationLocks.getLockReason()) {
                                  // If the instance is locked, print its ID and lock reason.
                                  System.out.println("instance:" + instance.getInstanceId() + "-->lockReason:" + lockReason.getLockReason() + ",vmStatus:" + instance.getStatus());
                                  if ("Recycling".equals(lockReason.getLockReason())) {
                                      // Print the ID of the instance scheduled for immediate release.
                                      System.out.println("spot instance will be recycled immediately, instance id:" + instance.getInstanceId());
                                      instanceIds.remove(instance.getInstanceId());
                                  }
                              }
                          }

                      }
                  }
                  // If no spot instance is locked yet, query again every two minutes.
                  System.out.print("try describeInstances again later ...");
                  Thread.sleep(2 * 60 * 1000);
              } else {
                  break;
              }
            }
        } catch (TeaUnretryableException ue) {
            // Print only for demonstration. Never ignore exceptions in production code.
            ue.printStackTrace();
            // Print error message
            System.out.println(ue.getMessage());
            // Print request details for debugging
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            // Print only for demonstration. Never ignore exceptions in production code.
            e.printStackTrace();
            // Print error code
            System.out.println(e.getCode());
            // Print error message (includes RequestId)
            System.out.println(e.getMessage());
            // Print detailed server-side error content
            System.out.println(e.getData());
        } catch (Exception e) {
            // Print only for demonstration. Never ignore exceptions in production code.
            e.printStackTrace();
        }
    }
}

Returned results

When a release is triggered, the output is:

result:instance:i-bp1i9c3qiv1qs6nc****,az:cn-hangzhou-i
instance:i-bp1i9c3qiv1qs6nc****-->lockReason:Recycling,vmStatus:Stopped
spot instance will be recycled immediately, instance id:i-bp1i9c3qiv1qs6nc****

Linux instance

# Get a metadata service token for authentication
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<metadata service token TTL>"`
# Check whether the spot instance is scheduled for interruption
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/instance/spot/termination-time

Windows instance

# Get a metadata service token for authentication
$token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<metadata service token TTL>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
# Check whether the spot instance is scheduled for interruption
Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/instance/spot/termination-time

Workflow

Procedure

1. Prepare the receiving channel

   Lightweight Message Queue

   1. Log on to the SMQ console.

   2. In the left-side navigation pane, choose Queue Model > Queues.

   3. In the top navigation bar, select a region.

   4. On the Queues page, click Create Queue.

   5. In the Create Queue panel, configure the following parameters and click OK:

      • Name: the name of the queue.

      • Maximum Message Length: the maximum length of the message that is sent to the queue.

      • Long Polling Period: the maximum duration for which long polling requests are held after the ReceiveMessage operation is called.

      • Visibility Timeout Period: the duration for which a message stays in the Inactive state after the message is received from the queue.

      • Message Retention Period: the maximum duration for which a message exists in the queue. After the specified retention period, the message is deleted regardless of whether the message is received.

      • Message Delay Period: the period after which all messages sent to the queue are consumed.

      • Enable Logging Feature: specifies whether to enable the logging feature.

      After the queue is created, it is displayed on the Queues page.

   Webhook

   Important

   Deploy the webhook service on an Internet-accessible server. Ensure inbound traffic is allowed on the response port.

   Java sample code:

   import org.springframework.http.ResponseEntity;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestBody;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   public class WebhookController {
       @PostMapping("/callback")
       public ResponseEntity<String> receiveWebhook(@RequestBody String payload) {
           // Process the payload, such as logging or executing business logic
           System.out.println("Received webhook payload: " + payload);
           // Return a success response
           return ResponseEntity.ok("Webhook received");
       }
   }

2. Create a subscription policy

   1. Log on to the Cloud Monitor console.

   2. In the left navigation pane, choose Event Hub > Event Subscriptions.

   3. On the Subscription Policies tab, click Create Subscription Policy.

   4. On the Create Subscription Policy page, configure the policy parameters.

      This example covers only parameters relevant to spot instance interruption events. For all parameters, see Manage event subscriptions (recommended).

      • Basic Information: Enter a Name and Description for the subscription policy.

      • Alert Subscription:

        • Subscription Type: Select System Events.

        • Subscription Scope:

        • Service: Select ECS.

        • Event Type: Select Status Notification.

        • Event Name: Select Spot Instance Interruption Notification.

        • Event Severity: Select Warning.

        • Application Groups, Event Content, and Event Resource: Leave these parameters empty to subscribe to all ECS system events that are named Spot Instance Interruption Notification across all application groups in your account.

      • Noise Reduction: Use the default.

      • Notification: The Custom Notification Method uses the default method.

      • Push and Integration: Click Add Channel. In the pop-up window, click Add Channel, select the channel prepared in Step 1 as the Target Type, and complete the remaining fields. For push channel details, see Manage push channels.

3. Simulate an interruption event

   Spot instance interruptions are passive, making it difficult to debug interruption-handling code. Use the Debug Event Subscription feature to simulate a spot instance interruption event.

   1. On the Subscription Policies tab, click Debug Event Subscription.

   2. In the Create Event Debug panel, set Service to ECS and Name to Spot Instance Interruption Notification.

      The system generates a debug payload in JSON format. Replace the resource-related placeholders with actual values for the spot instance to simulate.

      • Replace Alibaba Cloud account UID with your Alibaba Cloud account UID.

      • Replace <resource-id> and <instanceId> with the spot instance ID.

      • Replace <region ID> with the region ID of the spot instance.

        {
            "product": "ECS",
            "resourceId": "acs:ecs:cn-shanghai:Alibaba Cloud account UID:instance/<resource-id>",
            "level": "WARN",
            "instanceName": "instanceName",
            "regionId": "<region ID>",
            "groupId": "0",
            "name": "Instance:PreemptibleInstanceInterruption",
            "content": {
                "instanceId": "i-2zeg014dfo4y892z***",
                "instanceName": "wor***b73",
                "action": "delete"
            },
            "status": "Normal"
        }

   3. Click OK.

      The system displays the The operation is successful. message and sends a test alert notification based on your subscription policy.

4. Receive and view notifications

   Lightweight Message Queue

   1. Log on to the Simple Message Queue (formerly MNS) console. In the navigation pane on the left, click Queues.

   2. In the top navigation bar, select a region. On the Queues page, find your target queue and click Action > Send Messages.

   3. Optional: On the Send/Receive Messages Quick Experience page, click Edit Parameters of Receiving Messages. In the Edit Parameters of Receiving Messages panel, set Receive Times and Polling Period, and then click OK.

   4. On the Queue Send/Receive Messages Quick Experience page, click Receive Message. The message list appears in the Received Messages section.

   5. Optional: In the message list, find your target message, click Details in the Actions column, and view the message content in the Message Details dialog box.

   Webhook

   You can check the invocation logs and notification content in your deployed webhook application.