Use toolkit-maven-plugin to implement a phased release on an application (applicable to Kubernetes clusters)

Automated deployment

To use toolkit-maven-plugin for automated application deployment, add the plug-in dependency, configure the plug-in, and build deployment jobs.

1. Add the plug-in dependency

   Add the following plug-in dependency to the pom.xml file:

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

   Note We recommend that you use the latest toolkit-maven-plugin version.
2. Configure the plug-in

   The configurations of the plug-in include account configuration, packaging configuration, and deployment configuration. For information about more custom configuration items, see Specify the packaging parameters and Specify the deployment parameters.

   1. Account configurations

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

      regionId: # the region where the application is deployed. For example, the cn-beijing value represents China (Beijing), the cn-shanghai value represents China (Shanghai), and the cn-hangzhou value represents China (Hangzhou).
      jarPath: # the path of the deployment package. If you specify this parameter, you do not need to package the application file in Maven. The package in the specified path is used to deploy the application. You can specify an absolute path or a relative path.
      accessKeyId: # the AccessKey ID 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 used to access Alibaba Cloud resources. To reduce security risks, we recommend that you use the AccessKey secret of a RAM user. 

   2. Packaging configuration

      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. Name the file toolkit_package.yaml and add the following information to the file:

      apiVersion: V1
      kind: AppPackage
      spec:
       packageType: # the type of the application deployment package. Valid values are War, FatJar, Image, and URL. The packageUrl parameter takes effect only if you set this parameter to URL.
       packageUrl: # This parameter can be specified if the value of packageType is War or FatJar. If this parameter is left blank, the current Maven build package is used to deploy your application.
       imageUrl: # This parameter is required if the value of packageType is Image. You can also build a Docker image in your on-premises environment to deploy your application. 

   3. Deployment configuration

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

      apiVersion: V1
      kind: AppDeployment
      spec:
        type: kubernetes
        target:
          appId: # the ID of the application to be deployed. If you specify the appId parameter, you do not need to specify the namespaceId and appName parameters.
          namespaceId: # the ID of the namespace where the application is to be deployed. If the value of appId is unavailable, the values of namespaceId and appName can be used to identify the application to be deployed.
          appName: # the name of the application. If the value of appId is unavailable, the values of namespaceId and appName can be used to identify the application to be deployed.
        updateStrategy:
          type: GrayBatchUpdate    # the canary release (phased) mode.
          grayUpdate: # the canary release settings.
            gray: x                 # an integer value, which specifies the number of instances to which the canary release applies.
          batchUpdate:             # the settings for the batches of the phased release.
            batch: x                # an integer value, which specifies the number of batches.
            releaseType: xxx        # the release type. The value auto indicates an automatic release. The value manual indicates a manual release.
            batchWaitTime: x        # an integer value, which specifies the interval between two consecutive batches. Unit: seconds. 

3. Build deployment jobs
   Go to the directory where pom.xml is located. If you want to deploy a Maven submodule, go to the directory where the pom.xml file of the submodule is located. Run the following command:

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

   The following list describes the command parameters:

   • toolkit:deploy: instructs the system to deploy the application after the packaging operation is complete.
   • -Dtoolkit_profile: specifies your 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. The account configuration file is automatically obtained by the plug-in. Take note that a decimal point (.) is required at the beginning of the file name.
   • -Dtoolkit_package: specifies your 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. The package file is automatically obtained by the plug-in. Take note that a decimal point (.) is required at the beginning of the file name.
   • -Dtoolkit_deploy: specifies your 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. The deployment file is automatically obtained by the plug-in. Take note that a decimal point (.) is required at the beginning of the file name.
   • -Ddeploy_version: specifies the version to be deployed. The specified version has a higher priority than the version specified in the deployment configuration file.
     Note toolkit-maven-plugin 1.0.6 and later support the Ddeploy_version parameter.

   After you run the packaging command, the following information is displayed. If "BUILD SUCCESS" appears, it means that the deployment was successful.

More configuration items

1. Specify the packaging parameters.

   The package file supports the following parameters:

   apiVersion: V1
   kind: AppPackage
   spec:
     packageType: # the type of the application deployment package. Valid values are War, FatJar, Image, and URL. The packageUrl parameter takes effect only if you set the parameter to URL.
     imageUrl: # the URL of the image. This parameter is required if you use an image to deploy your application.
     packageUrl: # the URL of the package. This parameter is required if you use a WAR or FatJar package to deploy your application.
   build:
       docker:
          dockerfile: # the file used to build your Docker image. This parameter is required if you want to build an image in your on-premises environment to deploy the application.
          imageRepoAddress: # the address of the Alibaba Cloud image repository that you want to use. This parameter is required if you want to build an image in your on-premises environment to deploy the application.
          imageTag: # the image tag. This parameter is required if you want to build an image in your on-premises environment to deploy the application.
          imageRepoUser: # the username used to access the Alibaba Cloud image repository. This parameter is required if you want to build an image in your on-premises environment to deploy the application.
          imageRepoPassword: # the password used to access the Alibaba Cloud image repository. This parameter is required if you want to build an image in your on-premises environment to deploy the application.
             OSS:
               bucket: # the name of the destination Object Storage Service (OSS) bucket. This parameter is required if you want to use a custom OSS bucket to store the deployment package.
               key:             # the path of the custom OSS bucket. This parameter is required if you want to use a custom OSS bucket to store the deployment package.
               accessKeyId:     # the AccessKey ID used to access OSS. This parameter is required if you want to use a custom OSS bucket to store the deployment package.
               accessKeySecret: # the AccessKey secret used to access OSS. This parameter is required if you want to use a custom OSS bucket to store the deployment package. 

2. Specify the deployment parameters.

   The deployment file supports the following parameters:

   apiVersion: V1
   kind: AppDeployment
   spec:
     type: kubernetes
     target:
       appName:     # the name of the application.
       namespaceId: # the namespace where the application is to be deployed.
       appId:       # the ID of the application. The plug-in deploys the specified application. If you do not specify this parameter, the values of namespaceId and appName are used to search for the application to be deployed.
       version: # the version to be deployed. The default format is day-hour-minute-second.
       jdk:         # the JDK version on which the deployed package depends. Open JDK 7 and Open JDK 8 are supported. This parameter is not supported when you use an image to deploy your application.
       webContainer: # the Tomcat container version on which the deployed package depends. apache-tomcat-7.0.91 is supported. This parameter is not supported when you use an image to deploy your application.
       batchWaitTime: # the interval between two consecutive batches.
       command:       # the command used to start the image. The command must be an existing executable object in the container. For example, you can set the command to sleep. If you specify this parameter, the original startup command of the image becomes invalid.
       commandArgs:   # the parameters of the image startup command. These parameters are required by the preceding startup command.
       - 1d
     envs:       # the container environment variables.
       - name: envtmp0
         value: '0'
       - name: envtmp1
         value: '1'
     liveness: # checks the container health status. A container that fails to pass the health check is stopped and then recovered.
        exec:
         command:
           - sleep
           - 1s
       initialDelaySeconds: 5
       timeoutSeconds: 11
     readiness:  # checks the application startup status. A container that fails to pass this health check multiple times is stopped and then restarted. Containers that fail to pass health checks do not receive traffic from Server Load Balancer (SLB) instances.
        exec:
         command:
           - sleep
           - 1s
       initialDelaySeconds: 5
       timeoutSeconds: 11

Typical scenarios