|
| 1 | +{% raw %} |
| 2 | +<html> |
| 3 | + <head></head> |
| 4 | + <body> |
| 5 | + <div id="preamble"> |
| 6 | + <div class="sectionbody"> |
| 7 | + <div class="paragraph"> |
| 8 | + <p>Kroxylicious' composable filter chains and pluggable API mean that you can write your own filters to apply your own rules to the Kafka protocol, using the Java programming language.</p> |
| 9 | + </div> |
| 10 | + <div class="paragraph"> |
| 11 | + <p>In this quick start you will build a custom filter and use it to modify messages being sent to/consumed from Kafka, learn about filter configuration and running custom filters, and find a starting point for developing your own custom filters with your own rules and logic.</p> |
| 12 | + </div> |
| 13 | + </div> |
| 14 | + </div> |
| 15 | + <div class="sect1"> |
| 16 | + <h2 id="getting_started">1. Getting started</h2> |
| 17 | + <div class="sectionbody"> |
| 18 | + <div class="sect2"> |
| 19 | + <h3 id="prerequisites">1.1. Prerequisites</h3> |
| 20 | + <div class="paragraph"> |
| 21 | + <p>To start developing your own custom filters for Kroxylicious, you will need to install <a href="https://openjdk.org/projects/jdk/21/">JDK 21</a>.</p> |
| 22 | + </div> |
| 23 | + <div class="paragraph"> |
| 24 | + <p>You’ll also need to install the <a href="https://maven.apache.org/index.html">Apache Maven CLI</a> and one of either <a href="https://podman.io/docs/installation">Podman</a> or <a href="https://docs.docker.com/install/">Docker</a>.</p> |
| 25 | + </div> |
| 26 | + <div class="admonitionblock note"> |
| 27 | + <table> |
| 28 | + <tbody> |
| 29 | + <tr> |
| 30 | + <td class="icon"><i class="fa icon-note" title="Note"></i></td> |
| 31 | + <td class="content">If you are using Podman, you may encounter issues with the integration tests. There are instructions <a href="https://github.com/kroxylicious/kroxylicious/blob/main/DEV_GUIDE.md#running-integration-tests-on-podman">here</a> to resolve this.</td> |
| 32 | + </tr> |
| 33 | + </tbody> |
| 34 | + </table> |
| 35 | + </div> |
| 36 | + </div> |
| 37 | + <div class="sect2"> |
| 38 | + <h3 id="get_the_code">1.2. Get the code</h3> |
| 39 | + <div class="paragraph"> |
| 40 | + <p>The easiest way to learn how to build custom filters is with our <code>kroxylicious-sample</code> module, which contains some basic find-and-replace filters for you to experiment with. Begin by downloading the latest <code>kroxylicious-sample</code> sources from the <a href="https://github.com/kroxylicious/kroxylicious">Kroxylicious repository</a>.</p> |
| 41 | + </div> |
| 42 | + <div class="listingblock"> |
| 43 | + <div class="content"> |
| 44 | + <pre class="CodeRay highlight"><code data-lang="shell">git clone https://github.com/kroxylicious/kroxylicious.git |
| 45 | +cd kroxylicious |
| 46 | +git checkout v0.14.0</code></pre> |
| 47 | + </div> |
| 48 | + </div> |
| 49 | + </div> |
| 50 | + </div> |
| 51 | + </div> |
| 52 | + <div class="sect1"> |
| 53 | + <h2 id="build_the_sample_filter_project">2. Build the sample Filter project</h2> |
| 54 | + <div class="sectionbody"> |
| 55 | + <div class="paragraph"> |
| 56 | + <p>Building the sample project is easy! You can build the <code>kroxylicious-sample</code> jar either on its own or with the rest of the Kroxylicious project.</p> |
| 57 | + </div> |
| 58 | + <div class="paragraph"> |
| 59 | + <p>To build all of Kroxylicious, including the sample:</p> |
| 60 | + </div> |
| 61 | + <div class="listingblock"> |
| 62 | + <div class="content"> |
| 63 | + <pre class="CodeRay highlight"><code data-lang="shell">mvn verify -Pdist -Dquick</code></pre> |
| 64 | + </div> |
| 65 | + </div> |
| 66 | + <div class="paragraph"> |
| 67 | + <p>Note that the <code>quick</code> flag prevents tests from running. For more instructions about working with the build, see the <a href="https://github.com/kroxylicious/kroxylicious/blob/v0.14.0/DEV_GUIDE.md#build">Development Guide</a>.</p> |
| 68 | + </div> |
| 69 | + </div> |
| 70 | + </div> |
| 71 | + <div class="sect1"> |
| 72 | + <h2 id="run_the_built_sample_filter_in_a_proxy">3. Run the built sample Filter in a Proxy</h2> |
| 73 | + <div class="sectionbody"> |
| 74 | + <div class="paragraph"> |
| 75 | + <p>Build both <code>kroxylicious-sample</code> and <code>kroxylicious-app</code> with the <code>dist</code> profile as above, then run the following command:</p> |
| 76 | + </div> |
| 77 | + <div class="listingblock"> |
| 78 | + <div class="content"> |
| 79 | + <pre class="CodeRay highlight"><code data-lang="shell">KROXYLICIOUS_CLASSPATH="kroxylicious-sample/target/*" kroxylicious-app/target/kroxylicious-app-0.14.0-bin/kroxylicious-app-0.14.0/bin/kroxylicious-start.sh --config kroxylicious-sample/sample-proxy-config.yaml</code></pre> |
| 80 | + </div> |
| 81 | + </div> |
| 82 | + </div> |
| 83 | + </div> |
| 84 | + <div class="sect1"> |
| 85 | + <h2 id="configure_the_filter">4. Configure the Filter</h2> |
| 86 | + <div class="sectionbody"> |
| 87 | + <div class="paragraph"> |
| 88 | + <p>Filters can be added and removed by altering the <code>filterDefinitions</code> list in the <code>kroxylicious-sample/sample-proxy-config.yaml</code> file. You can also reconfigure the sample filters by changing the configuration values in this file.</p> |
| 89 | + </div> |
| 90 | + <div class="paragraph"> |
| 91 | + <p>The <strong>SampleFetchResponseFilter</strong> and <strong>SampleProduceRequestFilter</strong> each have two configuration values that must be specified for them to work:</p> |
| 92 | + </div> |
| 93 | + <div class="ulist"> |
| 94 | + <ul> |
| 95 | + <li> |
| 96 | + <p><code>findValue</code> - the string the filter will search for in the produce/fetch data</p> |
| 97 | + </li> |
| 98 | + <li> |
| 99 | + <p><code>replacementValue</code> - the string the filter will replace the value above with</p> |
| 100 | + </li> |
| 101 | + </ul> |
| 102 | + </div> |
| 103 | + <div class="sect2"> |
| 104 | + <h3 id="default_configuration">4.1. Default Configuration</h3> |
| 105 | + <div class="paragraph"> |
| 106 | + <p>The default configuration for <strong>SampleProduceRequestFilter</strong> is:</p> |
| 107 | + </div> |
| 108 | + <div class="listingblock"> |
| 109 | + <div class="content"> |
| 110 | + <pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">filterDefinitions</span>: |
| 111 | + - <span class="string"><span class="content">name: produce-request-filter</span></span> |
| 112 | + <span class="key">type</span>: <span class="string"><span class="content">SampleProduceRequestFilterFactory</span></span> |
| 113 | + <span class="key">config</span>: |
| 114 | + <span class="key">findValue</span>: <span class="string"><span class="content">foo</span></span> |
| 115 | + <span class="key">replacementValue</span>: <span class="string"><span class="content">bar</span></span></code></pre> |
| 116 | + </div> |
| 117 | + </div> |
| 118 | + <div class="paragraph"> |
| 119 | + <p>This means that it will search for the string <code>foo</code> in the produce data and replace all occurrences with the string <code>bar</code>. For example, if a Kafka Producer sent a produce request with data <code>{"myValue":"foo"}</code>, the filter would transform this into <code>{"myValue":"bar"}</code> and Kroxylicious would send that to the Kafka Broker instead.</p> |
| 120 | + </div> |
| 121 | + <div class="paragraph"> |
| 122 | + <p>The default configuration for <strong>SampleFetchResponseFilter</strong> is:</p> |
| 123 | + </div> |
| 124 | + <div class="listingblock"> |
| 125 | + <div class="content"> |
| 126 | + <pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">filterDefinitions</span>: |
| 127 | + - <span class="string"><span class="content">name: fetch-response-filter</span></span> |
| 128 | + <span class="key">type</span>: <span class="string"><span class="content">SampleFetchResponseFilterFactory</span></span> |
| 129 | + <span class="key">config</span>: |
| 130 | + <span class="key">findValue</span>: <span class="string"><span class="content">bar</span></span> |
| 131 | + <span class="key">replacementValue</span>: <span class="string"><span class="content">baz</span></span></code></pre> |
| 132 | + </div> |
| 133 | + </div> |
| 134 | + <div class="paragraph"> |
| 135 | + <p>This means that it will search for the string <code>bar</code> in the fetch data and replace all occurrences with the string <code>baz</code>. For example, if a Kafka Broker sent a fetch response with data <code>{"myValue":"bar"}</code>, the filter would transform this into <code>{"myValue":"baz"}</code> and Kroxylicious would send that to the Kafka Consumer instead.</p> |
| 136 | + </div> |
| 137 | + </div> |
| 138 | + <div class="sect2"> |
| 139 | + <h3 id="modify">4.2. Modify</h3> |
| 140 | + <div class="paragraph"> |
| 141 | + <p>Now that you know how the sample filters work, you can start modifying them! Replace the <code>SampleFilterTransformer</code> logic with your own code, change which messages they apply to, or whatever else you like!</p> |
| 142 | + </div> |
| 143 | + </div> |
| 144 | + </div> |
| 145 | + </div> |
| 146 | + </body> |
| 147 | +</html> |
| 148 | +{% endraw %} |
0 commit comments