Kroxylicious is an exploration for building a Kafka protocol proxy, addressing use cases such as multi-tenancy, schema validation, or encryption.
Java, version 11 or newer, and Apache Maven are required for building this project. Build the project like this:
$ mvn clean install
The running of the tests can be controlled with the following Maven properties:
| property | description |
|---|---|
-DskipUTs=true |
skip unit tests |
-DskipITs=true |
skip integration tests |
-DskipTests=true |
skip all tests |
The kafka environment used by the integrations tests can be defaulted with these two environment variables.
| env var | default | description |
|---|---|---|
TEST_CLUSTER_EXECUTION_MODE |
IN_VM |
IN_VM or CONTAINER. if IN_VM, kafka will be run same virtual machines as the integration test. Otherwise containers will be used. |
TEST_CLUSTER_KRAFT_MODE |
true |
if true, kafka will be run in kraft mode. |
When the integration-tests are run in CONTAINER mode, the kafka/zookeeper logs are written to a location specified by
the container.logs.dir system property. When run through Maven this is defaulted to integrationtests/target/container-logs.
Pass the -Dquick option to skip all tests and non-essential plug-ins and create the output artifact as quickly as possible:
$ mvn clean verify -Dquick
Run the following command to format the source code and organize the imports as per the project's conventions:
$ mvn process-sources
Build with the dist profile for creating an executable JAR:
$ mvn clean verify -Pdist -Dquick
Run the following to add missing license headers e.g. when adding new source files:
$ mvn org.commonjava.maven.plugins:directory-maven-plugin:highest-basedir@resolve-rootdir license:format
Build with the dist profile as shown above, then execute this:
$ java -jar kroxylicious/target/kroxylicious-1.0-SNAPSHOT.jar -cp {path-to-your-class-path}
To prevent the following error:
Failed to load class org.slf4j.impl.StaticLoggerBinder
Make sure to follow the suggestions here to include one (and only one) of the suggested jars on the classpath.
The docs directory has some user documentation written in AsciiDoc format.
You can render it to HTML using:
./mvnw org.asciidoctor:asciidoctor-maven-plugin:process-asciidoc@convert-to-html
The output will be in target/html/master.html.
See benchmarking.md for information on running basic performance tests for this proxy.
This project uses Deptective 🕵 for monitoring its architecture and fails any violations, either in form of unwanted package dependencies or circular package dependencies. The target dependency model is configured in the deptective.json file. Any new package relationships need to be registered there.
To verify whether the code base adheres to that target model, run the following:
$ mvn clean verify -Dquick -Parchitecture-check -pl kroxylicious
In case of any architecture violations, the actual architecture can be visualized using GraphViz like so:
$ dot -Tpng kroxylicious/target/generated-sources/annotations/deptective.dot > kroxylicious-arch.png
Currently the project uses JDK 11 for the actual code and JDK 17 for tests. IntelliJ needs to be configured to use the "new Workspace Model" in order for it to understand this (and to be useful for things like debugging):
- Open the Settings dialog (
File > Settings) - Navigate to
Build, Execution, Deployment > Build tools > Maven > Importing. - Tick "Import using the new IntelliJ Workspace Model API (experimental)"
This code base is available under the Apache License, version 2.