Configuration Working Principle

This article mainly explains the APIs and working principles related to Dubbo configuration, learning about Dubbo’s multiple configuration sources, the specific configuration methods for each source, and the priority and coverage relationships between different configuration sources.

Implementation Principles

To better manage various configurations, Dubbo abstracts a structured configuration component set, dividing the components by purpose to control behaviors in different scopes.

From the perspective of implementation principles, all configuration items in Dubbo will ultimately be assembled into URLs, using URLs as carriers during subsequent startup and RPC calls to control framework behaviors.

For specific configuration items supported by each component and their meanings, please refer to configuration item manual.

# JVM -D
-Ddubbo.config.mode=strict

# Environment Variable
DUBBO_CONFIG_MODE=strict

# External Configuration (Configuration Center), Spring application Environment, dubbo.properties
dubbo.config.mode=strict

service and reference

service and reference are the two most fundamental configuration items in Dubbo, used to register a specified interface or implementation class as a Dubbo service and control the service’s behavior through configuration items.

• service is used on the service provider side; the interfaces and implementation classes configured by service will be defined as standard Dubbo services, thereby providing RPC request services externally.
• reference is used on the consumer side; interfaces configured by reference will be defined as standard Dubbo services, and the generated proxy can initiate RPC requests to the remote service.

An application can configure any number of service and reference.

consumer and provider

• When there are multiple reference configurations in the application, consumer specifies the default values shared among these reference, such as shared timeout values, to simplify complex configurations. If a configuration item value is set individually in a reference, the priority of that configuration will be higher.
• When there are multiple service configurations in the application, provider specifies the default values shared among these service, such that if a configuration item value is set individually in a service, the priority of that configuration will be higher.

The consumer component can also virtual-group references; references in different groups can have different default value settings, such as in XML format configuration, the <dubbo:reference /> tag can be nested within the <dubbo:consumer /> tag to achieve grouping. The same effect can be achieved between provider and service.

Configuration Methods

Property Configuration

Generate configuration components based on property Key-value, similar to Spring Boot’s ConfigurationProperties; please refer to Property Configuration.

