All Products
Search
Document Center

Use toolkit-maven-plugin to automatically deploy applications

Last Updated: Feb 01, 2019

Previously, EDAS applications had to be deployed by following the step-by-step instructions in the console.To improve the developer experience, toolkit-maven-plugin has been provided for automatic application deployment.Developers who deploy applications by using WAR or JAR packages can now use toolkit-maven-plugin to automate the deployment of ECS applications and Swarm applications.

Deploy applications automatically

  1. Add the following plug-in dependencies to the pom.xml file in your packaged project.

    1. <build>
    2. <plugins>
    3. <plugin>
    4. <groupId>com.alibaba.cloud</groupId>
    5. <artifactId>toolkit-maven-plugin</artifactId>
    6. <version>1.0.0</version>
    7. </plugin>
    8. </plugins>
    9. </build>
  2. Create the .edas_config.yaml file in the root directory of the packaged project.If the packaged project is a Maven submodule, create the file in the submodule directory.

    1. env:
    2. region_id: cn-beijing
    3. app:
    4. app_id: eb20dc8a-e6ee-4f6d-a36f-5f6a54550453

    Among the preceding configuration items, region_id indicates the region ID of the application instance, while app_id indicates the application ID. The values of the preceding configuration items are for reference only. Replace them as needed.For information about other configuration items, see More configuration items.

    Perform the following steps to obtain the values of these parameters:

    1. Log on to the EDAS console.

    2. In the left-side navigation pane, click Application Management. On the Applications page, click the application that you want to deploy. On the Application Management page, click Deploy Application.

    3. On the Deploy Application page, click Generate Maven Plugin Configuration to retrieve the parameter values.

      Maven-plug-in-config

  3. Create an account file and configure the Access Key ID and Access Key Secret in yaml format. To view the Access Key ID and Access Key Secret, see User information management. We recommend that you configure application permissions with a RAM sub-account to improve application security.The following provides an example of configuration:

    1. access_key_id: abc
    2. access_key_secret: 1234567890

    Note: In this configuration, abc and 1234567890 are for reference only. Replace them as needed.In this configuration, the Access Key ID and Access Key Secret are only used to generate request signatures and not for any other purposes, such as network transfers.

  4. Go to the root directory (or the submodule directory if multiple Maven modules are used) and run this packaging command:

    1. mvn clean package toolkit:deploy -Daccess_key_file={Account file path}

    The preceding parameters are described as follows:

    • toolkit:deploy: Use toolkit-maven-plugin to deploy the application after successful packaging.The application is deployed only when this parameter is added.

    • access_key_file: indicates the Alibaba Cloud account file.(For more information on how to specify an access key, see Account configuration).

  5. After running the preceding command, the following message is displayed, indicating that you have successfully deployed the application with toolkit-maven-plugin.

     Deployment results output

More configuration items

Configuration items for deploying applications are classified as follows:

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

The currently supported configuration items are listed in the following table.

TypekeyRequiredDescription
envregion_idYesIndicates the ID of the region where the application is located.
appapp_idYesThe ID of the application.
package_versionNoIndicates the version of the deployment package.The default value is the string of the pom.xml file version plus the instance creation time, for example, 1.0 (2018-09-27 19:00:00).
descNoIndicates the deployment description.
group_id NoIndicates the deployment group ID.The default value is “all groups”.
batch NoIndicates the number of deployment batches.The default value is one batch and the maximum is five batches.
batch_wait_time NoIndicates the waiting time (in minutes) between deployment batches.The default value is 0.
buildPackIdNoIf you created the application without specifying the runtime environment and deploying it:For a native Dubbo or Spring Cloud application, this field can be ignored the first time it is deployed.For a non-native Dubbo or Spring Cloud application, this field is required the first time it is deployed.(Retrieve the field value over the ListBuildPackRequest API.)
componentIdsNoIf you created the application without specifying the runtime environment and deploying it:For a native Dubbo or Spring Cloud application to be deployed for the first time using a WAR package, specify the Apache Tomcat version through this field.(Retrieve the field over the ListComponentsRequest API).For a non-native Dubbo or Spring Cloud application to be deployed for the first time using a WAR package, this field can be ignored the first time it is deployed.
stage_timeout NoIndicates the timeout period (in minutes) for each release stage. The default value is 5 minutes.If batch_wait_time is set, it is automatically added to this parameter during calculation.During runtime, if a stage waits for a longer time than this threshold value, the plugin automatically exits.
ossregion_idNoIndicates the ID of the region where the target bucket is located.The default value is the ID of the region where the application is located.
bucketNoIndicates the name of the target bucket.The default value is the free OSS storage space provided by EDAS.If OSS configuration items are specified, you must specify the bucket parameter. Otherwise, the instance uses the free OSS storage space automatically allocated by EDAS.
keyNoIndicates the custom path used to upload the application package to OSS. The instance uses the free OSS storage space provided by EDAS by default.If you are using a specified OSS storage space, specify the package storage path in this parameter and use the {region_id}, {app_id}, and {version} variables to set the parameterized path, for example, pkgs/petstore/{version}/store.war.The default value is {region_id}/{app_id}/{version}.
access_key_id NoIndicates the custom account ID used to upload the application package to OSS.
access_key_secret NoIndicates the custom account key used to upload the application package to OSS.

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

