Integrate Dubbo Services into Aeraki Mesh for Full L7 Traffic Management

Overview

Aeraki Mesh is a CNCF sandbox project that provides L7 traffic management for any protocol inside a service mesh. It uses the MetaProtocol Proxy data‑plane, which includes a built‑in Dubbo codec (Meta‑Dubbo), and relies on Istio’s control‑plane APIs (xDS) to distribute configuration.

Architecture

The Dubbo2Istio component watches a Dubbo service registry (ZooKeeper, Nacos, or Etcd) and creates corresponding Istio ServiceEntry resources. Each generated ServiceEntry receives a virtual IP from the reserved 240.240.0.0/16 range and a DNS name derived from the fully‑qualified Dubbo interface name (lower‑cased). Labels from the Dubbo instance (e.g., version, release) become endpoint labels, enabling fine‑grained L7 routing, load balancing, circuit breaking, and rate limiting.

Method 1 – Bridge Dubbo Registries with Dubbo2Istio

Deploy the Dubbo2Istio component in the Kubernetes cluster. It continuously synchronises Dubbo services to Istio.

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  annotations:
    interface: org.apache.dubbo.samples.basic.api.DemoService
  labels:
    manager: aeraki
    registry: dubbo-zookeeper
  name: aeraki-org-apache-dubbo-samples-basic-api-demoservice
  namespace: dubbo
spec:
  hosts:
    - org.apache.dubbo.samples.basic.api.demoservice
  addresses:
    - 240.240.0.61
  endpoints:
    - address: 172.18.0.59
      labels:
        aeraki_meta_app_version: v2
        anyhost: "true"
        application: dubbo-sample-provider
        ...
      ports:
        tcp-dubbo: 20880
      serviceAccount: default

Set the following environment variables in the Dubbo provider deployment so that the required Istio endpoint labels are registered in the Dubbo registry:

AERAKI_META_APP_NAMESPACE – Kubernetes namespace of the application

AERAKI_META_APP_SERVICE_ACCOUNT – ServiceAccount used for mTLS authentication

AERAKI_META_WORKLOAD_SELECTOR – Workload selector label (e.g., app=dubbo-sample-provider)

AERAKI_META_APP_VERSION – Application version (used for traffic rules)

kind: Deployment
metadata:
  name: dubbo-sample-provider-v2
  labels:
    app: dubbo-sample-provider
spec:
  selector:
    matchLabels:
      app: dubbo-sample-provider
  replicas: 1
  template:
    metadata:
      labels:
        app: dubbo-sample-provider
        version: v2
    spec:
      containers:
        - name: dubbo-sample-provider
          image: aeraki/dubbo-sample-provider
          env:
            - name: AERAKI_META_APP_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: AERAKI_META_APP_SERVICE_ACCOUNT
              valueFrom:
                fieldRef:
                  fieldPath: spec.serviceAccountName
            - name: AERAKI_META_WORKLOAD_SELECTOR
              value: "dubbo-sample-provider"
            - name: AERAKI_META_APP_VERSION
              value: v2

Register the same values as custom Dubbo parameters so they are stored in the Dubbo registry and propagated to Istio:

<dubbo:application name="dubbo-sample-provider">
  <dubbo:parameter key="aeraki_meta_app_namespace" value="${AERAKI_META_APP_NAMESPACE}"/>
  <dubbo:parameter key="aeraki_meta_app_service_account" value="${AERAKI_META_APP_SERVICE_ACCOUNT}"/>
  <dubbo:parameter key="aeraki_meta_app_version" value="${AERAKI_META_APP_VERSION}"/>
  <dubbo:parameter key="aeraki_meta_workload_selector" value="${AERAKI_META_WORKLOAD_SELECTOR}"/>
</dubbo:application>

Method 2 – Define ServiceEntry Manually

If the Dubbo service is already containerised and you do not need to keep the original Dubbo SDK discovery, you can create a static ServiceEntry without deploying Dubbo2Istio:

apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: dubbo-demoservice
  namespace: meta-dubbo
  annotations:
    interface: org.apache.dubbo.samples.basic.api.DemoService
spec:
  hosts:
    - org.apache.dubbo.samples.basic.api.demoservice
  ports:
    - number: 20880
      name: tcp-metaprotocol-dubbo
      protocol: TCP
  workloadSelector:
    labels:
      app: dubbo-sample-provider
  resolution: STATIC

Client Configuration – Bypassing Dubbo SDK Service Discovery

After the application joins the mesh, configure the Dubbo consumer to use the ServiceEntry DNS name directly, eliminating the need for the Dubbo registry:

<dubbo:reference id="demoService" check="true" interface="org.apache.dubbo.samples.basic.api.DemoService" url="dubbo://org.apache.dubbo.samples.basic.api.demoservice:20880" timeout="3000"/>

Demo Setup

Direct ServiceEntry Demo – Follow Aeraki’s quick‑start guide to install Aeraki, Istio, and the Dubbo sample program.

Dubbo2Istio Demo – Clone the demo repository, create the dubbo namespace with Istio sidecar injection, apply the Aeraki bootstrap configuration, and deploy a Dubbo registry (ZooKeeper, Nacos, or Etcd). The source code is available at:

https://github.com/aeraki-mesh/dubbo-envoyfilter-example

Typical commands for the Dubbo2Istio demo:

git clone https://github.com/aeraki-mesh/dubbo2istio.git
cd dubbo2istio
kubectl create ns dubbo
kubectl label namespace dubbo istio-injection=enabled --overwrite
kubectl apply -f demo/k8s/aeraki-bootstrap-config.yaml -n dubbo
kubectl apply -f demo/k8s/zk -n dubbo   # replace with Nacos or Etcd manifests as needed

After deployment, use Aeraki Mesh tutorials to explore L7 traffic governance features such as load balancing, dynamic routing, circuit breaking, and rate limiting for Dubbo services.