Another important feature of property configuration is [Property Overrides](../principle/#32-Property Overrides), which uses values from external properties to override the properties of already created configuration components.

Please refer to [Externalized Configuration](../principle/#33-Externalized Configuration) for placing property configurations in external configuration centers.

Apart from the differences in outer driving methods, Dubbo’s configuration reading generally follows these principles:

1. Dubbo supports multi-level configurations and automatically implements the overrides between configurations based on predetermined priorities. Ultimately, all configurations are summarized to the data bus URL to drive subsequent service exposure and reference processes.
2. The configuration format is primarily Properties, following the agreed-upon path-based [naming conventions](../principle/#1-Configuration Format).

API Configuration

Organizing configurations in Java code, including Raw API and Bootstrap API, please refer to API Configuration.

public static void main(String[] args) throws IOException {
        ServiceConfig<GreetingsService> service = new ServiceConfig<>();
        service.setApplication(new ApplicationConfig("first-dubbo-provider"));
        service.setRegistry(new RegistryConfig("multicast://224.5.6.7:1234"));
        service.setInterface(GreetingsService.class);
        service.setRef(new GreetingsServiceImpl());
        service.export();
        System.out.println("first-dubbo-provider is running.");
        System.in.read();
}

XML Configuration

Configuring various components in XML format, supporting seamless integration with Spring; please refer to XML Configuration.

  <!-- dubbo-provier.xml -->

  <dubbo:application name="demo-provider"/>
  <dubbo:config-center address="zookeeper://127.0.0.1:2181"/>

  <dubbo:registry address="zookeeper://127.0.0.1:2181" simplified="true"/>
  <dubbo:metadata-report address="redis://127.0.0.1:6379"/>
  <dubbo:protocol name="dubbo" port="20880"/>

  <bean id="demoService" class="org.apache.dubbo.samples.basic.impl.DemoServiceImpl"/>
  <dubbo:service interface="org.apache.dubbo.samples.basic.api.DemoService" ref="demoService"/>

Annotation Configuration

Exposing service and reference service interfaces using annotations, supporting seamless integration with Spring; please refer to Annotation Configuration.

  // AnnotationService service implementation

  @DubboService
  public class AnnotationServiceImpl implements AnnotationService {
      @Override
      public String sayHello(String name) {
          System.out.println("async provider received: " + name);
          return "annotation: hello, " + name;
      }
  }

## dubbo.properties

dubbo.application.name=annotation-provider
dubbo.registry.address=zookeeper://127.0.0.1:2181
dubbo.protocol.name=dubbo
dubbo.protocol.port=20880

Spring Boot Configuration

Using Spring Boot to reduce unnecessary configurations, combining Annotation with application.properties/application.yml to develop Dubbo applications; please refer to Annotation Configuration.

## application.properties

# Spring boot application
spring.application.name=dubbo-externalized-configuration-provider-sample

# Base packages to scan Dubbo Component: @com.alibaba.dubbo.config.annotation.Service
dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service

# Dubbo Application
## The default value of dubbo.application.name is ${spring.application.name}
## dubbo.application.name=${spring.application.name}

# Dubbo Protocol
dubbo.protocol.name=dubbo
dubbo.protocol.port=12345

## Dubbo Registry
dubbo.registry.address=N/A

## DemoService version
demo.service.version=1.0.0

Configuration Specifications and Sources

Dubbo adheres to a path-based configuration specification, where each configuration component can be expressed in this manner. In terms of configuration sources, a total of 6 types of configuration sources are supported; that is, Dubbo will try to load configuration data from the following locations:

• JVM System Properties, JVM -D arguments
• System environment, JVM process’s environment variables
• Externalized Configuration, [Externalized Configuration](../principle/#33-Externalized Configuration), reading from configuration centers
• Application Configuration, the application’s property configuration, extracting attribute sets starting with “dubbo” from the Spring application’s Environment
• API / XML / annotation and other programming interfaces that can be understood as a type of configuration source, a method aimed directly at user programming for configuration collection
• Reading configuration files dubbo.properties from the classpath

dubbo-spring-boot-samples

  ## application.properties

  # Spring boot application
  spring.application.name=dubbo-externalized-configuration-provider-sample

  # Base packages to scan Dubbo Component: @com.alibaba.dubbo.config.annotation.Service
  dubbo.scan.base-packages=com.alibaba.boot.dubbo.demo.provider.service

  # Dubbo Application
  ## The default value of dubbo.application.name is ${spring.application.name}
  ## dubbo.application.name=${spring.application.name}

  # Dubbo Protocol
  dubbo.protocol.name=dubbo
  dubbo.protocol.port=12345

  ## Dubbo Registry
  dubbo.registry.address=N/A

  ## service default version
  dubbo.provider.version=1.0.0

Next, we’ll analyze the working principles of Dubbo configuration from three aspects: configuration format, configuration sources, and loading processes.

1 Configuration Format

All configurations currently supported by Dubbo are in .properties format, including -D, Externalized Configuration, etc., with all configuration items in .properties following a path-based configuration format.

In Spring applications, property configurations can also be placed in application.yml, which is more readable with its tree hierarchical structure.

# Application-level configuration (no id)
dubbo.{config-type}.{config-item}={config-item-value}

# Instance-level configuration (specifying id or name)
dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}
dubbo.{config-type}s.{config-name}.{config-item}={config-item-value}

# Service interface configuration
dubbo.service.{interface-name}.{config-item}={config-item-value}
dubbo.reference.{interface-name}.{config-item}={config-item-value}

# Method configuration
dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value}
dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value}

# Method argument configuration
dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value}

1.1 Application-level Configuration (no id)

The format for application-level configuration is: singular prefix for configuration type, without id/name.

# Application-level configuration (no id)
dubbo.{config-type}.{config-item}={config-item-value}

Similar to application, monitor, metrics, etc., these belong to application-level components, thus only allowing single instances to be configured; components like protocol, registry, etc., allow multiple configurations, and one may use the described format when only needing a singleton configuration. Common examples are as follows:

dubbo.application.name=demo-provider
dubbo.application.qos-enable=false

dubbo.registry.address=zookeeper://127.0.0.1:2181

dubbo.protocol.name=dubbo
dubbo.protocol.port=-1

1.2 Instance-level Configuration (specifying id or name)

The property configuration of a specific instance requires specifying id or name, where the prefix format is: plural prefix for configuration type + id/name. Applicable to components supporting multiple instance configurations like protocol, registry, etc.

# Instance-level configuration (specifying id or name)
dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}
dubbo.{config-type}s.{config-name}.{config-item}={config-item-value}

