This topic describes how to use Enterprise Distributed Application Service (EDAS) SDK for Java to release an application in canary mode in an Elastic Compute Service (ECS) cluster by calling an API operation.

Prerequisites

Before you call the API operation to release an application in canary mode, make sure that the following prerequisites are met:
  • The ID of the region in which you want to release an application in canary mode is obtained. For example, the region ID is cn-hangzhou.
  • A microservice namespace is created. For example, a microservice namespace with the ID of cn-hangzhou:doc is created. For more information, see Create a namespace.

    If a microservice namespace already exists, you can call the ListUserDefineRegion operation to query custom microservice namespace and obtain the value of the RegionId parameter for the microservice namespace that you want to use. For example, the value is cn-hangzhou:doc.

  • An application is created in an ECS cluster. For more information, see Create an application in an ECS cluster by calling an API operation.

    If you have created an application, you can call the ListApplication operation to query applications and obtain the ID of the specified application. The application ID is specified by the APPId parameter. For example, the application ID is 6bbc57a2-a017-4bec-b521-49a15bd3****.

  • The JAR package or WAR package that is used to deploy the application is uploaded to the destination storage system. For example, the path of the JAR package in Object Storage Service (OSS) is https:doc***.oss-cn-hangzhou.aliyuncs.com/sc-****-D-0.0.1-SNAPSHOT.jar.
  • The ID of the instance group that is used to perform a canary release is obtained. You can call the ListDeployGroup operation to query instance groups and obtain the ID of the specified instance group. The ID of the instance group is specified by the GroupId parameter. For example, the ID of the instance group is 941be68c-4aac-48a1-88fe-c9ad1502****.
  • The ID of the container version to be used is obtained if you want to release a High-Speed Service Framework (HSF) application. You can call the ListBuildPack operation to query container versions and obtain the ID of the specified container version. The ID of the container version is specified by the ConfigId parameter. For example, the ID of the container version is 57.

Background information

After you release an application to the instance group that is used to perform a canary release, you must manually trigger the release of the application to the remaining ECS instances. The remaining ECS instances refer to the ECS instances of the application that do not belong to the instance group used for the canary release. You can verify the application on a small number of ECS instances before you trigger the release of the application to the remaining ECS instances. After you verify the application, trigger the release of the application to the remaining ECS instances so that the application is updated on all related ECS instances.

When you release the application to the remaining ECS instances, we recommend that you perform an automatic phased release. If you perform a manual phased release, you must call the ContinuePipeline operation to manually trigger phases during the release process.

