You can use toolkit-maven-plugin to deploy Spring Cloud, Dubbo, and High-Speed Service Framework (HSF) applications to Elastic Compute Service (ECS) clusters.

Enable automatic deployment of applications

  1. Add the following plug-in dependency to the pom.xml file of your packaged project:
    <build>
    <plugins>
    <plugin>
         <groupId>com.alibaba.cloud</groupId>
         <artifactId>toolkit-maven-plugin</artifactId>
         <version>1.1.5</version>
    </plugin>
    </plugins>
    </build>                       
  2. Create a file named .edas_config.yaml in the root directory of the packaged project. If the packaged project is a Maven submodule, create the file in the submodule directory.
    Note For more information about how to deploy a multi-module project, see Deploy multi-module projects.
    env:
         region_id: cn-beijing
    app:
         app_id: eb20****-e6ee-4f6d-a36f-5f6a5455****                        

    Among the preceding configuration items, region_id indicates the region ID of the application instance, and app_id indicates the ID of the application. The values of the two items are sample values. Replace them with the actual values. For more information about the configuration parameters, see More configuration items.

    To obtain the values of these configuration items, perform the following steps:

    1. Log on to the Enterprise Distributed Application Service (EDAS) console.
    2. In the left-side navigation pane, choose Application Management > Applications and select a namespace.
    3. On the Applications page, select an ECS cluster type and click the name of the application that you want to deploy.
    4. On the Basic Information page of the application, click Deploy Application.
    5. Select a deployment mode. Select Regular Release (Single-batch/Multi-batch) or Canary Release (Phased), and then click Start Deployment.
    6. In the lower part of the application deployment page, click Generate Maven Plug-in Configuration to obtain the parameter values.
  3. Create an account file.

    Create an account file in the YAML format and configure your AccessKey ID and AccessKey secret. You can obtain the AccessKey ID and AccessKey secret on the User Management page in the Alibaba Cloud Management Console. We recommend that you use a RAM user that has been granted the application management permissions. This helps you control the permissions on applications and improves the application security.

    Example:

    access_key_id: abc
    access_key_secret: 1234567890                        
    Note In the preceding configuration, abc and 1234567890 are sample values. Replace them with your actual AccessKey ID and AccessKey secret. In this configuration, the AccessKey ID and AccessKey secret are only used to generate request signatures and not used for other purposes, such as network transfers.
  4. Go to the root directory of your project or go to the submodule directory if multiple Maven modules exist, and run the following packaging command:
    mvn clean package toolkit:deploy -Daccess_key_file={Account file path}
                            
    • toolkit:deploy: Use toolkit-maven-plugin to deploy your application after your application is packaged. The application is deployed only when this parameter is configured.
    • access_key_file: the account file of the Alibaba Cloud account.
      Note For more information about the methods to specify an AccessKey pair, see Account configurations and priorities.

    After you run the preceding command for packaging, the following message appears. This indicates that you have deployed the application by using toolkit-maven-plugin.

    Deploy an application to the file path specified by using -Djar_path.

    mvn toolkit:deploy -Daccess_key_file={Account file path} -Djar_path=target/demo.jar
                            
    Notice You can also configure the account file path in env. For more information, see More configuration items. The configuration by using -Djar_path takes precedence over that by using env.

More configuration items

Configuration items for deploying applications are classified into the following types:

  • Basic environment (env)
  • Application configuration (app)
  • Storage configuration (oss)

The following table lists the supported configuration items.

Configuration item Parameter Required/Example Description
env region_id Yes The ID of the region where the application is to be deployed.
jar_path target/demo.jar The path of the package that is used to deploy the application. You can specify an absolute or a relative path. If you specify the path, you do not need to package the application file in Maven.
endpoint No The gateway point of presence (POP) connected to the gateway for the application that is deployed on Apsara Stack.
app app_id Yes The ID of the application.
release_type 1 The release type of the application. Valid values:
  • 0: automatic phased release
  • 1: manual phased release
