All Products
Search
Document Center

Enterprise Distributed Application Service:Manage instance groups for an application in an ECS cluster by calling API operations

Last Updated:Nov 20, 2023

This topic describes how to use Enterprise Distributed Application Service (EDAS) SDK for Java to manage instance groups for an application in an Elastic Compute Service (ECS) cluster by calling API operations.

Prerequisites

Before you call the API operations to manage instance groups for an application in an ECS cluster, make sure that the following prerequisites are met:

  • The ID of the region in which the application resides is obtained. For example, the region ID is cn-hangzhou.

  • The unique ID of the application version to be associated with an instance group is obtained before you create the instance group. You can call the ListHistoryDeployVersion operation to query the historical versions of the application and obtain the ID of the specified version. The version ID is specified by the PackageVersion.Id parameter.

  • The ID of the Elastic Compute Container (ECC) that corresponds to an ECS instance is obtained before you change the instance group for the ECS instance. You can call the ListApplicationEcc operation to query the ECC information for the application and obtain the ID of the ECC that corresponds to the specified ECS instance. The ID of the ECC is specified by the EccId parameter.

  • ECS instances are created. For example, the instance IDs of the ECS instances are i-bp13o01lzmbsvhsl**** and i-bp13o01lzmbsvhsl****.

  • An ECS cluster is created. For more information on how to create an ECS cluster, see Create an ECS cluster by calling an API operation.

    If you have created an ECS cluster, you can call the ListCluster operation to query ECS clusters and obtain the ID of the specified ECS cluster. The ID of the ECS cluster is specified by the ClusterId parameter. For example, the ID of the ECS cluster is 369d06d7-450b-4f3d-bf75-9536fcd9****.

Background information

You can group the ECS instances deployed for an application so that you can deploy different versions of the application in different groups. You can adjust traffic and perform a canary release of the application based on instance groups.

For example, you deploy the itemcenter application on 10 ECS instances and divide the instances into two groups: the default group and the beta group. The default group contains six instances and the beta group contains four instances. You can deploy different versions of the application in different instance groups.

Note
  • When an application is created in the EDAS console, EDAS creates the default group for the application. The default group cannot be deleted.

  • The default group is sufficient for day-to-day use by the application. If your application is deployed in multiple versions, you can create other groups to adjust traffic for or perform canary release of specific versions.

  • When you deploy an application, we recommend that you use the Java Virtual Machine (JVM), Tomcat, launch template, and Server Load Balancer (SLB) configurations of the application instance group.

Create an instance group for an application

The following code provides an example on how to create an instance group for an application in an ECS cluster.

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.InsertDeployGroupRequest;
import com.aliyuncs.edas.model.v20170801.InsertDeployGroupResponse;

public class InsertDeployGroup {

    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 the application resides. 
        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. 
        InsertDeployGroupRequest request = new InsertDeployGroupRequest();
        // The application for which you want to create an instance group. 
        request.setAppId("6bbc57a2-a017-4bec-b521-49a15bd3****");
        // The custom name of the instance group. The name can contain letters, digits, underscores (_), and periods (.). The name can be up to 64 characters in length. 
        request.setGroupName("Beta");
        // The version of the deployment package that is used to initialize the instance group. You can call the ListHistoryDeployVersion operation to query the version ID. 
        request.setInitPackageVersionId("3fc52328-8746-4422-a742-94e0cfc7****");

        try {
            InsertDeployGroupResponse response = client.getAcsResponse(request);
            System.out.println("GroupName=" + response.getDeployGroupEntity().getGroupName() + "\nId=" + response.getDeployGroupEntity().getId());
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }
    }
}

Sample response:

GroupName=Beta
Id=941be68c-4aac-48a1-88fe-c9ad1502****

Change the instance group to which an ECS instance belongs

Note

You can change the instance group for only one ECS instance at a time.

The following code provides an example on how to move an ECS instance of a specified application to another instance group in an ECS cluster.

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.ChangeDeployGroupRequest;
import com.aliyuncs.edas.model.v20170801.ChangeDeployGroupResponse;

