Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions documentation/0.13.0/html/developer-guide/content.html
Original file line number Diff line number Diff line change
Expand Up @@ -91,13 +91,13 @@ <h2 id="con-custom-filters-proxy">2. Custom filters</h2>
<div class="sect2">
<h3 id="sample_custom_filter_project">2.1. Sample Custom Filter Project</h3>
<div class="paragraph">
<p>A collection of sample filters is available within the Kroxylicious repository for you to download, try out, and customise. You can find them <a href="https://github.com/kroxylicious/kroxylicious/tree/main/kroxylicious-sample">here</a> for a hands-on introduction to creating your own custom filters.</p>
<p>A collection of sample filters is available within the Kroxylicious repository for you to download, try out, and customise. You can find them <a href="https://github.com/kroxylicious/kroxylicious/tree/v0.13.0/kroxylicious-sample">here</a> for a hands-on introduction to creating your own custom filters.</p>
</div>
</div>
<div class="sect2">
<h3 id="api_docs">2.2. API docs</h3>
<div class="paragraph">
<p>Custom filters are built by implementing interfaces supplied by the <a href="https://github.com/kroxylicious/kroxylicious/tree/main/kroxylicious-api" target="_blank" rel="noopener">kroxylicious-api</a> module (<a href="https://mvnrepository.com/artifact/io.kroxylicious/kroxylicious-api">io.kroxylicious:kroxylicious-api</a> on maven central). You can view the javadoc <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/package-summary.html" target="_blank" rel="noopener">here</a>.</p>
<p>Custom filters are built by implementing interfaces supplied by the <a href="https://github.com/kroxylicious/kroxylicious/tree/v0.13.0/kroxylicious-api" target="_blank" rel="noopener">kroxylicious-api</a> module (<a href="https://mvnrepository.com/artifact/io.kroxylicious/kroxylicious-api">io.kroxylicious:kroxylicious-api</a> on maven central). You can view the javadoc <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/package-summary.html" target="_blank" rel="noopener">here</a>.</p>
</div>
</div>
<div class="sect2">
Expand Down Expand Up @@ -138,7 +138,7 @@ <h4 id="specific_message_protocol_filters">2.4.1. Specific Message Protocol Filt
<div class="sect4">
<h5 id="examples">Examples</h5>
<div class="paragraph">
<p>To intercept all Fetch Requests your class would implement <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/FetchRequestFilter.html" target="_blank" rel="noopener">FetchRequestFilter</a>:</p>
<p>To intercept all Fetch Requests your class would implement <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/FetchRequestFilter.html" target="_blank" rel="noopener">FetchRequestFilter</a>:</p>
</div>
<div class="listingblock">
<div class="content">
Expand All @@ -156,7 +156,7 @@ <h5 id="examples">Examples</h5>
</div>
</div>
<div class="paragraph">
<p>To intercept all Fetch Responses your class would implement <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/FetchResponseFilter.html" target="_blank" rel="noopener">FetchResponseFilter</a>:</p>
<p>To intercept all Fetch Responses your class would implement <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/FetchResponseFilter.html" target="_blank" rel="noopener">FetchResponseFilter</a>:</p>
</div>
<div class="listingblock">
<div class="content">
Expand All @@ -174,7 +174,7 @@ <h5 id="examples">Examples</h5>
</div>
</div>
<div class="paragraph">
<p>To intercept all Fetch Requests and all Fetch Responses your class would implement <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/FetchRequestFilter.html" target="_blank" rel="noopener">FetchRequestFilter</a> and <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/FetchResponseFilter.html" target="_blank" rel="noopener">FetchResponseFilter</a>:</p>
<p>To intercept all Fetch Requests and all Fetch Responses your class would implement <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/FetchRequestFilter.html" target="_blank" rel="noopener">FetchRequestFilter</a> and <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/FetchResponseFilter.html" target="_blank" rel="noopener">FetchResponseFilter</a>:</p>
</div>
<div class="listingblock">
<div class="content">
Expand Down Expand Up @@ -213,10 +213,10 @@ <h4 id="requestresponse_protocol_filters">2.4.2. Request/Response Protocol Filte
<div class="ulist">
<ul>
<li>
<p><a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/RequestFilter.html" target="_blank" rel="noopener">RequestFilter</a> to intercept all requests.</p>
<p><a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/RequestFilter.html" target="_blank" rel="noopener">RequestFilter</a> to intercept all requests.</p>
</li>
<li>
<p><a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/ResponseFilter.html" target="_blank" rel="noopener">ResponseFilter</a> to intercept all responses.</p>
<p><a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/ResponseFilter.html" target="_blank" rel="noopener">ResponseFilter</a> to intercept all responses.</p>
</li>
</ul>
</div>
Expand Down Expand Up @@ -351,7 +351,7 @@ <h4 id="handling_state">2.4.5. Handling state</h4>
<p>The simplest way of managing per-client state is to use member fields. The proxy guarantees that all methods of a given filter instance will always be invoked on the same thread (also true of the CompletionStage completion in the case of <a href="#sending_asynchronous_requests_to_the_cluster">Sending asynchronous requests to the Cluster</a>). Therefore, there is no need to use synchronization when accessing such fields.</p>
</div>
<div class="paragraph">
<p>See the <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/package-summary.html#implementing.threadSafety" target="_blank" rel="noopener"><code>io.kroxylicious.proxy.filter</code></a> package javadoc for more information on thread-safety.</p>
<p>See the <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/package-summary.html#implementing.threadSafety" target="_blank" rel="noopener"><code>io.kroxylicious.proxy.filter</code></a> package javadoc for more information on thread-safety.</p>
</div>
</div>
<div class="sect3">
Expand Down Expand Up @@ -571,14 +571,14 @@ <h5 id="sending_asynchronous_requests_to_the_cluster">Sending asynchronous reque
</table>
</div>
<div class="paragraph">
<p>As you have read above, we need to know the API version we want our request to be encoded at. Your filter can discover what versions of an API the Kafka Cluster supports. To do this use the <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/ApiVersionsService.html" target="_blank" rel="noopener">ApiVersionsService</a> available from the <code>FilterContext</code> to determine programmatically what versions of an API are support and then write code to make a suitable <code>request</code> object.</p>
<p>As you have read above, we need to know the API version we want our request to be encoded at. Your filter can discover what versions of an API the Kafka Cluster supports. To do this use the <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/ApiVersionsService.html" target="_blank" rel="noopener">ApiVersionsService</a> available from the <code>FilterContext</code> to determine programmatically what versions of an API are support and then write code to make a suitable <code>request</code> object.</p>
</div>
<div class="admonitionblock note">
<table>
<tbody>
<tr>
<td class="icon"><i class="fa icon-note" title="Note"></i></td>
<td class="content">Kroxylicious provides the guarantee that computation stages chained using the <em>default execution methods</em> are executed on the same thread as the rest of the Filter work, so we can safely mutate Filter members without synchronising. See the <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/package-summary.html#implementing.threadSafety" target="_blank" rel="noopener"><code>io.kroxylicious.proxy.filter</code></a> package javadoc for more information on thread-safety.</td>
<td class="content">Kroxylicious provides the guarantee that computation stages chained using the <em>default execution methods</em> are executed on the same thread as the rest of the Filter work, so we can safely mutate Filter members without synchronising. See the <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/package-summary.html#implementing.threadSafety" target="_blank" rel="noopener"><code>io.kroxylicious.proxy.filter</code></a> package javadoc for more information on thread-safety.</td>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -630,10 +630,10 @@ <h5 id="filtering_specific_api_versions">Filtering specific API Versions</h5>
<div class="sect3">
<h4 id="filter_construction_and_configuration">2.4.7. Filter Construction and Configuration</h4>
<div class="paragraph">
<p>For Kroxylicious to instantiate and configure your custom filter we use Java’s <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/ServiceLoader.html" target="_blank" rel="noopener">ServiceLoader</a> API. Each Custom Filter should provide a corresponding <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13/io/kroxylicious/proxy/filter/FilterFactory.html" target="_blank" rel="noopener">FilterFactory</a> implementation that can create an instance of your custom Filter. The factory can optionally declare a configuration class that Kroxylicious will populate (using Jackson) when loading your custom Filter. The module must package a <code>META-INF/services/io.kroxylicious.proxy.filter.FilterFactory</code> file containing the classnames of each filter factory implementation into the JAR file.</p>
<p>For Kroxylicious to instantiate and configure your custom filter we use Java’s <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/ServiceLoader.html" target="_blank" rel="noopener">ServiceLoader</a> API. Each Custom Filter should provide a corresponding <a href="https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/0.13.0/io/kroxylicious/proxy/filter/FilterFactory.html" target="_blank" rel="noopener">FilterFactory</a> implementation that can create an instance of your custom Filter. The factory can optionally declare a configuration class that Kroxylicious will populate (using Jackson) when loading your custom Filter. The module must package a <code>META-INF/services/io.kroxylicious.proxy.filter.FilterFactory</code> file containing the classnames of each filter factory implementation into the JAR file.</p>
</div>
<div class="paragraph">
<p>For example in the kroxylicious-samples we have the <a href="https://github.com/kroxylicious/kroxylicious/blob/main/kroxylicious-sample/src/main/java/io/kroxylicious/sample/config/SampleFilterConfig.java">SampleFilterConfig</a> class. This is used in the <a href="https://github.com/kroxylicious/kroxylicious/blob/main/kroxylicious-sample/src/main/java/io/kroxylicious/sample/SampleFetchResponseFilter.java">SampleFetchResponseFilter</a>). The configuration is routed to the Filter instance via the <a href="https://github.com/kroxylicious/kroxylicious/blob/main/kroxylicious-sample/src/main/java/io/kroxylicious/sample/SampleFetchResponse.java">SampleFetchResponse</a>.</p>
<p>For example in the kroxylicious-samples we have the <a href="https://github.com/kroxylicious/kroxylicious/blob/v0.13.0/kroxylicious-sample/src/main/java/io/kroxylicious/sample/config/SampleFilterConfig.java">SampleFilterConfig</a> class. This is used in the <a href="https://github.com/kroxylicious/kroxylicious/blob/v0.13.0/kroxylicious-sample/src/main/java/io/kroxylicious/sample/SampleFetchResponseFilter.java">SampleFetchResponseFilter</a>). The configuration is routed to the Filter instance via the <a href="https://github.com/kroxylicious/kroxylicious/blob/v0.13.0/kroxylicious-sample/src/main/java/io/kroxylicious/sample/SampleFetchResponse.java">SampleFetchResponse</a>.</p>
</div>
<div class="paragraph">
<p>Then, when we configure a filter in Kroxylicious configuration like:</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ <h3 id="install-prereqs-operator">3.1. Install prerequisites</h3>
<div class="sect2">
<h3 id="downloads-operator">3.2. Kroxylicious release artifacts</h3>
<div class="paragraph _abstract">
<p>To use YAML manifest files to install Kroxylicious, download kroxylicious-operator-0.13.zip or kroxylicious-operator-0.13.tar.gz file from the <a href="https://github.com/kroxylicious/kroxylicious/releases" target="_blank" rel="noopener">GitHub releases page</a>, and extract the files as appropriate (for example using <code>unzip</code> or <code>tar -xzf</code>).</p>
<p>To use YAML manifest files to install Kroxylicious, download kroxylicious-operator-0.13.0.zip or kroxylicious-operator-0.13.0.tar.gz file from the <a href="https://github.com/kroxylicious/kroxylicious/releases" target="_blank" rel="noopener">GitHub releases page</a>, and extract the files as appropriate (for example using <code>unzip</code> or <code>tar -xzf</code>).</p>
</div>
<div class="paragraph">
<p>Each of these archives contains:</p>
Expand Down Expand Up @@ -205,7 +205,7 @@ <h3 id="install-cluster-operator-operator">3.3. Installing the Kroxylicious Oper
<p>You need an account with permission to create and manage <code>CustomResourceDefinition</code> and RBAC (<code>ClusterRole</code>) resources.</p>
</li>
<li>
<p>You have downloaded one of kroxylicious-operator-0.13.zip or kroxylicious-operator-0.13.tar.gz and extracted the contents into the current directory.</p>
<p>You have downloaded one of kroxylicious-operator-0.13.0.zip or kroxylicious-operator-0.13.0.tar.gz and extracted the contents into the current directory.</p>
</li>
</ul>
</div>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2677,7 +2677,7 @@ <h4 id="using_micrometer_with_filters">5.4.3. Using Micrometer with filters</h4>
<div class="sect2">
<h3 id="proc-proxy-setting-log-levels-proxy">5.5. Setting log levels</h3>
<div class="paragraph _abstract">
<p>The Kroxylicious <a href="https://github.com/kroxylicious/kroxylicious/tree/main" target="_blank" rel="noopener">binary distribution</a> includes <a href="https://logging.apache.org/log4j/2.x">log4j2</a> as the default logging backend.</p>
<p>The Kroxylicious <a href="https://github.com/kroxylicious/kroxylicious/releases/download/v0.13.0/kroxylicious-app-0.13.0-bin.zip" target="_blank" rel="noopener">binary distribution</a> includes <a href="https://logging.apache.org/log4j/2.x">log4j2</a> as the default logging backend.</p>
</div>
<div class="paragraph">
<p>When using the <code>bin/kroxylicious-start.sh</code> script from the binary distribution, you can set an environment variable to load a custom <code>log4j2</code> configuration file or change the root logging level.</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -408,7 +408,7 @@ <h5 id="establish_an_application_identity_for_the_filter">Establish an applicati
<div class="sect4">
<h5 id="testing_the_application_identity_for_the_filter_using_the_cli">Testing the application identity for the filter using the CLI</h5>
<div class="paragraph">
<p>To test whether the application identity and the policy are working correctly, a <a href="https://raw.githubusercontent.com/kroxylicious/kroxylicious/main/scripts/validate_vault_token.sh">script</a> can be used.</p>
<p>To test whether the application identity and the policy are working correctly, a <a href="https://raw.githubusercontent.com/kroxylicious/kroxylicious/v0.13.0/scripts/validate_vault_token.sh">script</a> can be used.</p>
</div>
<div class="paragraph">
<p>First, as the administrator, create a KEK in the hierarchy at this path <code>transit/keys/KEK_testkey</code>.</p>
Expand Down