Kroxylicious v0.18.0 release documentation 2025-11-28

_data/documentation/0_18_0.yaml

@@ -0,0 +1,77 @@
+docs:
+  - title: Proxy Quick Start
+    description: Start here if you're experimenting with the proxy for the first time.
+    tags:
+      - proxy
+    rank: '000'
+    path: html/proxy-quick-start
+  - title: Proxy guide
+    description: "Covers using the proxy, including configuration, security and operation."
+    tags:
+      - proxy
+    rank: '010'
+    path: html/kroxylicious-proxy
+  - title: Record Encryption quickstart
+    description: Shows how to use the proxy to provide an encryption at rest solution
+      for Apache Kafka
+    tags:
+      - record-encryption
+      - encryption-at-rest
+    rank: '011'
+    path: html/record-encryption-quickstart
+  - title: Kroxylicious Operator for Kubernetes
+    description: Describes how to deploy and run the Proxy in a Kubernetes environment
+      using the Kroxylicious Operator
+    tags:
+      - kubernetes
+    rank: '020'
+    path: html/kroxylicious-operator
+  - title: Record Encryption Guide
+    description: "Covers using the record encryption filter, including configuration,\
+      \ security and operation."
+    tags:
+      - filter
+    rank: '020'
+    path: html/record-encryption-guide
+  - title: Record Validation Guide
+    description: Covers using the record validation filter.
+    tags:
+      - filter
+    rank: '021'
+    path: html/record-validation-guide
+  - title: Multi-tenancy Guide
+    description: Covers using the multi-tenancy filter.
+    tags:
+      - filter
+    rank: '022'
+    path: html/multi-tenancy-guide
+  - title: SASL Inspection Guide
+    description: Covers using the SASL Inspection filter.
+    tags:
+      - filter
+    rank: '023'
+    path: html/sasl-inspection-guide
+  - title: Oauth Bearer Validation Guide
+    description: Covers using the Oauth Bearer validation filter.
+    tags:
+      - filter
+    rank: '023'
+    path: html/oauth-bearer-validation
+  - title: Developer Quick Start
+    description: Start here if you're developing a filter for the first time.
+    tags:
+      - developer
+    rank: '031'
+    path: html/developer-quick-start
+  - title: Kroxylicious Developer guide
+    description: Covers writing plugins for the proxy in the Java programming language
+    tags:
+      - developer
+    rank: '032'
+    path: html/developer-guide
+  - title: Kroxylicious Javadocs
+    description: The Java API documentation.
+    tags:
+      - developer
+    path: https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.18.0/index.html
+    rank: '033'

_data/kroxylicious.yml

@@ -1,3 +1,3 @@
 # The version number of the latest release
-latestRelease: 0.17.1
+latestRelease: 0.18.0
 

_data/release/0_18_0.yaml

@@ -0,0 +1,34 @@
+#
+# Copyright Kroxylicious Authors.
+#
+# Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+#
+
+releaseNotesUrl: https://github.com/kroxylicious/kroxylicious/releases/tag/v$(VERSION)/
+assetBaseUrl: https://github.com/kroxylicious/kroxylicious/releases/download/v$(VERSION)/
+assets:
+  - name: Proxy
+    description: The proxy application.
+    downloads:
+      - format: zip
+        path: kroxylicious-app-$(VERSION)-bin.zip
+      - format: tar.gz
+        path: kroxylicious-app-$(VERSION)-bin.tar.gz
+  - name: Operator
+    description: The Kubernetes operator.
+    downloads:
+      - format: zip
+        path: kroxylicious-operator-$(VERSION).zip
+      - format: tar.gz
+        path: kroxylicious-operator-$(VERSION).tar.gz
+images:
+  - name: Proxy
+    url: https://quay.io/repository/kroxylicious/kroxylicious?tab=tags
+    registry: quay.io/kroxylicious/kroxylicious
+    tag: $(VERSION)
+    digest: sha256:6c7f23a8134e681c4845b34e44ff73522addedd93963c4851eb4b784ff7879c4
+  - name: Operator
+    url: https://quay.io/repository/kroxylicious/operator?tab=tags
+    registry: quay.io/kroxylicious/operator
+    tag: $(VERSION)
+    digest: sha256:f0d6566accf8bd4eb67200875ff2ac2adaadca22a2e720646becd6da29328599

documentation/0.18.0/html/developer-guide/index.html

@@ -0,0 +1,10 @@
+---
+layout: guide
+title: Kroxylicious Developer guide
+description: Covers writing plugins for the proxy in the Java programming language
+tags:
+  - developer
+rank: '032'
+version: 0.18.0
+permalink: /documentation/0.18.0/html/developer-guide/
+---

documentation/0.18.0/html/developer-guide/toc.html

