Detecting and responding to interruption events

Build the API request

Before you build the request object, refer to the API documentation for parameter information.

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

Initiate the call

When calling an API operation, you can set runtime parameters, such as timeout and proxy configurations. For more information, see Advanced configurations.

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

Handle exceptions

The SDK for Java classifies exceptions into two main types: TeaUnretryableException and TeaException.

• TeaUnretryableException: This exception is typically caused by network issues and is thrown after the maximum number of retries is reached.

• TeaException: This exception is primarily for service-related errors.

To ensure system robustness and stability, implement proper exception handling, such as propagating exceptions, logging, and attempting recovery.

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. Make sure the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is set in your runtime environment.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is set in your runtime environment.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                // For endpoints, see 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.
            // Set the IDs of one or more ECS instances 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 parameters.
            RuntimeOptions runtime = new RuntimeOptions();
            while (!instanceIds.isEmpty()) {
              // Call the DescribeInstances API operation.
              DescribeInstancesResponse response = client.describeInstancesWithOptions(request, runtime);
              // Obtain the instance-related response.
              DescribeInstancesResponseBody responseBody = response.getBody();
              DescribeInstancesResponseBody.DescribeInstancesResponseBodyInstances instanceList = responseBody.getInstances();
              // Obtain instance information and check the value of lockReason.
              if (instanceList != null && instanceList.getInstance()!= null && !instanceList.getInstance().isEmpty()) {
                  for (DescribeInstancesResponseBody.DescribeInstancesResponseBodyInstancesInstance instance : instanceList.getInstance()) {
                      // Output the ID and zone of the queried instance.
                      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, output its ID and lock type.
                                  System.out.println("instance:" + instance.getInstanceId() + "-->lockReason:" + lockReason.getLockReason() + ",vmStatus:" + instance.getStatus());
                                  if ("Recycling".equals(lockReason.getLockReason())) {
                                      // Output the ID of the instance that is about to be reclaimed.
                                      System.out.println("spot instance will be recycled immediately, instance id:" + instance.getInstanceId());
                                      instanceIds.remove(instance.getInstanceId());
                                  }
                              }
                          }

                      }
                  }
                  // If the spot instance is not yet locked, query again every 2 minutes.
                  System.out.print("try describeInstances again later ...");
                  Thread.sleep(2 * 60 * 1000);
              } else {
                  break;
              }
            }
        } catch (TeaUnretryableException ue) {
            // This is for demonstration only. In a production environment, handle exceptions with caution and do not ignore them.
            ue.printStackTrace();
            // Print the error message.
            System.out.println(ue.getMessage());
            // Print the last request to find information about the failed request.
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            // This is for demonstration only. In a production environment, handle exceptions with caution and do not ignore them.
            e.printStackTrace();
            // Print the error code.
            System.out.println(e.getCode());
            // Print the error message, which includes the RequestId.
            System.out.println(e.getMessage());
            // Print the detailed error information returned by the server.
            System.out.println(e.getData());
        } catch (Exception e) {
            // This is for demonstration only. In a production environment, handle exceptions with caution and do not ignore them.
            e.printStackTrace();
        }
    }
}

Response

The following output is returned when a reclamation is triggered:

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

# Obtain a token for accessing the metadata server for authentication.
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<token-validity-in-seconds>"`
# Query whether the spot instance is scheduled for interruption and reclamation.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/instance/spot/termination-time

Windows instance

# Obtain a token for accessing the metadata server for authentication.
$token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<token-validity-in-seconds>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
# Query whether the spot instance is scheduled for interruption and reclamation.
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 a receiving channel

   Simple Message Queue (SMQ)

   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

   The webhook service must be deployed on a server with public network access. Ensure that the server's firewall allows access to the corresponding port.

   The following is an example in Java:

   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, for example, by logging it or handling 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 CloudMonitor console.

   2. In the left-side navigation pane, choose Event Center > Event Subscription.

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

   4. On the Create Subscription Policy page, set the parameters for the policy.

      This example describes only the parameters required for subscribing to spot instance interruption events. For more information about the 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 Instance:PreemptibleInstanceInterruption.

        • Event Severity: Select Warning.

        • Application Groups, Event Content, and Event resources: Leave these parameters empty to subscribe to the Instance:PreemptibleInstanceInterruption system event for all ECS instances in all application groups under your account.

      • Combined Noise Reduction: Use the default settings.

      • Notification: For Custom Notification Method, use the default notification method.

      • Push and Integration: Click Add Channel. In the dialog box that appears, click Increase Channels. For Target type, select the channel prepared in Step 1, and fill in the other parameters as prompted. For more information about push channels, see Manage push channels.

3. Simulate an interruption event

   Spot instance interruptions are passive events, which can make it difficult to effectively debug your interruption handler. You can use the Debug Event Subscription feature to simulate a spot instance interruption event.

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

   2. In the Create Event Test panel, set Service to ECS and Name to Instance:PreemptibleInstanceInterruption.

      The system automatically generates debugging content in JSON format. You must replace the placeholder resource information in the JSON file with the details of the spot instance you are using for the simulation.

      • Replace the Alibaba Cloud account UID variable with the UID of your Alibaba Cloud account.

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

      • Replace <region-ID> with the region ID of your 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 an The operation is successful. message. CloudMonitor automatically sends a test alert notification using the method specified in the subscription policy.

4. Receive and view the notification

   Simple Message Queue (SMQ)

   1. Log on to the Simple Message Queue (SMQ) console and click Queues in the left-side navigation pane.

   2. In the top menu bar, select a region. On the Queues page, find the target queue, and in the Action column, choose Send Messages.

   3. (Optional) On the Quick Experience page, click Edit Parameters of Receiving Messages. In the Edit Parameters of Receiving Messages panel, configure Receive Times and Polling Period, then click OK.

   4. On the Send and Receive Messages - Quick Experience page, click the Receive Message button. The message list for the queue is displayed in the Received Messages area.

   5. (Optional) In the message list, find the target message and click Details in the Actions column. In the Message Details dialog box, view the message content and other information.

   Webhook

   In your deployed webhook application, check the invocation status and notification content.