public class ChangeDeployGroup {

    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 the application resides. 
        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. 
        ChangeDeployGroupRequest request = new ChangeDeployGroupRequest();
        // The application for which you want to move an ECS instance to another instance group. 
        request.setAppId("6bbc57a2-a017-4bec-b521-49a15bd3****");
        // The ID of the ECC that corresponds to the ECS instance for which you want to change the instance group. You can call the ListApplicationEcc operation to query the ECC information for the application and obtain the ID of the ECC. 
        request.setEccInfo("4009a824-ce33-4ba0-9ca2-346249a9****");
        // The name of the instance group to which you want to move the ECS instance. If you want to move the ECS instance to the default group, set this parameter to _DEFAULT_GROUP. 
        request.setGroupName("Beta");
        // Specifies whether to forcibly change the instance group if the deployment package version of the ECC is inconsistent with that of the instance group. A value of true indicates that the instance group is forcibly changed. A value of false indicates that the instance group is not forcibly changed. 
        request.setForceStatus(true);

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

Sample response:

Message=success
ChangeOrderId=369d06d7-450b-4f3d-bf75-9536fcd9****

Set JVM parameters for an instance group

The following code provides an example on how to set Java Virtual Machine (JVM) parameters for an instance group of an application in an ECS cluster.

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.UpdateJvmConfigurationRequest;
import com.aliyuncs.edas.model.v20170801.UpdateJvmConfigurationResponse;

public class UpdateJvmConfiguration {

    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 the application resides. 
        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. 
        UpdateJvmConfigurationRequest request = new UpdateJvmConfigurationRequest();
        // The application for which you want to set JVM parameters for an instance group. 
        request.setAppId("6bbc57a2-a017-4bec-b521-49a15bd3****");
        // The ID of the instance group for which you want to set JVM parameters. You can call the ListDeployGroup operation to query the ID of the instance group. 
        request.setGroupId("941be68c-4aac-48a1-88fe-c9ad1502****");
        // The custom parameters. 
        request.setOptions("-Dproperty=value");
        // The initial size of the heap memory. Unit: MB. 
        request.setMinHeapSize(500);
        // The size of the permanent heap memory. Unit: MB. 
        request.setMaxPermSize(500);
        // The maximum size of the heap memory. Unit: MB. 
        request.setMaxHeapSize(500);

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

Sample response:

Message=success

Set Tomcat parameters for an instance group

The following code provides an example on how to set Tomcat parameters for an instance group of an application in an ECS cluster.

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.UpdateContainerConfigurationRequest;
import com.aliyuncs.edas.model.v20170801.UpdateContainerConfigurationResponse;

public class UpdateContainerConfiguration {

    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 the application resides. 
        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. 
        UpdateContainerConfigurationRequest request = new UpdateContainerConfigurationRequest();
        // The application for which you want to set Tomcat parameters for an instance group. 
        request.setAppId("6bbc57a2-a017-4bec-b521-49a15bd3****");
        // The ID of the instance group for which you want to set Tomcat parameters. You can call the ListDeployGroup operation to query the ID of the instance group. 
        request.setGroupId("941be68c-4aac-48a1-88fe-c9ad1502****");
        // The context path of the Tomcat container. The path can be an empty string, null and the name of a WAR package, ROOT that indicates the root directory, or a non-empty custom string. 
        request.setContextPath("");
        // The port of the application. 
        request.setHttpPort(8080);
        // The maximum number of threads. 
        request.setMaxThreads(20);
        // The URI encoding scheme. Valid values: ISO-8859-1, GBK, GB2312, and UTF-8. 
        request.setURIEncoding("ISO-8859-1");
        // Specifies whether to use the encoding scheme specified in the request body for URI query parameters. A value of true indicates that this feature is enabled. A value of false indicates that the feature is disabled. 
        request.setUseBodyEncoding(true);

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

Sample response:

Message=success

Delete an instance group for an application

Note

You cannot delete an instance group that contains ECS instances. Before you delete an instance group, move all ECS instances in the instance group to other instance groups. For more information, see Change the instance group to which an ECS instance belongs.

The following code provides an example on how to delete an instance group for an application in an ECS cluster.

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.DeleteDeployGroupRequest;
import com.aliyuncs.edas.model.v20170801.DeleteDeployGroupResponse;

public class DeleteDeployGroup {

    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 the application resides. 
        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. 
        DeleteDeployGroupRequest request = new DeleteDeployGroupRequest();
        // The application for which you want to delete an instance group. 
        request.setAppId("6bbc57a2-a017-4bec-b521-49a15bd3****");
        // The name of the instance group to be deleted for the application. You can call the ListDeployGroup operation to query the ID of the instance group. 
        request.setGroupName("Beta");


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

Sample response:

Message=success
Data=1

Verify the result

Select a verification method based on the operation that you performed.

