Access Dubbo Backend Services via Gateway for HTTP Traffic

Proxying Dubbo Service through Higress Cloud Native Gateway, supporting triple protocol.

In the triple protocol specification, we detailed the friendly design of the triple protocol for browsers and gateways, one very important aspect being that triple supports running on both HTTP/1 and HTTP/2:

  • Use the efficient triple binary protocol between backend services.
  • For the frontend access layer, it supports all standard HTTP tools like cURL to request backend services in standard application/json, application/yaml, etc.

Next, let’s see how to quickly access the backend triple microservice system through some common gateway products for frontend HTTP traffic.

Note

After using the triple protocol, there is no need for generalized invocation, http -> dubbo protocol conversion, etc. Any mainstream gateway device can directly access the backend triple protocol service through HTTP traffic. Refer to Publishing REST Style Services

Native HTTP Access

triple protocol - 图1

As illustrated, HTTP requests from browsers, phones, or web servers can be directly forwarded by the gateway to backend Dubbo services, while backend services continue to use the triple binary protocol. Since the traffic entering and exiting the gateway is standard HTTP, there is no need for the gateway to perform any proprietary protocol conversion work, nor any custom logic, allowing it to focus solely on traffic routing and responsibilities.

In a real production environment, the only issue that the gateway needs to address is service discovery: how to dynamically perceive changes in backend triple service instances? The good news is that several mainstream open-source gateway products, such as Apache APISIX and Higress, generally support using Nacos, Zookeeper, Kubernetes as upstream data sources.

Next, we will detail the workflow of the entire mechanism using a typical example of Higress + Nacos + Dubbo.

triple protocol - 图2

Start Example Application

The complete source code for this example can be found at dubbo-samples-gateway-higress-triple.

In this example, a triple service defined as org.apache.dubbo.samples.gateway.api.DemoService is defined and published:

  1. public interface DemoService {
  2.     String sayHello(String name);
  3. }

Next, we demonstrate how to start the Dubbo service and use the Higress gateway to forward requests to the backend service.

Access the Higress Gateway

Next, we will specifically demonstrate the steps for accessing the Higress gateway, including deploying the Dubbo application, Nacos registry, and Higress gateway.

Install Higress and Nacos

The following example is deployed in a Kubernetes environment, so ensure you are connected to a usable Kubernetes cluster.

  1. Install Higress, refer to the Higress Deployment Documentation.

  2. Install Nacos by running

  1. kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/2-advanced/dubbo-samples-gateway/dubbo-samples-gateway-higress/dubbo-samples-gateway-higress-triple/deploy/nacos/Nacos.yaml

Start the Dubbo Application

After packaging the above example application into a Docker image (using the pre-packaged official example image), start the application in standard Kubernetes Deployment format:

  1. kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/2-advanced/dubbo-samples-gateway/dubbo-samples-gateway-higress/dubbo-samples-gateway-higress-triple/deploy/provider/Deployment.yaml

The specific deployment file definition is as follows:

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.     name: gateway-higress-triple-provider
  5.     namespace: default
  6.     labels:
  7.         app: gateway-higress-triple-provider
  8. spec:
  9.     replicas: 1
  10.     selector:
  11.         matchLabels:
  12.             app: gateway-higress-triple-provider
  13.     template:
  14.         metadata:
  15.             labels:
  16.                 app: gateway-higress-triple-provider
  17.         spec:
  18.             containers:
  19.                 -   name: gateway-higress-triple-provider
  20.                     image: docker.io/allenyi/higress-triple:2.0.0
  21.                     imagePullPolicy: IfNotPresent
  22.                     ports:
  23.                         - containerPort: 50052
  24.                     env:
  25.                         - name: NACOS_ADDRESS
  26.                           value: nacos-server.default.svc.cluster.local

Forward Requests to Dubbo Service through Higress

Higress can interface with Nacos as a service source through McpBridge. Apply the following resources in the K8s cluster to configure McpBridge:

  1. kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/2-advanced/dubbo-samples-gateway/dubbo-samples-gateway-higress/dubbo-samples-gateway-higress-triple/deploy/mcp/mcpbridge.yaml

The specific definition of the installed McpBridge resource is as follows:

  1. apiVersion: networking.higress.io/v1
  2. kind: McpBridge
  3. metadata:
  4.   name: nacos-service-resource
  5.   namespace: higress-system
  6. spec:
  7.   registries:
  8.   - domain: nacos-server.default.svc.cluster.local
  9.     nacosGroups:
  10.     - DEFAULT_GROUP
  11.     name: nacos-service-resource
  12.     port: 8848
  13.     type: nacos2