For example, take an application whose ID is eb20dc8a-e6ee-4f6d-a36f-5f6a54550453 is deployed in Beijing. The group ID is 06923bb9-8c5f-4508-94d8-517b692f30b9, and the deployment package version is 1.2.In this case, the configuration is as follows:

  1. env:
  2. region_id: cn-beijing
  3. app:
  4. app_id: eb20dc8a-e6ee-4f6d-a36f-5f6a54550453
  5. package_version: 1.2
  6. group_id: 06923bb9-8c5f-4508-94d8-517b692f30b9

Configuration example 2: Specify an OSS storage space

For example, we want to deploy the application whose ID is eb20dc8a-e6ee-4f6d-a36f-5f6a54550453 and upload the deployment package to our own bucket named release-pkg in Beijing. The file object name is my.war, the OSS account ID is ABC, and the OSS account key is 1234567890.In this case, the configuration is as follows:

  1. env:
  2. region_id: cn-beijing
  3. app:
  4. app_id: eb20dc8a-e6ee-4f6d-a36f-5f6a54550453
  5. oss:
  6. region_id: cn-beijing
  7. bucket: release-pkg
  8. key: my.war
  9. access_key_id: ABC
  10. access_key_secret: 1234567890

Specify a configuration file

  • When no configuration file is specified, this plugin uses the .edas_config.yaml file in the root directory of the packaged project as the configuration file.If the packaged project is a submodule of the Maven project, the configuration file is under the root directory of the submodule by default but not 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 while another configuration file is specified, the plugin uses the latter.

Description of account configuration and priority

When deploying an application using this plugin, you must provide an Alibaba Cloud Access Key for application deployment.Currently, this plugin supports multiple configuration methods. If duplicate configuration methods are present, the configuration method with a higher priority overrides that with a lower priority.Configuration methods are as follows in descending order of priority:

  • ak/sk parameter specified in the command line: You can specify the access_key_id and access_key_secret in either of the following ways:

    • If you package the project by running Maven commands, specify both parameters with -Daccess_key_id=xx -Daccess_key_secret=xx.

    • When configuring this plugin in the pom file, configure both parameters as follows:

      1. <plugin>
      2. <groupId>com.alibaba.cloud</groupId>
      3. <artifactId>toolkit-maven-plugin</artifactId>
      4. <version>1.0.0</version>
      5. <configuration>
      6. <accessKeyId>abc</accessKeyId>
      7. <accessKeySecret>1234567890</accessKeySecret>
      8. </configuration>
      9. </plugin>
  • Specify the account file in the command line (recommended): When you package the project by running Maven commands, specify the account file in yaml format with -Daccess_key_file={account file path.Example:

    1. access_key_id: abc
    2. access_key_secret: 1234567890
  • Use the default Alibaba Cloud account file: If you choose not to specify an account in either of the preceding ways, the plugin uses the set Alibaba Cloud account to deploy the application.

    • aliyuncli: If you have used the latest aliyuncli tool and configured your Alibaba Cloud account, Alibaba Cloud generates the .aliyuncli sub-directory under the current Home directory and creates the credentials file in the .aliyuncli sub-directory to store your account information.Here, we use the Mac system as an example and assume the system user is “jack”, so the following information is stored in the /Users/jack/.aliyuncli/credentials file:

      1. [default]
      2. aliyun_access_key_secret = 1234567890
      3. aliyun_access_key_id = abc

      This plugin uses this account file as the account for deploying the application.

  • aliyun: If you have used a legacy Aliyun tool and configured the Alibaba Cloud account, the Aliyun tool generates the .aliyun sub-directory under the current Home directory and creates the config.json file in the .aliyun sub-directory.Here, we use the Mac system as an example and assume the system user is “jack”, so the account information is stored in the /Users/jack/.aliyun/config.json file:

    1. {
    2. "current": "",
    3. "profiles": [{
    4. "name": "default",
    5. "mode": "AK",
    6. "access_key_id": "",
    7. "access_key_secret": "",
    8. "sts_token": "",
    9. "ram_role_name": "",
    10. "ram_role_arn": "",
    11. "ram_session_name": "",
    12. "private_key": "",
    13. "key_pair_name": "",
    14. "expired_seconds": 0,
    15. "verified": "",
    16. "region_id": "",
    17. "output_format": "json",
    18. "language": "en",
    19. "site": "",
    20. "retry_timeout": 0,
    21. "retry_count": 0
    22. }, {
    23. "name": "",
    24. "mode": "AK",
    25. "access_key_id": "abc",
    26. "access_key_secret": "xxx",
    27. "sts_token": "",
    28. "ram_role_name": "",
    29. "ram_role_arn": "",
    30. "ram_session_name": "",
    31. "private_key": "",
    32. "key_pair_name": "",
    33. "expired_seconds": 0,
    34. "verified": "",
    35. "region_id": "cn-hangzhou",
    36. "output_format": "json",
    37. "language": "en",
    38. "site": "",
    39. "retry_timeout": 0,
    40. "retry_count": 0
    41. }],
    42. "meta_path": ""
    43. }
  • System environment variables: Finally, the plugin attempts to retrieve the access_key_id and access_key_secret values from system environment variables.Namely, the plugin retrieves these values from System.getenv("access_key_id") and System.getenv("access_key_secret") in the Java code.