@@ -0,0 +1,19 @@
+{% raw %}
+<div id="toc" class="toc">
+ <ul class="sectlevel1">
+  <li><a href="#assembly-proxy-overview-proxy">1. Kroxylicious Proxy overview</a>
+   <ul class="sectlevel2">
+    <li><a href="#con-api-compatibility-developer-proxy">1.1. Compatibility</a></li>
+   </ul></li>
+  <li><a href="#con-custom-filters-proxy">2. Custom filters</a>
+   <ul class="sectlevel2">
+    <li><a href="#custom_filter_project_generation">2.1. Custom Filter Project Generation</a></li>
+    <li><a href="#api_docs">2.2. API docs</a></li>
+    <li><a href="#dependencies">2.3. Dependencies</a></li>
+    <li><a href="#protocol_filters">2.4. Protocol filters</a></li>
+    <li><a href="#packaging_filters">2.5. Packaging filters</a></li>
+   </ul></li>
+  <li><a href="#trademark_notice">3. Trademark notice</a></li>
+ </ul>
+</div>
+{% endraw %}

documentation/0.18.0/html/developer-quick-start/content.html

@@ -0,0 +1,172 @@
+{% raw %}
+<html>
+ <head></head>
+ <body>
+  <div id="preamble">
+   <div class="sectionbody">
+    <div class="paragraph _abstract">
+     <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>
+    </div>
+    <div class="paragraph">
+     <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>
+    </div>
+   </div>
+  </div>
+  <div class="sect1">
+   <h2 id="getting_started">1. Getting started</h2>
+   <div class="sectionbody">
+    <div class="sect2">
+     <h3 id="prerequisites">1.1. Prerequisites</h3>
+     <div class="paragraph">
+      <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>
+     </div>
+     <div class="paragraph">
+      <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>
+     </div>
+     <div class="admonitionblock note">
+      <table>
+       <tbody>
+        <tr>
+         <td class="icon"><i class="fa icon-note" title="Note"></i></td>
+         <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>
+        </tr>
+       </tbody>
+      </table>
+     </div>
+    </div>
+    <div class="sect2">
+     <h3 id="generate_a_sample_filter_project">1.2. Generate a Sample Filter Project</h3>
+     <div class="paragraph">
+      <p>The easiest way to learn how to build custom filters is with our <code>kroxylicious-filter-archetype</code> maven archetype, which will generate some basic find-and-replace filters for you to experiment with. Begin by generating a sample project:</p>
+     </div>
+     <div class="listingblock">
+      <div class="content">
+       <pre class="CodeRay highlight"><code data-lang="shell">mvn archetype:generate -DarchetypeGroupId=io.kroxylicious \
+                       -DarchetypeArtifactId=kroxylicious-filter-archetype \
+                       -DarchetypeVersion=0.18.0 \
+                       -DgroupId=org.example \
+                       -DartifactId=sample-filter \
+                       -Dversion=1.0-SNAPSHOT \
+                       -DinteractiveMode=false
+cd sample-filter</code></pre>
+      </div>
+     </div>
+    </div>
+   </div>
+  </div>
+  <div class="sect1">
+   <h2 id="build_the_sample_filter_project">2. Build the Sample Filter project</h2>
+   <div class="sectionbody">
+    <div class="paragraph">
+     <p>Building the sample project is easy!</p>
+    </div>
+    <div class="listingblock">
+     <div class="content">
+      <pre class="CodeRay highlight"><code data-lang="shell">mvn verify</code></pre>
+     </div>
+    </div>
+    <div class="paragraph">
+     <p>Note that the sample project includes automated unit and integration tests. The project’s powerful integration tests run against an in-VM Kafka cluster, enabling you to rapidly iterate on your filter’s business logic.</p>
+    </div>
+   </div>
+  </div>
+  <div class="sect1">
+   <h2 id="run_the_built_sample_filter_module_in_a_proxy">3. Run the built Sample Filter module in a Proxy</h2>
+   <div class="sectionbody">
+    <div class="paragraph">
+     <p>To build and run your sample filter</p>
+    </div>
+    <div class="listingblock">
+     <div class="content">
+      <pre class="CodeRay highlight"><code data-lang="shell">chmod +x run.sh
+./run.sh --config sample-proxy-config.yaml</code></pre>
+     </div>
+    </div>
+    <div class="paragraph">
+     <p>Send a Kafka message containing <code>foo</code> through the proxy. You should see the content transformed, with the word <code>foo</code> replaced by <code>baz</code> in the message received by the consumer.</p>
+    </div>
+    <div class="listingblock">
+     <div class="content">
+      <pre class="CodeRay highlight"><code data-lang="shell">podman run -it --net host \
+           --entrypoint /opt/kafka/bin/kafka-console-producer.sh \
+           apache/kafka:4.1.0 \
+           --bootstrap-server localhost:9192 \
+           --topic hello
+&gt;foo
+
+podman run -it --net host \
+           --entrypoint /opt/kafka/bin/kafka-console-consumer.sh \
+           apache/kafka:4.1.0 \
+           --bootstrap-server localhost:9192 \
+           --topic hello \
+           --from-beginning
+baz</code></pre>
+     </div>
+    </div>
+   </div>
+  </div>
+  <div class="sect1">
+   <h2 id="configure_the_filter">4. Configure the Filter</h2>
+   <div class="sectionbody">
+    <div class="paragraph">
+     <p>Filters can be added and removed by altering the <code>filterDefinitions</code> list in the <code>sample-proxy-config.yaml</code> file. You can also reconfigure the sample filters by changing the configuration values in this file. Note that the proxy must be restarted when you modify the configuration.</p>
+    </div>
+    <div class="paragraph">
+     <p>The <strong>SampleFetchResponseFilter</strong> and <strong>SampleProduceRequestFilter</strong> each have two configuration values that must be specified for them to work:</p>
+    </div>
+    <div class="ulist">
+     <ul>
+      <li>
+       <p><code>findValue</code> - the string the filter will search for in the produce/fetch data</p>
+      </li>
+      <li>
+       <p><code>replacementValue</code> - the string the filter will replace the value above with</p>
+      </li>
+     </ul>
+    </div>
+    <div class="sect2">
+     <h3 id="default_configuration">4.1. Default Configuration</h3>
+     <div class="paragraph">
+      <p>The default configuration for <strong>SampleProduceRequestFilter</strong> is:</p>
+     </div>
+     <div class="listingblock">
+      <div class="content">
+       <pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">filterDefinitions</span>:
+  - <span class="string"><span class="content">name: produce-request-filter</span></span>
+    <span class="key">type</span>: <span class="string"><span class="content">SampleProduceRequestFilterFactory</span></span>
+    <span class="key">config</span>:
+      <span class="key">findValue</span>: <span class="string"><span class="content">foo</span></span>
+      <span class="key">replacementValue</span>: <span class="string"><span class="content">bar</span></span></code></pre>
+      </div>
+     </div>
+     <div class="paragraph">
+      <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>
+     </div>
+     <div class="paragraph">
+      <p>The default configuration for <strong>SampleFetchResponseFilter</strong> is:</p>
+     </div>
+     <div class="listingblock">
+      <div class="content">
+       <pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">filterDefinitions</span>:
+  - <span class="string"><span class="content">name: fetch-response-filter</span></span>
+    <span class="key">type</span>: <span class="string"><span class="content">SampleFetchResponseFilterFactory</span></span>
+    <span class="key">config</span>:
+      <span class="key">findValue</span>: <span class="string"><span class="content">bar</span></span>
+      <span class="key">replacementValue</span>: <span class="string"><span class="content">baz</span></span></code></pre>
+      </div>
+     </div>
+     <div class="paragraph">
+      <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>
+     </div>
+    </div>
+    <div class="sect2">
+     <h3 id="modify">4.2. Modify</h3>
+     <div class="paragraph">
+      <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>
+     </div>
+    </div>
+   </div>
+  </div>
+ </body>
+</html>
+{% endraw %}

