Serverless App Engine:Use a Maven plug-in to automatically deploy applications to SAE

Typical scenarios

Deploy an application

This section describes how to deploy a project in an on-premises environment to SAE by adding a plug-in dependency and specifying deployment information.

1. Add a plug-in dependency to the pom.xml file of the packaged project.

   Note

   We recommend that you use the toolkit-maven-plugin plug-in of the latest version 1.1.8.

   <build>
       <plugins>
           <plugin>
               <groupId>com.alibaba.cloud</groupId>
               <artifactId>toolkit-maven-plugin</artifactId>
               <version>1.1.8</version>
           </plugin>
       </plugins>
   </build>                            

2. Specify the plug-in information.

   The plug-in information includes the account information, package information, and deployment information. For more information, see More parameters.

   1. Specify the account information.

      In the root directory of your packaged project, create an account configuration file that is in the YAML format. Set the name of the file to toolkit_profile.yaml and add the following information to the file:

      regionId:        # The region where the application resides. 
      accessKeyId:     # The AccessKey ID that is used to access Alibaba Cloud resources. To reduce security risks, we recommend that you use the AccessKey ID of a RAM user. 
      accessKeySecret: # The AccessKey secret that is used to access Alibaba Cloud resources. To reduce security risks, we recommend that you use the AccessKey secret of a RAM user.                                     

   2. Specify the package information.

      In the root directory of your packaged project, create a package configuration file that is in the YAML format. If the packaged project is created for a Maven submodule, create the file in the directory of the submodule. Set the name of the file to toolkit_package.yaml and add the following information to the file:

      apiVersion: V1
      kind: AppPackage
      spec:
       packageType:   # The type of the deployment package. Valid values:War, FatJar, Image, and url. The packageUrl parameter takes effect only if you set this parameter to url. 
       packageUrl:    # The URL of the package. This parameter can be configured only if you use a WAR or FatJar package to deploy your application. If you do not configure this parameter, the current package that is built by using Maven is used. 
       imageUrl:      # This parameter can be configured only if you set the packageType parameter to Image. You can also build a Docker image in your on-premises environment to deploy your application. 
       acrInstanceId: # The ID of the Container Registry Enterprise Edition instance. If you want to use a Container Registry Enterprise Edition instance, configure this parameter. 

   3. Specify the deployment information.

      In the root directory of your packaged project, create a deployment file that is in the YAML format. Set the name of the file to toolkit_deploy.yaml and add the following information to the file:

      apiVersion: V1
      kind: AppDeployment
      spec:
       type: serverless
       target:
         appId:        # The ID of the application that you want to deploy. If you configure this parameter, you do not need to configure the namespaceId or appName parameter. 
         namespaceId:  # The ID of the namespace to which the application belongs. If you do not know the application ID, you can use the namespace to which the application belongs and the application name to deploy the application. 
         appName:      # The name of the application. If you do not know the application ID, you can use the namespace to which the application belongs and the application name to deploy the application.                                    

3. Go to the directory where the pom.xml file resides and run the following command to build a deployment project.

   Important

   If you want to deploy a submodule, go to the directory where the pom.xml file resides in the submodule to deploy a project.

   mvn clean package toolkit:deploy -Dtoolkit_profile=toolkit_profile.yaml -Dtoolkit_package=toolkit_package.yaml -Dtoolkit_deploy=toolkit_deploy.yaml                           

   The following table describes the parameters in the preceding command.

   Parameter	Description
   toolkit:deploy	Specifies the system to deploy the application after the packaging operation is complete.
   -Dtoolkit_profile	Specifies the account configuration file. If the account configuration file is in the same directory as pom.xml and the file name is .toolkit_profile.yaml, this parameter is not required. In this case, the account configuration file is automatically obtained by the plug-in. Important The name of the .toolkit_profile.yaml file that is automatically obtained by the plug-in starts with a period (.).
   -Dtoolkit_package	Specifies the package file. If the package file is in the same directory as pom.xml and the file name is .toolkit_package.yaml, this parameter is not required. In this case, the plug-in automatically obtains the package file. Important The name of the .toolkit_package.yaml file that is automatically obtained by the plug-in starts with a period (.).
   -Dtoolkit_deploy	Specifies the deployment file. If the deployment file is in the same directory as pom.xml and the file name is .toolkit_deploy.yaml, this parameter is not required. In this case, the plug-in automatically obtains the package file. Important The name of the .toolkit_deploy.yaml file that is automatically obtained by the plug-in starts with a period (.).
   -Ddeploy_version	Specifies the version that you want to deploy. The specified version is assigned a higher priority than the Version that is specified in the toolkit_deploy.yaml file. Note This parameter is available only for toolkit-maven-plugin plug-ins of version 1.1.2 and later.

   After you run the packaging command, the following information is displayed. If BUILD SUCCESS appears, the deployment is successful.

