Configuring Local Rate Limiting for MetaProtocol Services with Aeraki Mesh

Aeraki Mesh, a CNCF sandbox project, enables management of any Layer‑7 protocol within a service mesh. This tutorial, part of a series co‑produced with the Cloud Native Technology Community, shows how to use Aeraki to provide traffic routing, local and global rate limiting for Dubbo, Thrift, and custom protocols built with Aeraki Protocol.

Installation of the example program

First, follow the quick‑start guide to install Aeraki, Istio, and the example applications. After installation, two namespaces ( meta-dubbo and meta-thrift ) appear, each containing a sample program implementing the Dubbo or Thrift protocol via MetaProtocol.

➜  ~ kubectl get ns | grep meta
meta-dubbo        Active   16m
meta-thrift       Active   16m

Aeraki’s rate‑limit design is intuitive and flexible: it can limit all inbound requests to a service or apply fine‑grained limits based on specific conditions.

Limiting all inbound requests for a service

kubectl apply -f- <

Note: because local rate limiting is applied per service instance, the effective limit multiplies by the number of instances.

Using aerakictl to view client logs shows that each instance processes only two requests per minute, resulting in four successful requests across two instances.

➜  ~ aerakictl_app_log client meta-thrift -f --tail 10
Hello Aeraki, response from thrift-sample-server-v1-5c8476684-842l6/172.17.0.40
Hello Aeraki, response from thrift-sample-server-v2-6d5bcc885-hpx7n/172.17.0.41
Hello Aeraki, response from thrift-sample-server-v1-5c8476684-842l6/172.17.0.40
Hello Aeraki, response from thrift-sample-server-v2-6d5bcc885-hpx7n/172.17.0.41
org.apache.thrift.TApplicationException: meta protocol local rate limit: request '5' has been rate limited
... (truncated)

Conditional rate limiting

Aeraki allows multiple conditional limits per service, enabling fine‑grained control such as per‑method or per‑user limits. The matching conditions use the same attributes as routing rules.

apiVersion: metaprotocol.aeraki.io/v1alpha1
kind: MetaRouter
metadata:
  name: test-metaprotocol-thrift-route
  namespace: meta-thrift
spec:
  hosts:
  - thrift-sample-server.meta-thrift.svc.cluster.local
  localRateLimit:
    conditions:
    - match:
        attributes:
          method:
            exact: sayHello
      tokenBucket:
        fillInterval: 60s
        maxTokens: 10
        tokensPerFill: 10
    - match:
        attributes:
          method:
            exact: ping
      tokenBucket:
        fillInterval: 60s
        maxTokens: 100
        tokensPerFill: 100

Combining service‑wide and conditional limits

You can define a global limit for all requests while specifying exceptions for particular methods.

apiVersion: metaprotocol.aeraki.io/v1alpha1
kind: MetaRouter
metadata:
  name: test-metaprotocol-thrift-route
  namespace: meta-thrift
spec:
  hosts:
  - thrift-sample-server.meta-thrift.svc.cluster.local
  localRateLimit:
    tokenBucket:
      fillInterval: 60s
      maxTokens: 1000
      tokensPerFill: 1000
    conditions:
    - match:
        attributes:
          method:
            exact: ping
      tokenBucket:
        fillInterval: 60s
        maxTokens: 100
        tokensPerFill: 100

Underlying mechanism

Aeraki translates the MetaRouter configuration into a local rate‑limit filter that is injected into the sidecar proxy’s listener for the service. The filter configuration is part of the MetaProtocol Proxy settings.

To inspect the sidecar configuration, run:

aerakictl_sidecar_config server-v1 meta-thrift | fx

The relevant portion of the inbound listener for the Thrift service looks like this:

{
  "name": "envoy.filters.network.meta_protocol_proxy",
  "typed_config": {
    "@type": "type.googleapis.com/udpa.type.v1.TypedStruct",
    "type_url": "type.googleapis.com/aeraki.meta_protocol_proxy.v1alpha.MetaProtocolProxy",
    "value": {
      "stat_prefix": "inbound|9090||",
      "application_protocol": "thrift",
      "route_config": {
        "name": "inbound|9090||",
        "routes": [
          { "route": { "cluster": "inbound|9090||" } }
        ]
      },
      "codec": { "name": "aeraki.meta_protocol.codec.thrift" },
      "meta_protocol_filters": [
        {
          "name": "aeraki.meta_protocol.filters.local_ratelimit",
          "config": {
            "@type": "type.googleapis.com/aeraki.meta_protocol_proxy.filters.local_ratelimit.v1alpha.LocalRateLimit",
            "stat_prefix": "thrift-sample-server.meta-thrift.svc.cluster.local",
            "token_bucket": {
              "max_tokens": 2,
              "tokens_per_fill": 2,
              "fill_interval": "60s"
            }
          }
        },
        { "name": "aeraki.meta_protocol.filters.router" }
      ]
    }
  }
}

The next article in the series will cover global rate limiting.