Connecting Spring Cloud Applications to ServiceComb Engines

Prerequisites

• Microservice applications have been developed based on Spring Cloud.

  For details about microservice application development in the Spring Cloud microservice framework, see https://spring.io/projects/spring-cloud.

Procedure

1. Add dependencies to the pom.xml file of the project.
   • If you develop microservices using Spring Cloud, introduce the following dependencies:

     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-service-engine</artifactId>
     </dependency>
     
     NOTE:

     The spring-cloud-starter-huawei-service-engine module consists of the following dependent modules:

     <!-- Registry and discovery module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-discovery</artifactId>
     </dependency>
     <!-- Configuration center module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-config</artifactId>
     </dependency>
     <!-- Service governance module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-governance</artifactId>
     </dependency>
     <!-- Dark launch module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-router</artifactId>
     </dependency>
     
   • If you develop the gateway using Spring Cloud, introduce the following dependencies:

     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-service-engine-gateway</artifactId>
     </dependency>
     NOTE:

     The spring-cloud-starter-huawei-service-engine-gateway module consists of the following dependent modules:

     <!-- Registry and discovery module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-discovery</artifactId>
     </dependency>
     <!-- Configuration center module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-config</artifactId>
     </dependency>
     <!-- Service governance module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-governance</artifactId>
     </dependency>
     <!-- Dark launch module -->
     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-router</artifactId>
     </dependency>
     <!-- Gateway module -->
     <dependency>
       <groupId>org.springframework.cloud</groupId>
       <artifactId>spring-cloud-starter-gateway</artifactId>
     </dependency>
     

     You are advised to use Maven Dependency Management to manage the third-party software dependencies of a project. Add the following information to the project:

      <dependencyManagement>
         <dependencies>
           <!-- configure user spring cloud / spring boot versions -->
           <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-dependencies</artifactId>
             <version>${spring-boot.version}</version>
             <type>pom</type>
             <scope>import</scope>
           </dependency>
           <dependency>
             <groupId>org.springframework.cloud</groupId>
             <artifactId>spring-cloud-dependencies</artifactId>
             <version>${spring-cloud.version}</version>
             <type>pom</type>
             <scope>import</scope>
           </dependency>
           <!-- configure spring cloud huawei version -->
           <dependency>
             <groupId>com.huaweicloud</groupId>
             <artifactId>spring-cloud-huawei-bom</artifactId>
             <version>${spring-cloud-huawei.version}</version>
             <type>pom</type>
             <scope>import</scope>
           </dependency>
         </dependencies>
       </dependencyManagement>

   Skip the operation if your project already contains the preceding dependencies.

   If other registry and discovery libraries, such as Eureka, are used in your project, you need to adjust the project as follows:

   • Delete the dependencies related to Eureka from the project. For example:

     <dependency>
       <groupId>org.springframework.cloud</groupId>
       <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
     </dependency>
   • If @EnableEurekaServer is used in the code, delete it and replace it with @EnableDiscoveryClient.
     NOTE:

     The spring-cloud-starter-huawei-service-engine component provides functions such as service registration, configuration center, service governance, dark launch, and contract management. Contract management is not mandatory for the running of Spring Cloud microservice applications. The ServiceComb engine limits the number of contracts. When the number of microservice application contracts exceeds the limit, the registry fails. If the legacy system cannot be properly split to reduce the number of contracts, the dependency can be excluded and the contract management function is not used.

     <dependency>
       <groupId>com.huaweicloud</groupId>
       <artifactId>spring-cloud-starter-huawei-service-engine</artifactId>
       <exclusions>
     	<exclusion>
     	  <groupId>com.huaweicloud</groupId>
     	  <artifactId>spring-cloud-starter-huawei-swagger</artifactId>
     	</exclusion>
       </exclusions>
     </dependency>