Deploy a multi-module project

In most cases, a project consists of multiple modules. You can use the toolkit-maven-plugin plug-in to deploy your multi-module project by using one of the following methods:

More parameters

• View packaging parameters.

  The package file supports the following parameters:

  apiVersion: V1
  kind: AppPackage
  spec:
    packageType:   # The type of the deployment package. Valid values:War, FatJar, Image, and url. The packageUrl parameter takes effect only if you set this parameter to url. 
    imageUrl:      # The URL of the image. This parameter can be configured only if you set the packageType to Image. If you call the spec.build.docker command to build a Docker image in your on-premises environment to deploy your application, you do not need to configure this parameter. 
    acrInstanceId: # The ID of the Container Registry Enterprise Edition instance. If you want to use a Container Registry Enterprise Edition instance, configure this parameter. 
    packageUrl:    # The URL of the package. This parameter can be configured only if you use a WAR or FatJar package to deploy your application. 
    build:
      docker:
         dockerfile:        # The file that is used to build your Docker image. If you want to build an image in your on-premises environment, you must configure this parameter. Example: Dockerfile. 
         imageRepoAddress:  # The address of the Alibaba Cloud image repository. If you want to deploy an image in your on-premises environment, you must configure this parameter. Example: registry.cn-beijing.aliyuncs.com/edas_demo/demo. 
         imageTag:          # The image tag. If you want to build an image in your on-premises environment, you must configure this parameter. Example: test. 
         imageRepoUser:     # The username that is used to access the Alibaba Cloud image repository. If you want to build an image in your on-premises environment, you must configure this parameter. Example: ***@***. 
         imageRepoPassword: # The password that is used to access the Alibaba Cloud image repository. If you want to build an image in your on-premises environment, you must configure this parameter. Example: password. 
      oss:
         bucket:              # The name of the destination Object Storage Service (OSS) bucket. If you want to use a custom OSS bucket to store the deployment package, you must configure this parameter. Example: bucket-name01. 
         key:                 # The path of the OSS bucket. If you want to use a custom OSS bucket to store the deployment package, you must configure this parameter. Example: test1/test.jpg. 
         accessKeyId:         # The AccessKey ID that is used to access OSS. If you want to use a custom OSS bucket to store the deployment package, you must configure this parameter. 
         accessKeySecret:     # The AccessKey secret that is used to access OSS. If you want to use a custom OSS bucket to store the deployment package, you must configure this parameter. 
         useVpcEndpoint: true # Specifies whether to upload the file over an internal network. To upload the file over an internal network, set this parameter to true. If you do not want to upload the file over an internal network, set this parameter to false. 
         accessTimeout:30     # The validity period of the temporary access URL of the deployment package. Unit: minutes. Default value: 30. If you want to specify a custom validity period, change the default value.                        