  • Create an instance group for an application

    You can call the ListDeployGroup operation to query the instance groups of the application. Check the GroupName parameter in the response and determine whether the instance group is created.

    Sample response that is returned after you call the ListDeployGroup operation:

    {
      "DeployGroupList": {
        "DeployGroup": [
          {
            "GroupName": "Beta",
            "AppId": "6bbc57a2-a017-4bec-b521-49a15bd3****",
            ......
            "GroupId": "941be68c-4aac-48a1-88fe-c9ad1502****"
          }
        ]
      },
      "Message": "success",
      "RequestId": "E8DC196C-F446-4465-A2D1-503728601680",
      "Code": 200
    }
  • Change the instance group to which an ECS instance belongs

    You can call the ListApplicationEcc operation to query the ECC information for the application. Check the GroupId and EccId parameters in the response and determine whether the instance group is changed for the ECS instance.

    Sample response that is returned after you call the ListApplicationEcc operation:

    {
      "EccInfoList": {
        "EccInfo": [
          {
            "EcuId": "8287bcf6-cde3-4377-8906-086d2c32****",
            "GroupId": "941be68c-4aac-48a1-88fe-c9ad1502****",
            "AppId": "6bbc57a2-a017-4bec-b521-49a15bd3****",
            "EccId": "02cdcdfa-f22b-45e6-8a0f-a738c766****",
            ......
          }
        ]
      },
      "Message": "success",
      "RequestId": "763D5FDF-3EC0-4F73-9FB5-A34E22BA9410",
      "Code": 200
    }
  • Set JVM parameters for an instance group

    You can call the GetJvmConfiguration operation to query the JVM settings of the instance group. Check the JVM information in the response and determine whether the JVM parameters are set.

    Sample response that is returned after you call the GetJvmConfiguration operation:

    {
      "Message": "success",
      "RequestId": "8EEB65B1-FD4E-4279-A221-09BFB34B9BBF",
      "JvmConfiguration": {
        "Options": "-Dproperty=value",
        "MaxPermSize": 500,
        "MaxHeapSize": 500,
        "MinHeapSize": 500
      },
      "Code": 200
    }
  • Set Tomcat parameters for an instance group

    You can call the GetContainerConfiguration operation to query the Tomcat settings of the instance group. Check the Tomcat information in the response and Determine whether the Tomcat parameters are set.

    Sample response that is returned after you call the GetContainerConfiguration operation:

    {
      "Message": "success",
      "RequestId": "B04B77C9-3978-4A3D-A628-72D385CB7DD3",
      "Code": 200,
      "ContainerConfiguration": {
        "HttpPort": 8080,
        "ContextPath": "ROOT",
        "UseBodyEncoding": true,
        "URIEncoding": "ISO-8859-1",
        "MaxThreads": 20
      }
    }
  • Delete an instance group for an application

    You can call the ListDeployGroup operation to query the instance groups of the application. Check the GroupName parameter in the response and determine whether the instance group is deleted.

    Sample response that is returned after you call the ListDeployGroup operation:

    {
      "DeployGroupList": {
        "DeployGroup": [
          {
            "GroupName": "_DEFAULT_GROUP",
            "AppId": "6bbc57a2-a017-4bec-b521-49a15bd3****",
            ......
            "GroupId": "941be68c-4aac-48a1-88fe-c9ad1502****"
          }
        ]
      },
      "Message": "success",
      "RequestId": "E8DC196C-F446-4465-A2D1-503728601680",
      "Code": 200
    }