How to implement a custom protocol

MetaProtocol Proxy provides a well-designed mechanism to allows us to quickly implement a layer-7 proxy for a custom protocol.

MetaProtocol Proxy already has most of the features needed for a Layer-7 proxy building in, including load balancing, circuit breaker, RDS dynamic routing, local/global reate limiting, header mutation, metrics and tracing reporting, etc., more features are under the way. Therefore, creating a layer-7 protocol based on MetaProtocol for a custom protocol is very simple. We only need to implement the codec interface. Normally, it’s only a few hundred lines of code.

After implementing the data proxy based on MetaProtocol, without any control-plane coding, we can manage the services using those custom protocols in the Isito service mesh via Aeraki, providing service governance capabilities for those services, such as traffic splitting, canary releasing, traffic mirroring, etc. This is because Aeraki recognizes any Layer-7 protocol based on MetaProtocol and provides user-friendly traffic rules at the control plane. Aeraki translates these traffic rules into MetaProtocol configurations and then distribute them to the data plane.

Another benefit of using MetaProtocol to develop custom protocols in a service mesh is that the solution is completely non-intrusive to the upstream open source projects such as Istio, Envoy, and MetaProtocol Proxy itself. It allows rapid iterations to follow the upstream projects and take advantage of the new capabilities provided by new versions of the upstream projects without maintaining your own forked branches.

Implementation the codec interface

Aeraki provides a scaffold project awesomerpc to demonstrate how to implement a custom protocol with MetaProtocol proxy. You can fork this repo and use it as the start point to build a layer-7 proxy for your proprietary protocol.

  1. git clone https://github.com/aeraki-mesh/meta-protocol-awesomerpc.git my-protocol-proxy

The most important files are awesomerpc_codec.h and awesomerpc_codec.cc in the src/application_protocols/awesomerpc/ directory. These two files define the interface and implementation code for the codec of the application protocol.

The definition of awesomerpc_codec.h is as follows, you can see that the application protocol codec is implementing the MetaProtocolProxy::Codec interface. To implement the application protocol, you only need to write the decode, encode and onError methods.

  1. /**
  2.  * Codec for Awesomerpc protocol.
  3.  */
  4. class AwesomerpcCodec : public MetaProtocolProxy::Codec,
  5.                   public Logger::Loggable<Logger::Id::misc> {
  6. public:
  7.   AwesomerpcCodec() {};
  8.   ~AwesomerpcCodec() override = default;
  10.   //For protocol decoding, the buffer needs to be parsed and populated with Metadata, which will be used for MetaProtocol Proxy filters, such as flow restriction and matching conditions for routes.
  11.   MetaProtocolProxy::DecodeStatus decode(Buffer::Instance& buffer,
  12.                                          MetaProtocolProxy::Metadata& metadata) override;
  14.   //Protocol encoding, the request or response packet can be modified according to Mutation, such as adding, deleting or modifying the header, which needs to be written back to the buffer after modification
  15.   void encode(const MetaProtocolProxy::Metadata& metadata,
  16.               const MetaProtocolProxy::Mutation& mutation, Buffer::Instance& buffer) override;
  18.   //the framework uses err code to return error messages to the client, such as route not found or connection creation failure, etc., the encoded data needs to be written to the buffer
  19.   void onError(const MetaProtocolProxy::Metadata& metadata, const MetaProtocolProxy::Error& error,
  20.                Buffer::Instance& buffer) override;
  22. ...

You can also refer to the dubbo and thrift implementation when writing the codec.

Configuration WORKSPACE

Configure the metaProtocol, envoy and Istio-Proxy dependencies in the WORKSPACE file in the root directory.

You need to configure the git commit of metaProtocol in WORKSPACE, and the dependencies of envoy and Istio-Proxy refer to the configuration in WORKSPACE in the commit of metaProtocol. See Version compatibility between Aeraki and MetaProtocol and Istio for version dependencies.

  2. # Get the dependency version information of envoy from the meta_protocol_proxy code
  3. ENVOY_SHA = "98c1c9e9a40804b93b074badad1cdf284b47d58b"
  4. ENVOY_SHA256 = "4365a4c09b9a8b3c4ae34d75991fcd046f3e19d53d95dfd5c89209c30be94fe6"
  5. ......
  7. # Get the istio_proxy dependency version information from the meta_protocol_proxy code
  8. http_archive(
  9.     name = "io_istio_proxy",
  10.     strip_prefix = "proxy-1.10.0",
  11.     sha256 = "19d13bc4859dc8422b91fc28b0d8d12a34848393583eedfb08af971c658e7ffb",
  12.     url = "https://github.com/istio/proxy/archive/refs/tags/1.10.0.tar.gz",   
  13. )
  14. ...... 
  16. # set metaProtocol git commit
  17. git_repository(
  18.   name = "meta_protocol_proxy",
  19.   remote = "https://github.com/aeraki-mesh/meta-protocol-proxy.git",
  20.   commit = "5ae1d11",  
  21. )

Compilation

It is recommended to use Ubuntu 18.04 as the build environment.

Install the required software for compiling:

  1. sudo wget -O /usr/local/bin/bazel https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-$([ $(uname -m) = "aarch64" ] && echo "arm64" || echo "amd64")
  2. sudo chmod +x /usr/local/bin/bazel
  4. sudo apt-get install \
  5. autoconf \
  6. automake \
  7. cmake \
  8. curl \
  9. libtool \
  10. make \
  11. ninja-build \
  12. patch \
  13. python3-pip \
  14. unzip \
  15. virtualenv
  17. sudo add-apt-repository ppa:ubuntu-toolchain-r/test
  18. sudo apt update
  19. sudo apt-get install llvm-10 lldb-10 llvm-10-dev libllvm10 llvm-10-runtime clang-10 clang++-10 lld-10 gcc-10 g++-10

Build binary:

  1. ./build.sh

Define a ApplicationProtocol

To identify custom protocols in Istio, you need to create an Aeraki’s ApplicationProtocol CRD resource.

  1. apiVersion: metaprotocol.aeraki.io/v1alpha1
  2. kind: ApplicationProtocol
  3. metadata:
  4.   name: my-protocol
  5.   namespace: istio-system
  6. spec:
  7.   protocol: my-protocol
  8.   codec: aeraki.meta_protocol.codec.my_protocol

Protocol Selection

Aeraki identifies MetaProtocol-based application protocols by the service prefix, and the port name of the service must follow this naming convention: tcp-metaprotocol-{application protocol}-xxx. Service definitions can be K8s service or Istio ServiceEntry.

The following ServiceEntry defines a dubbo service:

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: ServiceEntry
  3. metadata:
  4.   name: dubbo-demoservice
  5.   namespace: meta-dubbo
  6. spec:
  7.   hosts:
  8.     - org.apache.dubbo.samples.basic.api.demoservice
  9.   ports:
  10.     - number: 20880
  11.       name: tcp-metaprotocol-dubbo
  12.       protocol: TCP
  13.   workloadSelector:
  14.     labels:
  15.       app: dubbo-sample-provider
  16.   resolution: STATIC

The following Service defines a Thrift service:

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: thrift-sample-server
  5. spec:
  6.   selector:
  7.     app: thrift-sample-server
  8.   ports:
  9.     - name: tcp-metaprotocol-thrift-hello-server
  10.       protocol: TCP
  11.       port: 9090
  12.       targetPort: 9090

Note: The prefix of the port definition needs to contain “tcp”, this is because Istio will treat the service as a tcp service. Aeraki will recognize the application protocol that follows and process it accordingly at Layer 7.

Last modified May 12, 2022: Update implement-a-custom-protocol.md (8de9faf)