Enterprise Distributed Application Service:Perform a canary release for an application in an ECS cluster by calling an API operation

How a canary release works

A canary release through the EDAS API follows three stages:

1. Deploy to the canary group -- Call DeployApplication to deploy the new version to a specific instance group with a traffic control strategy.

2. Get the phase IDs -- Call GetChangeOrderInfo to retrieve the PipelineId for each release phase.

3. Trigger the remaining phases -- Call ContinuePipeline with each subsequent PipelineId to advance through the remaining phases.

DeployApplication           GetChangeOrderInfo           ContinuePipeline
(canary group + traffic) -> (get pipeline IDs)       -> (trigger next phase) -> ... -> Done

Prerequisites

Before you begin, make sure that you have:

• EDAS SDK for Java installed. For more information, see "Use EDAS SDK for Java to call EDAS API"

• The region ID where the application runs. In this example: cn-hangzhou

• A microservice namespace. For more information, see Create a microservice namespace. If a namespace already exists, call ListUserDefineRegion and get the namespace ID from the RegionId parameter

• An application created in an ECS cluster. For more information, see Create an application in an ECS cluster by calling an API operation. If the application already exists, call ListApplication and get the application ID from the AppId parameter. In this example: 6bbc57a2-a017-4bec-b521-49a15bd3****

• The JAR or WAR deployment package uploaded to a destination address. In this example, the Object Storage Service (OSS) address is https:doc***.oss-cn-hangzhou.aliyuncs.com/sc-****-D-0.0.1-SNAPSHOT.jar

• The instance group ID for the canary release. Call ListDeployGroup and get the group ID from the GroupId parameter. In this example: 941be68c-4aac-48a1-88fe-c9ad1502****

• (HSF applications only) The EDAS Container version. Call ListBuildPack and get the version from the ConfigId parameter. In this example: 57

Step 1: Deploy the application to the canary group

Call the DeployApplication operation to start a canary release. The following table describes the key parameters.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.edas.model.v20170801.DeployApplicationRequest;
import com.aliyuncs.edas.model.v20170801.DeployApplicationResponse;

public class DeployApplication {

    public static void main(String[] args)  {
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations.
        // Using these credentials to perform operations in EDAS is a high-risk operation.
        // We recommend that you use a RAM user to call API operations.
        // To create a RAM user, log on to the RAM console.
        // To prevent key leaks, do not save your AccessKey ID and AccessKey secret in the code.
        // Read the AccessKey pair from environment variables.
        String aliyun_user_ak = System.getenv("ACCESS_KEY_ID");
        String aliyun_user_sk = System.getenv("ACCESS_KEY_SECRET");

        String region_id = "cn-hangzhou";

        DefaultProfile defaultProfile = DefaultProfile.getProfile(region_id, aliyun_user_ak, aliyun_user_sk);
        DefaultAcsClient client = new DefaultAcsClient(defaultProfile);

        DeployApplicationRequest request = new DeployApplicationRequest();
        // Application ID
        request.setAppId("6bbc57a2-a017-4bec-b521-49a15bd3****");
        // Deployment description
        request.setDesc("Canary release");
        // Deployment method: url
        request.setDeployType("url");
        // URL of the deployment package (JAR or WAR) in OSS
        request.setWarUrl("https:doc***.oss-cn-hangzhou.aliyuncs.com/sc-****-D-0.0.1-SNAPSHOT.jar");
        // Package version (timestamp recommended, up to 64 characters)
        request.setPackageVersion("20210417.173831");
        // Enable canary release
        request.setGray(true);
        // Route 50% of traffic to the canary group
        request.setTrafficControlStrategy("{\"http\":{\"rules\":[{\"conditionType\":\"percent\",\"percent\":50}]}}");
        // Instance group ID for the canary release
        request.setGroupId("941be68c-4aac-48a1-88fe-c9ad1502****");
        // Release to remaining instances in 2 phases
        request.setBatch(2);
        // Manual phased release (0 = automatic, 1 = manual)
        request.setReleaseType((long) 1);
        // Wait 1 minute between phases (range: 0-5)
        request.setBatchWaitTime(1);
        // Application component: 5 = OpenJDK 1.8.x
        request.setComponentIds("5");

        try {
            DeployApplicationResponse response = client.getAcsResponse(request);
            System.out.println("Message=" + response.getMessage() + "\nChangeOrderId=" + response.getChangeOrderId());
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }
    }
}

Message=success
ChangeOrderId=4a3329de-2495-4c51-be33-f69ff264****

Step 2: Get the phase IDs

Call the GetChangeOrderInfo operation with the ChangeOrderId from Step 1 to retrieve the PipelineId for each release phase.

Sample response (partial):

{
  "Message": "success",
  "RequestId": "0EB98A7D-50CE-4F5F-855D-70BAF61DFB38",
  "Code": 200,
  "changeOrderInfo": {
    "Status": 8,
    "Desc": "Canary release",
    "PipelineInfoList": {
      "PipelineInfo": [
        {
          "PipelineId": "09e7d9aa-e79d-49ef-99b9-5405532d****"
        },
        {
          "PipelineId": "1ea53844-2c60-46f1-b46d-df3b34d0****"
        },
        {
          "PipelineId": "d99da075-b87d-4fe7-bbb6-ae1c6c26****"
        }
      ]
    }
  }
}

In this example, three phase IDs are returned because the release has three stages:

A Status value of 8 means the release is waiting for you to manually trigger the next phase.

Step 3: Trigger the remaining phases

Before you trigger the remaining phases, verify the update on the canary group instances. If the verification is successful, call the ContinuePipeline operation with the second PipelineId to release the application to the first batch of remaining instances.

Sample response:

{
  "Message": "success",
  "RequestId": "B8ECF6F7-672D-40E9-91DD-1C33F06D4FD8",
  "Code": 200
}

After the first batch completes, call ContinuePipeline again with the third PipelineId to release to the second batch.

Sample response:

{
  "Message": "success",
  "RequestId": "7BB4F043-7C28-4A0E-B6A5-D4023EB24388",
  "Code": 200
}

Verify the result

Call the GetChangeOrderInfo operation again to check the release status. The changeOrderInfo.Status field indicates the current state:

A Status value of 2 means the canary release completed successfully across all phases.

Sample response (partial):

{
  "Message": "success",
  "RequestId": "0EB98A7D-50CE-4F5F-855D-70BAF61DFB38",
  "Code": 200,
  "changeOrderInfo": {
    "Status": 2,
    "Desc": "Canary release",
    "PipelineInfoList": {
      "PipelineInfo": [
        ...
      ]
    }
  }
}

If the status is 3 (Failed) or 10 (Failed due to a system exception), check the change order details in the PipelineInfoList to identify which phase failed. You can then fix the issue and start a new canary release.

Use automatic phased release (recommended)

The example above uses manual phased release (ReleaseType = 1), which requires you to call ContinuePipeline for each phase. For production environments, automatic phased release is recommended. Set the following parameters:

With automatic phased release, you only need to call DeployApplication and then monitor the status with GetChangeOrderInfo. The system advances through each phase automatically after the specified wait time.

Related API operations