For more detailed configuration, refer to McpBridge Configuration Documentation.

Next, we create the following Ingress to create an HTTP route pointing to the Dubbo service:

  1. kubectl apply -f https://raw.githubusercontent.com/apache/dubbo-samples/master/2-advanced/dubbo-samples-gateway/dubbo-samples-gateway-higress/dubbo-samples-gateway-higress-triple/deploy/ingress/Ingress.yaml

Thus, requests with the path prefix /org.apache.dubbo.samples.gateway.api.DemoService will be routed to the Dubbo service we just created.

The specific resource definitions of the installed resources are as follows:

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/destination: gateway-higress-triple-provider.DEFAULT-GROUP.public.nacos
  6.   name: demo
  7.   namespace: default
  8. spec:
  9.     ingressClassName: higress
  10.     rules:
  11.         - http:
  12.               paths:
  13.                   - backend:
  14.                         resource:
  15.                             apiGroup: networking.higress.io
  16.                             kind: McpBridge
  17.                             name: default
  18.                     path: /org.apache.dubbo.samples.gateway.api.DemoService
  19.                     pathType: Prefix

Note here that the annotation higress.io/destination specifies the target service to which the route should ultimately be forwarded: gateway-higress-triple-provider, which is the name of the application that just started the Dubbo service (relying on the application-level address list registered by Dubbo3).

For services sourced from Nacos, the format here is: “ServiceName.ServiceGroup.NamespaceID.nacos”. Note that the underscore ‘_’ in the service group is converted to a dash ‘-’. When the namespace is not specified, the default value here is “public”.

For more traffic governance-related configurations, refer to Ingress Annotation Configuration Documentation and Advanced Traffic Governance through Ingress Annotation.

Request Validation

You can access Higress using cURL to call the backend triple service:

  1. $ curl "localhost/org.apache.dubbo.samples.gateway.api.DemoService/sayHello?name=HigressTriple"
  3. "Hello HigressTriple"

Note

You need to run kubectl port-forward service/higress-gateway -n higress-system 80:80 443:443 to expose Higress in the cluster for access.

The access path exposed directly through the Java path name and method, such as /org.apache.dubbo.samples.gateway.api.DemoService/sayHello/, while easily callable, is not user-friendly for the front end. Next, let’s see how to publish a REST-style HTTP service.

REST Style Interface

In the previous example, something like http://127.0.0.1:9080/triple/demo/hello would be a more frontend-friendly access method. To achieve this, we can configure uri rewrite in gateways such as Higress, thereby mapping the frontend /triple/demo/hello to the backend /org.apache.dubbo.samples.gateway.api.DemoService/sayHello/.

In addition to reconfiguring the gateway rewrite rules, the Dubbo framework also provides built-in support for exposing REST-style HTTP access paths for triple services. The specific usage depends on whether you are using protobuf-based service definition mode or Java interface-based service definition mode:

  • Java Interface Mode: By directly adding annotations to the Java interface, you can simultaneously publish REST-style services. Currently, both Spring Web and JAX-RS annotation standards are supported.
  • Protobuf Mode: By using grpc-gateway, you can publish REST-style services.

Adding Annotations to Service Definitions

By adding any of the following annotations to the Java interface, you can publish both triple binary and REST-style services. With this configuration, for the same service, you can access it using standard binary triple format or via REST HTTP in JSON format.

Spring Web style annotations:

  1. @RequestMapping("/triple/demo")
  2. public interface DemoService {
  4.     @RequestMapping(method = RequestMethod.GET, value = "/hello")
  5.     String sayHello(@RequestParam("name") String name);
  7. }

Note

Regarding the interface annotations:

At this point, our route prefix configuration is as follows, maintaining the previous Nacos address configuration, while changing the path prefix to a friendlier /triple/demo:

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/destination: gateway-higress-triple-provider.DEFAULT-GROUP.public.nacos
  6.   name: demo
  7.   namespace: default
  8. spec:
  9.     ingressClassName: higress
  10.     rules:
  11.         - http:
  12.               paths:
  13.                   - backend:
  14.                         resource:
  15.                             apiGroup: networking.higress.io
  16.                             kind: McpBridge
  17.                             name: default
  18.                     path: /triple/demo
  19.                     pathType: Prefix

The service can be accessed using /triple/demo/hello:

  1. $ curl "localhost/triple/demo/hello?name=HigressTriple"
  3. "Hello HigressTriple"

Note

The content described in this article applies only to the versions of the triple protocol released after Dubbo 3.3.0.

Feedback

Was this page helpful?

Yes No

Last modified September 30, 2024: Update & Translate Overview Docs (#3040) (d37ebceaea7)