2. Configure microservice information.

   Add the microservice description to the bootstrap.yml file. If the bootstrap.yml file is not available in the project, create one.

   spring:
     application:
       name: basic-provider
     cloud:
       servicecomb:
         service:
           name: ${spring.application.name}
           application: basic-application
           environment: production
         discovery:
           enabled: true
           healthCheckInterval: 15
           pollInterval: 15000
           waitTimeForShutDownInMillis: 15000
           address: http://127.0.0.1:30100
           appName: basic-application  
           version: 0.0.1
         config:
           enabled: true
           kie:
             customLabel: default
             customLabelValue: default
           serverAddr: http://127.0.0.1:{port}
           serverType: {servertype}
           fileSource: governance.yaml
         dashboard:
           enabled: false
           address: http://127.0.0.1:30109
   

   For the description of each configuration item, see Table 1.

   Table 1 Spring Cloud configuration items

   Item	Description	Default Value	Mandatory	Remarks
   spring.application.name	Application name.	-	Yes	-
   spring.cloud.servicecomb.service.name	Microservice name.	-	No	Use spring.application.name if this item is not configured. In Spring Cloud Huawei 1.10.2-2021.0.x and earlier, this item is configured by using spring.cloud.servicecomb.discovery.serviceName.
   spring.cloud.servicecomb.service.application	Name of the application to which the current microservice belongs.	default	No	Only microservices with the same application name can discover each other. You are advised to define a name for each service to implement service discovery isolation. In Spring Cloud Huawei 1.10.2-2021.0.x and earlier, this item is configured by using spring.cloud.servicecomb.discovery.appName.
   spring.cloud.servicecomb.service.environment	Microservice registry environment.	<Empty>	No	Only microservices with the same environment name can discover each other. In Spring Cloud Huawei 1.10.2-2021.0.x and earlier, this item is configured by using server.env. The value is the environment ID. The value can be development, testing, acceptance, or production.
   spring.cloud.servicecomb.discovery.enabled	Whether to enable service discovery.	true	No	-
   spring.cloud.servicecomb.discovery.healthCheckInterval	Heartbeat detection time, in seconds.	15	No	-
   spring.cloud.servicecomb.discovery.pollInterval	Polling time for pulling an instance, in milliseconds.	15000	No	-
   spring.cloud.servicecomb.discovery.waitTimeForShutDownInMillis	Waiting duration for lossless shutdown, in milliseconds. When a service stops, it deregisters itself from the registry center. After waitTimeForShutDownInMillis, the container exits.	15000	No	-
   spring.cloud.servicecomb.discovery.address	Registry and discovery address.	-	Yes	-
   spring.cloud.servicecomb.discovery.appName	Service name.	-	Yes	-
   spring.cloud.servicecomb.discovery.version	Service version.	1.0.0.0	Yes	This parameter is required during service upgrade to prevent contract registry failures.
   spring.cloud.servicecomb.config.enabled	Whether to enable dynamic configuration.	true	No	-
   spring.cloud.servicecomb.config.kie.customLabel	Custom label.	-	No	When the configuration center type is kie, if a custom label is used to deliver configurations, you need to configure customLabel and customLabelValue. The microservice name, environment name, and application name labels support only independent adaptation.
   spring.cloud.servicecomb.config.kie.customLabelValue	Custom label value.	-	No	-
   spring.cloud.servicecomb.config.serverAddr	Configuration center address.	-	Yes	For ServiceComb engine 1.x, {port} is 30103. For ServiceComb engine 2.x, {port} is 30110.
   spring.cloud.servicecomb.config.serverType	Configuration center type.	config-center	Yes	For ServiceComb engine 1.x, the value is config-center. For ServiceComb engine 2.x, the value is kie (recommended) or config-center.
   spring.cloud.servicecomb.config.fileSource	List of YAML configuration items, which are separated by commas (,)	-	No	When the configuration center type is config-center, if the configuration center delivers configurations through a configuration file, you must set fileSource to parse the configurations. Otherwise, the correct configurations cannot be obtained.
   spring.cloud.servicecomb.config.dashboard.enabled	Whether to enable dashboard.	false	No	-
   spring.cloud.servicecomb.config.dashboard.address	Dashboard server IP address. The port number is 30109.	-	No	-

   NOTE:

   The bootstrap.yml file is loaded before the application.yml file in the application boot phase. You are advised to configure the basic configuration center address and authentication information required for starting the application in the bootstrap.yml file. If such information is configured in the application.yml file, the application may fail to be started.

3. (Optional) Configure security authentication parameters.

   Perform this step only when you use the exclusive ServiceComb engine and enable security authentication. In other scenarios, skip this step.

   After security authentication is enabled for a ServiceComb engine, all called APIs can be called only after a token is obtained. For details about the authentication process, see RBAC.

   To use security authentication, obtain the username and password from the ServiceComb engine and then add the following configuration to the configuration file.

   • Configuration in plaintext

     spring:
       cloud:
         servicecomb:
           credentials:
             account:
               name: username
               password: password
               cipher: default
   • Custom encryption algorithms for storage

     Implement the com.huaweicloud.common.util.Cipher API using either of the following methods:
     String name(), which is the name definition of spring.cloud.servicecomb.credentials.cipher and needs to be added to the configuration file.
     char[] decode(char[] encrypted), which is the decryption API used to decrypt secretKey.
     public class CustomCipher implements Cipher
     To implement encryption and decryption, you need to use BootstrapConfiguration as the startup add-in. Add the following statement first:
     @Configuration
     public class MyCipherConfiguration {
       @Bean
       public Cipher customCipher() {
         return new CustomCipher();
       }
     }
     Add the META-INF/spring.factories file to define the configuration:
     org.springframework.cloud.bootstrap.BootstrapConfiguration=\
     com.huaweicloud.common.transport.MyCipherConfiguration
     After the custom configuration is complete, you can use the new decryption algorithm in the bootstrap.yaml file.

     spring:
       cloud:
         servicecomb:
           credentials:
             account:
               name: username
               password: password
             cipher: user-defined algorithm name
   NOTE:

   The RBAC function requires 1.6.0-Hoxton or later.