• View deployment parameters.

  The deployment file supports the following parameters.

  Note

  • If you want to add new parameters, join the DingTalk group 32874633 for technical support.

  • To use the following parameters to deploy applications, we recommend that you use the latest version of the Maven plug-in.

  apiVersion: V1
  kind: AppDeployment
  spec:
    type: serverless
    target:
      appName:     # The name of the application. 
      namespaceId: # The ID of the namespace to which the application belongs. 
      appId:       # The ID of the application. The plug-in deploys the specified application. If you do not configure this parameter, the values of the namespaceId and appName parameters are used to search for the application. 
    version:       # The version that you want to deploy. By default, the version is in the DD-HH:MM:SS format. 
    jdk:           # The version of the Java Development Kit (JDK) on which the deployment package of the application depends. Valid values: Open JDK 8, Open JDK 7, Dragonwell 11, Dragonwell 8, openjdk-8u191-jdk-alpine3.9, and openjdk-7u201-jdk-alpine3.9. This parameter is unavailable if you deploy applications by using images. 
    webContainer:  # The version of the Tomcat container on which the deployment package depends. Valid values: apache-tomcat-7.0.91 and apache-tomcat-8.5.42. 
    batchWaitTime: # The interval between two consecutive batches. 
    command:       # The command that is used to start the image. The command must be an existing executable object in the container. 
    commandArgs:   # The parameters of the image startup command. These parameters are required by the preceding startup command. 
    - 1d
    updateStrategy: 
      type: GrayBatchUpdate # The type of the deployment policy. BatchUpdate specifies the phased release policy. GrayBatchUpdate specifies the canary release policy. 
      batchUpdate: 
        batch: 2 # The number of batches. If you set the type parameter to GrayBatchUpdate, this parameter specifies the number of batches in which you want to release the remaining instances after the canary release is performed. 
        releaseType: manual # The processing method for the batches. If you set the value to manual, you must manually release the batches. If you set the value to auto, SAE automatically releases the batches. 
        batchWaitTime: 0 # The interval at which the instances in a batch are deployed. Unit: minutes. This parameter is required if you set the releaseType parameter to auto. 
      grayUpdate: # This parameter is required if you set the type parameter to GrayBatchUpdate. 
        gray: 1 # The number of instances for which you want to perform the canary release. 
    envs:    # The container environment variables. 
      - name: envtmp0
        value: '0'
      - name: envtmp1
        value: '1'
    customHostAlias:  # The custom host mappings in the container. 
      - hostName: 'samplehost1'
        ip: '127.X.X.X'
      - hostName: 'samplehost2'
        ip: '127.X.X.X'
    jarStartOptions:  # The startup options in the JAR package. The settings are used to start the application container. 
    jarStartArgs:     # The arguments in the JAR package. The arguments are used to start the application container. 
    liveness: # The liveness check settings of the container. If a container fails this health check, the container is restarted. 
      exec:
        command:
          - sleep
          - 1s
      initialDelaySeconds: 5
      timeoutSeconds: 11
      periodSeconds: 30 
    readiness:  # The readiness check settings of the container. If a container fails this health check multiple times, the container is restarted. Containers that fail this health check cannot receive traffic from Server Load Balancer (SLB) instances. 
      exec:
        command:
          - sleep
          - 1s
      initialDelaySeconds: 5
      timeoutSeconds: 11
      periodSeconds: 30   
    minReadyInstances: 1  # The minimum number of available instances. During a rolling upgrade process or if a rolling upgrade fails, the number of available instances must be greater than or equal to the value of this parameter. If you set this parameter to 0, the number of instances is unlimited. The minimum number of instances in an auto scaling policy must be greater than or equal to the value of this parameter. Otherwise, exceptions occur. 
    timezone: Asia/Shanghai # The time zone. 
    warStartOptions: CATALINA_OPTS=\"$CATALINA_OPTS $Options\" catalina.sh run # The startup command of the WAR package. 
    tomcatConfig: # The Tomcat configuration that is deployed by using the WAR package. 
      port: 8082
      maxThreads: 399
      contextPath: /test/
      uriEncoding: UTF-8
      useBodyEncodingForUri: false
    nasConfig: # The NAS configuration. 
      nasId: 3fc4*****
      mountHost: 3fc4*****.cn-shanghai.nas.aliyuncs.com
      mountDesc:
        - mountPath: /nas
          nasPath: /
    postStart: # The post-start configuration. 
      exec:
        command:
          - sh
          - -c
          - echo helloPostStart
    preStop: # The pre-stop configuration. 
      exec:
        command:
          - sh
          - -c
          - echo helloPreStop
    terminationGracePeriodSeconds: 9 # The timeout period for a graceful shutdown. Unit: seconds. 
    changeOrderDesc: maven test # The change order. 
    autoEnableApplicationScalingRule: true # Specifies whether to enable an auto scaling policy. 
    associateEip: true # The elastic IP address (EIP) configuration. This parameter may conflict with the autoEnableApplicationScalingRule parameter. You can set only the associateEip parameter or the autoEnableApplicationScalingRule parameter to true. 
    configMapMountDesc: # The ConfigMap configuration. 
      - configMapId: 123**
        key: config1
        mountPath: /configMap
    enableAhas: true # Specifies whether to enable access to Application High Availability Service (AHAS). 
    ossConfig: # The OSS configuration. 
      ossAkId: ******
      ossAkSecret: ******
      ossMountDescs:
        - bucketName: ******-cn-shanghai-s-*****
          bucketPath: /
          mountPath: /ossPath
          readOnly: true
    slsConfigs: # The logging configuration of Log Service. If you do not configure the following parameters, SAE automatically creates the corresponding Log Service resources. If you configure Parameter 1 and Parameter 2, the specified Log Service resources are used and a Logtail configuration is automatically created. If you configure Parameter 1, Parameter 2, and Parameter 3, the specified Log Service resources and Logtail configuration are used. 
      - logDir: /tmp/test.log # Required. The path of file logs. 
        projectName: test-project   # Optional. Parameter 1. 
        logstoreName: test-logstore # Optional. Parameter 2. 
        logtailName: test-logtail   # Optional. Parameter 3. 

References