Release an application in canary mode

  1. Run the code to release the application in canary mode.

    The following code provides an example on how to release an application in canary mode in an ECS cluster. The code does not contain settings of advanced parameters such as environment variables. For more information about how to set these parameters, see DeployApplication.

    Note You can use the code to release a Spring Cloud or Dubbo application in canary mode. To release an HSF application in canary mode, you must add the following EDAS Container information to the code:
    // The build package number of EDAS Container. This parameter is required to release an HSF application in canary mode. You can call the ListBuildPack operation to query the build package number. The build package number is specified by the ConfigId parameter. 
    request.setBuildPackId(57);
    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 ID of your Alibaba Cloud account or a RAM user within the Alibaba Cloud account. 
            String aliyun_user_ak = "<yourAccessKeyId>";
            // The AccessKey secret of your Alibaba Cloud account or a RAM user within the account. 
            String aliyun_user_sk = "<yourAccessKeySecret>";
            // The ID of the region in which you want to release the application. 
            String region_id = "cn-hangzhou";
    
            DefaultProfile defaultProfile = DefaultProfile.getProfile(region_id, aliyun_user_ak, aliyun_user_sk);
            DefaultAcsClient client = new DefaultAcsClient(defaultProfile);
    
            // Create an API request and set the parameters. 
            DeployApplicationRequest request = new DeployApplicationRequest();
            // The ID of the application. 
            request.setAppId("6bbc57a2-a017-4bec-b521-49a15bd3****");
            // The description of the application. 
            request.setDesc("Canary release");
            // The type of method to deploy the application. You can set this parameter only to url. 
            request.setDeployType("url");
            // The URL of the JAR package or WAR package that is used to deploy the application. We recommend that you store the deployment package of the application in OSS and set this parameter to the path of the deployment package in OSS. 
            request.setWarUrl("https:doc***.oss-cn-hangzhou.aliyuncs.com/sc-****-D-0.0.1-SNAPSHOT.jar");
            // The version of the deployment package. The value can be up to 64 characters in length. We recommend that you use a timestamp. 
            request.setPackageVersion("20210417.173831");
            // Specifies whether to release the application in canary mode. A value of true indicates the application is released in canary mode. A value of false indicates that the application is not released in canary mode. To release the application in canary mode, you must specify the ID of the instance group that is used to preform a canary release. The number of phases to release the application to the remaining ECS instances is specified by the Batch parameter. 
            request.setGray(true);
            // The traffic adjustment policy that is used for the canary release. The sample policy indicates that 50% of the traffic is forwarded to the instance group that is used to perform the canary release. 
            request.setTrafficControlStrategy("{\"http\":{\"rules\":[{\"conditionType\":\"percent\",\"percent\":50}]}}");
            // The ID of the group to which the application is deployed. If you want to deploy the application to all instance groups, set the parameter to all. To release the application in canary mode, you must specify the ID of the instance group that is used to preform a canary release. 
            // You can call the ListDeployGroup operation to obtain the ID of the specified instance group. 
            request.setGroupId("941be68c-4aac-48a1-88fe-c9ad1502****");
            // The number of phases in which the application is released to the specified instance group. If you set the value to a number greater than 1, a phased release is performed. 
            request.setBatch(2);
            // The mode of the phased release. A value of 0 indicates that the next phase is automatically triggered. A value of 1 indicates that the next phase must be manually triggered. We recommend that you set the parameter to 0 to perform an automatic phased release. 
            request.setReleaseType((long) 1);
            // The time that the system waits between two phases. Unit: minutes. By default, the value is 0. This means no wait time between phases. You can set the parameter to a number from 0 to 5. 
            request.setBatchWaitTime(1);
            // The ID of the component that is used by the application. This parameter is required if the application runs in Apache Tomcat or in a standard Java application runtime environment. The Apache Tomcat application runtime environment is applicable to Dubbo applications that are deployed by using WAR packages. A standard Java application runtime environment is applicable to Spring Boot or Spring Cloud applications that are deployed by using JAR packages. 
            // A value of 4 indicates Apache Tomcat 7.0.91. A value of 7 indicates Apache Tomcat 8.5.42. A value of 5 indicates OpenJDK 1.8.x. A value of 6 indicates OpenJDK 1.7.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();
            }
        }
    }
    Sample response:
    Message=success
    ChangeOrderId=4a3329de-2495-4c51-be33-f69ff264****
  2. Call the GetChangeOrderInfo operation to obtain the values of the PipelineId parameter. This parameter indicates the pipeline ID of each phase.
    Sample response that is returned after you call the GetChangeOrderInfo operation:
    {
      "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****"
              ......
              // The sample response is incomplete and is only for reference. 
    Note In this example, after the application is released to the instance group that is used for the canary release, the application is released to the remaining ECS instances in two phases. After the application is released to the instance group that is used for the canary release, you must manually trigger the release of the application to the remaining ECS instances. Three pipeline IDs are returned after you call the GetChangeOrderInfo operation. The second pipeline ID indicates the phase that you need to manually trigger after the application is released to the instance group that is used for the canary release. The third pipeline ID indicates the phase that you need to manually trigger after the first phase of the manual phased release is complete.
  3. Call the ContinuePipeline operation to manually trigger the first phase of the manual phased release after the application is released to the instance group that is used for the canary release.
    Sample response:
    {
      "Message": "success",
      "RequestId": "B8ECF6F7-672D-40E9-91DD-1C33F06D4FD8",
      "Code": 200
    }
  4. Call the ContinuePipeline operation to manually trigger the second phase of the manual phased release.
    Sample response:
    {
      "Message": "success",
      "RequestId": "7BB4F043-7C28-4A0E-B6A5-D4023EB24388",
      "Code": 200
    }
    Note In this example, after the application is released to the instance group that is used for the canary release, the application is released to the remaining ECS instances in two phases. During this phased release to the remaining ECS instances, you need to trigger only phase. If the application is to be released to the remaining ECS instances in more than two phases, repeat this step by selecting the correct pipeline ID to trigger phases one by one.

Verify the result

After you release an application in canary mode, you can call the GetChangeOrderInfo operation to view the change details and the change status of the application. For more information, see GetChangeOrderInfo.

Sample response that is returned after you call the GetChangeOrderInfo operation:
{
  "Message": "success",
  "RequestId": "0EB98A7D-50CE-4F5F-855D-70BAF61DFB38",
  "Code": 200,
  "changeOrderInfo": {
    "Status": 2,
    "Desc": "Canary release",
    "PipelineInfoList": {
      "PipelineInfo": [
                {
                   ......
                   // The sample response is incomplete and is only for reference. 
You can view the value of the changeOrderInfo.Status parameter to check whether the application is released in canary mode. Valid values of the changeOrderInfo.Status parameter:
  • 0: ready
  • 1: in progress
  • 2: successful
  • 3: failed
  • 6: terminated
  • 8: wait for manual confirmation to trigger the next phase during a manual phased release
  • 9: wait to trigger the next phase during an automatic phased release
  • 10: failed due to a system exception