documentation/0.18.0/html/developer-quick-start/index.html

@@ -0,0 +1,10 @@
+---
+layout: guide
+title: Developer Quick Start
+description: Start here if you're developing a filter for the first time.
+tags:
+  - developer
+rank: '031'
+version: 0.18.0
+permalink: /documentation/0.18.0/html/developer-quick-start/
+---

documentation/0.18.0/html/developer-quick-start/toc.html

@@ -0,0 +1,18 @@
+{% raw %}
+<div id="toc" class="toc">
+ <ul class="sectlevel1">
+  <li><a href="#getting_started">1. Getting started</a>
+   <ul class="sectlevel2">
+    <li><a href="#prerequisites">1.1. Prerequisites</a></li>
+    <li><a href="#generate_a_sample_filter_project">1.2. Generate a Sample Filter Project</a></li>
+   </ul></li>
+  <li><a href="#build_the_sample_filter_project">2. Build the Sample Filter project</a></li>
+  <li><a href="#run_the_built_sample_filter_module_in_a_proxy">3. Run the built Sample Filter module in a Proxy</a></li>
+  <li><a href="#configure_the_filter">4. Configure the Filter</a>
+   <ul class="sectlevel2">
+    <li><a href="#default_configuration">4.1. Default Configuration</a></li>
+    <li><a href="#modify">4.2. Modify</a></li>
+   </ul></li>
+ </ul>
+</div>
+{% endraw %}