package_version No The version of the deployment package. By default, the value is a string that consists of the pom.xml file version and the time when the current instance is created, for example, 1.0 (2018-09-27 19:00:00).
desc No The description about the application deployment.
group_id No The ID of the group to which the application is deployed. By default, the application belongs to all the groups.
batch No The number of deployment batches. The default value is 1 and the maximum value is 5.
batch_wait_time No The waiting time in minutes between deployment batches. The default value is 0.
stage_timeout No The timeout period in minutes for each change stage. The default value is 5. If you specify the batch_wait_time value, the specified batch_wait_time value is automatically added to the value of the stage_timeout parameter. When the application is running, the plug-in automatically exits if a stage waits for a time longer than this threshold value.
oss region_id No The ID of the region where the bucket is deployed. The default value is the ID of the region where the application is to be deployed.
bucket No The name of the bucket. By default, the free Object Storage Service (OSS) bucket that is provided by Enterprise Distributed Application Service (EDAS) is used. If you use OSS for storage, you must specify the bucket parameter. Otherwise, the free OSS bucket that is automatically allocated by EDAS is used.
key No The custom path that is used to upload the application package to OSS. By default, the free OSS bucket that is provided by EDAS is used. If you use the specified OSS bucket, you can use this parameter to specify the storage path of the application package. You can also use the following variables to specify the path in a parameterized way: {region_id}, {app_id}, and {version}. For example, you can set the path to pkgs/petstore/{version}/store.war. By default, the value follows the {region_id}/{app_id}/{version} format.
access_key_id No The AccessKey ID that is used to upload the application package to OSS.
access_key_secret No The AccessKey secret that is used to upload the application package to OSS.
use_vpc_endpoint true By default, the plug-in uses the public endpoint of the specified OSS bucket to upload your package. To use the internal endpoint of the specified OSS bucket to upload your package, set the value to true.

Configuration example 1: Specify a group and a deployment package version

Assume that you want to deploy the application eb20dc8a-e6ee-4f6d-a36f-5f6a545**** to the group 06923bb9-8c5f-4508-94d8-517b692f**** in the China (Beijing) region. The version of the deployment package is 1.2. In this case, you can use the following configuration:

env:
  region_id: cn-beijing
app:
  app_id: eb20dc8a-e6ee-4f6d-a36f-5f6a5455****
  package_version: 1.2
  group_id: 06923bb9-8c5f-4508-94d8-517b692f****            

Configuration example 2: Specify an OSS bucket

Assume you want to deploy the application eb20dc8a-e6ee-4f6d-a36f-5f6a5455**** and upload the deployment package to your own bucket named release-pkg in the China (Beijing) region. The file name of the OSS object is my.war, the ID of the OSS account is ABC, and the key of the OSS account is 1234567890. In this case, you can use the following configuration:

env:
  region_id: cn-beijing
app:
  app_id: eb20dc8a-e6ee-4f6d-a36f-5f6a5455****
oss:
  region_id: cn-beijing
  bucket: release-pkg
  key: my.war  
  access_key_id: ABC
  access_key_secret: 1234567890            

Specify a configuration file

  • If no configuration file is specified, the plug-in uses the .edas_config.yaml file in the root directory of the packaged project by default. If the packaged project is a submodule of the Maven project, the default configuration file is located in the root directory of the submodule, instead of the root directory of the entire Maven project.
  • You can also specify a configuration file by setting the -Dedas_config=xxx parameter.
  • If the default configuration file exists and another configuration file is specified by using the preceding parameter, the plug-in uses the latter.

Account configurations and priorities