• If the instance with such an id or name doesn’t exist, the framework will create configuration component instances based on the properties listed here.
• If an identical id or name instance exists, the framework will use the listed properties as supplements to the existing instance configuration; refer to [Property Overrides](../principle#32-Property Overrides) for details.
• For specific plural configuration forms, refer to [Singular-Plural Configuration Correspondence Table](../principle#17-Configuration Item Singular-Plural Correspondence).

Configuration examples:

dubbo.registries.unit1.address=zookeeper://127.0.0.1:2181
dubbo.registries.unit2.address=zookeeper://127.0.0.1:2182

dubbo.protocols.dubbo.name=dubbo
dubbo.protocols.dubbo.port=20880

dubbo.protocols.hessian.name=hessian
dubbo.protocols.hessian.port=8089

1.3 Service Interface Configuration

dubbo.service.org.apache.dubbo.samples.api.DemoService.timeout=5000
dubbo.reference.org.apache.dubbo.samples.api.DemoService.timeout=6000

Method Configuration

Method configuration format:

# Method configuration
dubbo.service.{interface-name}.{method-name}.{config-item}={config-item-value}
dubbo.reference.{interface-name}.{method-name}.{config-item}={config-item-value}

# Method argument configuration
dubbo.reference.{interface-name}.{method-name}.{argument-index}.{config-item}={config-item-value}

Method configuration examples:

dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.timeout=7000
dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.oninvoke=notifyService.onInvoke
dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.onreturn=notifyService.onReturn
dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.onthrow=notifyService.onThrow
dubbo.reference.org.apache.dubbo.samples.api.DemoService.sayHello.0.callback=true

Equivalent to XML configuration:

<dubbo:reference interface="org.apache.dubbo.samples.api.DemoService" >
    <dubbo:method name="sayHello" timeout="7000" oninvoke="notifyService.onInvoke"
                  onreturn="notifyService.onReturn" onthrow="notifyService.onThrow">
        <dubbo:argument index="0" callback="true" />
    </dubbo:method>
</dubbo:reference>

1.4 Parameter Configuration

The parameters are a map object, supporting the configuration in the format of xxx.parameters=[{key:value},{key:value}].

dubbo.application.parameters=[{item1:value1},{item2:value2}]
dubbo.reference.org.apache.dubbo.samples.api.DemoService.parameters=[{item3:value3}]

1.5 Transport Layer Configuration

The triple protocol uses HTTP2 as the underlying communication protocol, allowing users to customize six settings parameters for HTTP2 6 settings parameters

The configuration format is as follows:

# Limit on the number of entries in the header compression index table for the other end
dubbo.rpc.tri.header-table-size=4096

# Enable server push functionality
dubbo.rpc.tri.enable-push=false

# The maximum number of concurrent streams allowed for the other end
dubbo.rpc.tri.max-concurrent-streams=2147483647

# The window size declared by the sender
dubbo.rpc.tri.initial-window-size=1048576

# Set the maximum number of bytes for frames
dubbo.rpc.tri.max-frame-size=32768

# Maximum number of bytes for uncompressed headers permitted for the other end
dubbo.rpc.tri.max-header-list-size=8192

Equivalent to YAML configuration:

dubbo:
  rpc:
    tri:
      header-table-size: 4096
      enable-push: false
      max-concurrent-streams: 2147483647
      initial-window-size: 1048576
      max-frame-size: 32768
      max-header-list-size: 8192

1.6 Property and XML Configuration Mapping Rules

The tag names and property names of XML can be combined with a ‘.’ separator. One property per line.

• dubbo.application.name=foo is equivalent to <dubbo:application name="foo" />
• dubbo.registry.address=10.20.153.10:9090 is equivalent to <dubbo:registry address="10.20.153.10:9090" />

If there are more than one tags in XML configuration, you can use ‘id’ to distinguish. If you do not specify id, it will apply to all tags.

• dubbo.protocols.rmi.port=1099 is equivalent to <dubbo:protocol id="rmi" name="rmi" port="1099" />
• dubbo.registries.china.address=10.20.153.10:9090 is equivalent to <dubbo:registry id="china" address="10.20.153.10:9090" />

1.7 Configuration Item Singular-Plural Correspondence Table

The naming for plural configurations follows the same rules for pluralizing ordinary words:

1. If it ends with the letter y, change y to ies.
2. If it ends with the letter s, add es.
3. Otherwise, add s.

2 Configuration Sources

Dubbo supports six configuration sources by default:

• JVM System Properties, JVM -D arguments
• System environment, JVM process’s environment variables
• Externalized Configuration, [Externalized Configuration](#33-Externalized Configuration), reading from configuration centers
• Application Configuration, the application’s property configuration, extracting attribute sets starting with “dubbo” from the Spring application’s Environment
• API / XML / annotation and other programming interfaces that can be understood as a configuration source, a method aimed directly at user programming for configuration collection
• Reading configuration files dubbo.properties from the classpath

Regarding the dubbo.properties attributes:

1. If there are more than one dubbo.properties files in the classpath (for example, two jar packages each containing dubbo.properties), Dubbo will randomly select one to load and print an error log.
2. Dubbo can automatically load dubbo.properties from the root directory of the classpath, but you can also specify the path using the JVM parameter: -Ddubbo.properties.file=xxx.properties.

2.1 Cover Relationship

If the same configuration item is specified through multiple configuration sources, overlaps may occur, and specific coverage relationships and priorities are referenced in the next subsection.

3 Configuration Loading Process

3.1 Handling Process

Dubbo’s configuration loading roughly consists of two stages:

• The first stage involves parsing and processing XML configuration/annotation configuration/Java configuration or executing API configuration code before the DubboBootstrap initialization, creating config beans and adding them to the ConfigManager.
• The second stage involves the DubboBootstrap initialization process, reading external configurations from the configuration center, processing instance-level attribute configurations and application-level attribute configurations in sequence, and finally refreshing all configuration instances’ attributes, i.e., [Property Overrides](../principle#32-Property Overrides).

3.2 Property Overrides

Property overrides may occur in two ways, and both may happen simultaneously:

1. Different configuration sources specify the same configuration item.
2. The same configuration source, but the same configuration item is specified at different levels.

3.2.1 Different Configuration Sources

3.2.2 Same Configuration Sources

Property override refers to using the configured attribute values to override the properties of config bean instances, similar to Spring’s PropertyOverrideConfigurer.

Property resource configurer that overrides bean property values in an application context definition. It pushes values from a properties file into bean definitions. Configuration lines are expected to be of the following form:

beanName.property=value

However, unlike PropertyOverrideConfigurer, Dubbo’s property overrides have multiple matching formats, with priorities ranked from high to low as follows:

#1. Instance-level configuration specifying id
dubbo.{config-type}s.{config-id}.{config-item}={config-item-value}

#2. Instance-level configuration specifying name
dubbo.{config-type}s.{config-name}.{config-item}={config-item-value}

#3. Application-level configuration (singular)
dubbo.{config-type}.{config-item}={config-item-value}

Property overriding handling process:

The search is conducted from high to low priority; if a preceding prefix property is found, the properties using this prefix will be selected, ignoring subsequent configurations.

3.3 Externalized Configuration

One of the aims of externalized configuration is to achieve centralized management of configurations. There are many mature professional configuration systems in the industry, such as Apollo and Nacos. What Dubbo does primarily is ensure proper functionality with these systems.

Externalized configurations differ in content and format, and can simply be understood as the external storage of dubbo.properties, allowing the configuration centers to better manage common configurations such as registry addresses and metadata center configurations.

# Centralize the management of registry address, metadata center address, etc., enabling unified environments and reducing development-side awareness.
dubbo.registry.address=zookeeper://127.0.0.1:2181
dubbo.registry.simplified=true

dubbo.metadata-report.address=zookeeper://127.0.0.1:2181

dubbo.protocol.name=dubbo
dubbo.protocol.port=20880

dubbo.application.qos.port=33333

• Priority By default, externalized configurations have a higher priority than local configurations, so the contents configured here will override local configuration values; details regarding the [cover relationship](#21-Cover Relationship) are explained separately in one chapter.

• Scope Externalized configurations come in global and application levels. Global configurations are shared among all applications, while application-level configurations are maintained by each application and are only visible to them. Current supported extended implementations include Zookeeper, Apollo, and Nacos.

3.3.1 Using Externalized Configuration

1. Add config-center configuration

<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>

2. Add global configuration items in the corresponding configuration center (Zookeeper, Nacos, etc.), as shown below in Nacos, for example:

After enabling externalized configuration, global configurations for registry, metadata-report, protocol, qos, etc. theoretically no longer need to be configured in the application, allowing application developers to focus on business service configurations. Shared global configurations can instead be uniformly set by the operations team in remote configuration centers.

This allows for the scenario where application only needs to care about:

• Service exposure and subscription configurations
• Configuration center address When deployed in different environments, other configurations can automatically be retrieved from the corresponding configuration center.

For instance, Dubbo-related configurations in each application may only need to include the following content, while the rest are managed by the specific environment’s configuration center:

dubbo
  application
    name: demo
  config-center
    address: nacos://127.0.0.1:8848

3.3.2 Custom Loading of Externalized Configuration

Dubbo’s support for configuration centers essentially involves pulling .properties files from remote sources to the local machine, then merging them with the local configurations. Theoretically, as long as the Dubbo framework can obtain the necessary configurations, it can start normally. It doesn’t matter whether these configurations were loaded by itself or directly provided by the application. Thus, Dubbo provides the following API, allowing users to push configured settings to the Dubbo framework themselves (users need to handle the configuration loading process), so that Dubbo no longer directly interacts with Apollo or Zookeeper for configuration reading.

// Application loads configurations by itself
Map<String, String> dubboConfigurations = new HashMap<>();
dubboConfigurations.put("dubbo.registry.address", "zookeeper://127.0.0.1:2181");
dubboConfigurations.put("dubbo.registry.simplified", "true");

// Push the organized configurations to the Dubbo framework
ConfigCenterConfig configCenter = new ConfigCenterConfig();
configCenter.setExternalConfig(dubboConfigurations);