When you use the plug-in to deploy applications, you must provide the AccessKey ID and AccessKey secret of your Alibaba Cloud account. The plug-in supports multiple configuration methods. If duplicate configurations exist, the configuration method that has a higher priority overrides the configuration method that has a lower priority. The following list describes the configuration methods that are sorted by priority in descending order:

  • Specify an AccessKey ID and AccessKey secret in a command-line interface (CLI): You can specify an AccessKey ID and AccessKey secret in one of the following ways:
    • If you use a Maven command to package the project, use -Daccess_key_id=xx -Daccess_key_secret=xx to configure the AccessKey ID and AccessKey secret.
    • If you configure the plug-in in the pom.xml file, use the following sample code to configure the AccessKey ID and AccessKey secret:
      <plugin>
         <groupId>com.alibaba.cloud</groupId>
         <artifactId>toolkit-maven-plugin</artifactId>
         <version>1.0.3</version>
      <configuration>
        <accessKeyId>abc</accessKeyId>
        <accessKeySecret>1234567890</accessKeySecret>
      </configuration>
      </plugin>                            
  • Specify an account file in a CLI (recommended): If you use a Maven command to package the project, specify an account file in the YAML format by using -Daccess_key_file={Account file path}. For example, you can use the following configuration:
    access_key_id: abc
    access_key_secret: 1234567890                    
  • Use the default Alibaba Cloud account file: If you do not specify an account by using one of the preceding ways, the plug-in uses the Alibaba Cloud account that you previously set to deploy the application.

    aliyuncli: Assume that you have used the latest Alibaba Cloud CLI and configured your Alibaba Cloud account. In this case, Alibaba Cloud generates the .aliyuncli directory in the current home directory and creates the credentials file in the .aliyuncli directory to store your account information. Assume that the macOS system is used and the system user is jack. In this case, the following information is stored in the /Users/jack/.aliyuncli/credentials file:

    [default]
    aliyun_access_key_secret = 1234567890
    aliyun_access_key_id = abc                    

The plug-in uses the account that is specified by using this account file to deploy the application.

  • aliyun: Assume that you have used a legacy Alibaba Cloud CLI and configured the Alibaba Cloud account. In this case, Alibaba Cloud generates the .aliyun directory in the current home directory and creates the config.json file in the .aliyun directory. Assume that the macOS system is used and the system user is jack. In this case, the following information is stored in the /Users/jack/.aliyun/config.json file:
    {
        "current": "",
        "profiles": [{
            "name": "default",
            "mode": "AK",
            "access_key_id": "",
            "access_key_secret": "",
            "sts_token": "",
            "ram_role_name": "",
            "ram_role_arn": "",
            "ram_session_name": "",
            "private_key": "",
            "key_pair_name": "",
            "expired_seconds": 0,
            "verified": "",
            "region_id": "",
            "output_format": "json",
            "language": "en",
            "site": "",
            "retry_timeout": 0,
            "retry_count": 0
        }, {
            "name": "",
            "mode": "AK",
            "access_key_id": "abc",
            "access_key_secret": "xxx",
            "sts_token": "",
            "ram_role_name": "",
            "ram_role_arn": "",
            "ram_session_name": "",
            "private_key": "",
            "key_pair_name": "",
            "expired_seconds": 0,
            "verified": "",
            "region_id": "cn-hangzhou",
            "output_format": "json",
            "language": "en",
            "site": "",
            "retry_timeout": 0,
            "retry_count": 0
        }],
        "meta_path": ""
    }                    
  • System environment variables: Then, the plug-in attempts to retrieve the AccessKey ID and AccessKey secret from system environment variables. This indicates that the plug-in retrieves the values from System.getenv("access_key_id") and System.getenv("access_key_secret") in your Java code.

Deploy multi-module projects

A multi-module project is a common project. You can use the Maven plug-in to deploy your multi-module project in one of the following ways:

  • Method 1: Run the packaging and deployment commands in your parent project.

    To use this method, use toolkit-maven-plugin 1.0.3 or later.

    When you run the toolkit:deploy command in your parent project, add the -Ddeploy_artifacts parameter to specify the artifact ID of the submodule that you want to deploy. To deploy multiple submodules, separate them with commas (,).

    The following example shows the submodules of the CarShop project:

    carshop
       itemcenter-api
       itemcenter
    
       detail

    To deploy the itemcenter and detail submodules, run the following command in the carshop directory:

    mvn clean package toolkit:deploy -Ddeploy_artifacts=itemcenter,detail

    By default, the plug-in separately deploys the corresponding applications by using the .edas_config.yaml file of the itemcenter and detail submodules. You can also add the -Dedas_config parameter to specify a configuration file. For more information, see Specify a configuration file.

  • Method 2: Run the packaging and deployment commands in a submodule. This method supports toolkit-maven-plugin of all versions.

    Run the install command in your parent project to install the dependencies of the submodule to your Maven local repository. Then, go to the directory of the submodule that you want to deploy and run the toolkit:deploy command.

Apsara Stack support

The plug-in can be used in Apsara Stack Enterprise V3.8.0 or later. Before you use the plug-in, configure an EDAS endpoint for the plug-in. For more information, see More configuration items. To obtain an endpoint, contact EDAS technical support.