Skip to content

Commit ce21fbe

Browse files
k-wallk-wall
committed
Prepare v0.11.0 release documentation
Signed-off-by: k-wall <[email protected]>
1 parent 160f7d8 commit ce21fbe

File tree

53 files changed

+3206
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+3206
-0
lines changed

‎_data/kroxylicious.yml

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
versions:
22
- title: 'Development'
33
url: '/kroxylicious'
4+
- title: 'v0.11.0'
5+
url: '/docs/v0.11.0/'
46
- title: 'v0.10.0'
57
url: '/docs/v0.10.0/'
68
- title: 'v0.9.0'

‎docs/v0.11.0/_files/_assets/attributes.adoc

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// AsciiDoc settings
2+
:data-uri!:
3+
:doctype: book
4+
:experimental:
5+
:idprefix:
6+
:imagesdir: images
7+
:numbered:
8+
:sectanchors!:
9+
:sectnums:
10+
:source-highlighter: highlight.js
11+
:toc: left
12+
:linkattrs:
13+
:toclevels: 2
14+
:icons: font
15+
16+
//Latest version
17+
:KroxyliciousVersion: 0.9
18+
:gitRef: releases/tag/v0.11.0
19+
:ApicurioVersion: 2.6.x
20+
21+
//Proxy links
22+
:github: https://github.com/kroxylicious/kroxylicious
23+
:github-releases: https://github.com/kroxylicious/kroxylicious/{gitRef}
24+
:github-issues: https://github.com/kroxylicious/kroxylicious/issues
25+
:api-javadoc: https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/{KroxyliciousVersion}
26+
:kms-api-javadoc: https://javadoc.io/doc/io.kroxylicious/kroxylicious-kms/{KroxyliciousVersion}
27+
:encryption-api-javadoc: https://javadoc.io/doc/io.kroxylicious/kroxylicious-encryption/{KroxyliciousVersion}
28+
:start-script: https://github.com/kroxylicious/kroxylicious/blob/{gitRef}/kroxylicious-app/src/assembly/kroxylicious-start.sh
29+
30+
//Kafka links
31+
:ApacheKafkaSite: https://kafka.apache.org[Apache Kafka website^]
32+
:kafka-protocol: https://kafka.apache.org/protocol.html
33+
34+
//java links
35+
:java-17-javadoc: https://docs.oracle.com/en/java/javase/17/docs/api
36+
:java-17-specs: https://docs.oracle.com/en/java/javase/17/docs/specs
37+
38+
//Vault links
39+
:hashicorp-vault: https://developer.hashicorp.com/vault
40+
41+
//Fortanix DSM links
42+
:fortanix-dsm: https://www.fortanix.com/platform/data-security-manager
43+
:fortanix-support: https://support.fortanix.com/
44+
45+
//AWS links
46+
:aws: https://docs.aws.amazon.com/
47+
48+
// Apicurio links
49+
:apicurio-docs: https://www.apicur.io/registry/docs/apicurio-registry/{ApicurioVersion}/
50+
51+
// Conditional inclusion flags
52+
:include-fortanix-dsm-kms: 1
53+
:include-aws-kms-service-config-identity-ec2-metadata: 1
54+
55+
//API stability markers.
56+
:unstable-api-version: denoted by a major version 0
57+
:stable-api-version: version 1.0.0

‎docs/v0.11.0/_files/_assets/trademarks.adoc

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
= Trademark notice
2+
3+
* Hashicorp Vault is a registered trademark of HashiCorp, Inc.
4+
* AWS Key Management Service is a trademark of Amazon.com, Inc. or its affiliates.
5+
ifdef::include-fortanix-dsm-kms[]
6+
* Fortanix and Data Security Manager are trademarks of Fortanix, Inc.
7+
endif::[]
8+
* Apache Kafka is a registered trademark of The Apache Software Foundation.

‎docs/v0.11.0/_files/assemblies/assembly-aws-kms.adoc

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// file included in the following:
2+
//
3+
// assembly-record-encryption-filter.adoc
4+
5+
[id='assembly-aws-kms-{context}']
6+
= Setting up AWS KMS
7+
8+
[role="_abstract"]
9+
To use {aws}/kms/latest/developerguide/overview.html[AWS Key Management Service] with the Record Encryption filter, use the following setup:
10+
11+
* Establish an AWS KMS aliasing convention for keys
12+
* Configure the AWS KMS
13+
* Create AWS KMS keys
14+
15+
You'll need a privileged AWS user that is capable of creating users and policies to perform the set-up.
16+
17+
include::../modules/record-encryption/aws-kms/con-aws-kms-setup.adoc[leveloffset=+1]
18+
include::../modules/record-encryption/aws-kms/con-aws-kms-service-config.adoc[leveloffset=+1]
19+
include::../modules/record-encryption/aws-kms/con-aws-kms-key-creation.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-built-in-filters.adoc

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// file included in the following:
2+
//
3+
// kroxylicious-proxy/index.adoc
4+
5+
[id='assembly-built-in-filters-{context}']
6+
= Built-in filters
7+
8+
[role="_abstract"]
9+
Kroxylicious comes with a suite of built-in filters designed to enhance the functionality and security of your Kafka clusters.
10+
11+
include::assembly-record-encryption-filter.adoc[leveloffset=+1]
12+
include::assembly-multi-tenancy-filter.adoc[leveloffset=+1]
13+
include::assembly-record-validation-filter.adoc[leveloffset=+1]
14+
include::../modules/oauthbearer/con-oauthbearer.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-configuring-proxy.adoc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[id='assembly-configuring-proxy-{context}']
2+
= Configuring proxies
3+
4+
[role="_abstract"]
5+
Fine-tune your deployment by configuring proxies to include additional features according to your specific requirements.
6+
7+
include::../modules/configuring/con-configuration-outline.adoc[leveloffset=+1]
8+
include::../modules/configuring/con-configuring-filters.adoc[leveloffset=+1]
9+
include::../modules/configuring/con-configuring-virtual-clusters.adoc[leveloffset=+1]
10+
include::../modules/configuring/con-configuring-vc-gateways.adoc[leveloffset=+1]
11+
include::../modules/configuring/con-configuring-vc-client-tls.adoc[leveloffset=+1]
12+
include::../modules/configuring/con-configuring-vc-target-tls.adoc[leveloffset=+1]
13+
14+
include::../modules/configuring/con-configuring-vc-other-settings.adoc[leveloffset=+1]
15+
include::../modules/configuring/con-configuring-toplevel-other-settings.adoc[leveloffset=+1]
16+
17+
include::../modules/configuring/ref-configuring-proxy-example.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-fortanix-dsm.adoc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// file included in the following:
2+
//
3+
// assembly-record-encryption-filter.adoc
4+
5+
[id='assembly-fortanix-dsm-{context}']
6+
= Setting up Fortanix Data Security Manager (DSM)
7+
8+
[role="_abstract"]
9+
To use Fortanix Data Security Manager (DSM) with the Record Encryption filter, use the following setup:
10+
11+
* Establish a naming convention for keys and decide in which group the keys will live
12+
* Create an application identity, with an API key, for use by the Record Encryption filter.
13+
* Create keys within Fortanix DSM.
14+
15+
include::../modules/record-encryption/fortanix-dsm/con-fortanix-dsm-setup.adoc[leveloffset=+1]
16+
include::../modules/record-encryption/fortanix-dsm/con-fortanix-dsm-service-config.adoc[leveloffset=+1]
17+
include::../modules/record-encryption/fortanix-dsm/con-fortanix-dsm-key-creation.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-hashicorp-vault.adoc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// file included in the following:
2+
//
3+
// assembly-record-encryption-filter.adoc
4+
5+
[id='assembly-hashicorp-vault-{context}']
6+
= Setting up HashiCorp Vault
7+
8+
[role="_abstract"]
9+
To use HashiCorp Vault with the Record Encryption filter, use the following setup:
10+
11+
* Enable the Transit Engine as the Record Encryption filter relies on its APIs.
12+
* Create a Vault policy specifically for the filter with permissions for generating and decrypting Data Encryption Keys (DEKs) for envelope encryption.
13+
* Obtain a Vault token that includes the filter policy.
14+
15+
include::../modules/record-encryption/hashicorp-vault/con-vault-setup.adoc[leveloffset=+1]
16+
include::../modules/record-encryption/hashicorp-vault/con-vault-service-config.adoc[leveloffset=+1]
17+
include::../modules/record-encryption/hashicorp-vault/con-vault-key-creation.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-monitoring-proxy.adoc

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// file included in the following:
2+
//
3+
// kroxylicious-proxy/index.adoc
4+
5+
[id='con-operating-{context}']
6+
= Monitoring proxies
7+
8+
[role="_abstract"]
9+
Monitoring data allows you to monitor the performance and health of proxy operations.
10+
You can configure your deployment to capture metrics data for analysis and notifications.
11+
12+
* Introduce custom logging configurations using `log4j2` and set appropriate root log levels.
13+
* Set up an admin HTTP endpoint for Prometheus metrics scraping.
14+
* Integrate Micrometer for enhanced observability.
15+
* Configure common tags and standard binders for JVM and system metrics to ensure comprehensive monitoring and efficient proxy operation.
16+
17+
include::../modules/monitoring/proc-introducing-metrics.adoc[leveloffset=+1]
18+
include::../modules/monitoring/con-setting-logs.adoc[leveloffset=+1]
19+
include::../modules/monitoring/con-integrating-micrometer.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-multi-tenancy-filter.adoc

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
// file included in the following:
2+
//
3+
// assembly-built-in-filters.adoc
4+
5+
[id='assembly-multi-tenancy-filter-{context}']
6+
= (Preview) Multi-tenancy filter
7+
8+
[role="_abstract"]
9+
Kroxylicious’s Multi-tenancy filter presents a single Kafka cluster to tenants as if it were multiple clusters.
10+
Operations are isolated to a single tenant by prefixing resources with an identifier.
11+
12+
NOTE: This filter is currently in incubation and available as a preview.
13+
We would not recommend using it in a production environment.
14+
15+
The Multi-tenancy filter works by intercepting all Kafka RPCs (remote procedure calls) that reference resources, such as topic names and consumer group names:
16+
17+
Request path:: On the request path, resource names are prefixed with a tenant identifier.
18+
Response path:: On the response path, the prefix is removed.
19+
20+
Kafka RPCs that list resources are filtered so that only resources belonging to the tenant are returned, effectively creating a private cluster experience for each tenant.
21+
22+
To set up the filter, configure it in Kroxylicious.
23+
24+
IMPORTANT: While the Multi-tenancy filter isolates operations on resources, it does not isolate user identities across tenants.
25+
User authentication and ACLs (Access Control Lists) are shared across all tenants, meaning that identity is not scoped to individual tenants.
26+
For more information on open issues related to this filter, see {github-issues}[Kroxylicious issues^].
27+
28+
NOTE: For more information on Kafka's support for multi-tenancy, see the {ApacheKafkaSite}.
29+
30+
//configuring the multi-tenancy filter
31+
include::../modules/multi-tenancy/proc-multi-tenancy.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-overview.adoc

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// file included in the following:
2+
//
3+
// kroxylicious-proxy/index.adoc
4+
5+
[id='assembly-overview-{context}']
6+
= Kroxylicious overview
7+
8+
[role="_abstract"]
9+
Kroxylicious is an Apache Kafka protocol-aware ("Layer 7") proxy designed to enhance Kafka-based systems.
10+
Through its filter mechanism it allows additional behavior to be introduced into a Kafka-based system without requiring changes to either your applications or the Kafka cluster itself.
11+
Built-in filters are provided as part of the solution.
12+
13+
Functioning as an intermediary, the Kroxylicious mediates communication between a Kafka cluster and its clients.
14+
It takes on the responsibility of receiving, filtering, and forwarding messages.
15+
16+
An API provides a convenient means for implementing custom logic within the proxy.
17+
18+
[role="_additional-resources"]
19+
.Additional resources
20+
21+
* {ApacheKafkaSite}

‎docs/v0.11.0/_files/assemblies/assembly-record-encryption-filter.adoc

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// file included in the following:
2+
//
3+
// assembly-built-in-filters.adoc
4+
5+
[id='assembly-record-encryption-filter-{context}']
6+
= Record Encryption filter
7+
8+
[role="_abstract"]
9+
Kroxylicious's Record Encryption filter enhances the security of Kafka messages.
10+
The filter uses industry-standard cryptographic techniques to apply encryption to Kafka messages, ensuring the confidentiality of data stored in the Kafka Cluster.
11+
Kroxylicious centralizes topic-level encryption, ensuring streamlined encryption across Kafka clusters.
12+
13+
There are three steps to using the filter:
14+
15+
1. Setting up a Key Management System (KMS).
16+
2. Establishing the encryption keys within the KMS that will be used to encrypt the topics.
17+
3. Configuring the filter within Kroxylicious.
18+
19+
The filter integrates with a Key Management Service (KMS), which has ultimate responsibility for the safe storage of sensitive key material.
20+
The filter relies on a KMS implementation.
21+
Currently, Kroxylicious integrates with either HashiCorp Vault or AWS Key Management Service.
22+
You can provide implementations for your specific KMS systems.
23+
Additional KMS support will be added based on demand.
24+
25+
//overview of the record encryption process
26+
include::../modules/record-encryption/con-record-encryption-overview.adoc[leveloffset=+1]
27+
//setting up hashicorp vault
28+
include::assembly-hashicorp-vault.adoc[leveloffset=+1]
29+
//setting up AWS KMS
30+
include::assembly-aws-kms.adoc[leveloffset=+1]
31+
ifdef::include-fortanix-dsm-kms[]
32+
include::assembly-fortanix-dsm.adoc[leveloffset=+1]
33+
endif::[]
34+
//configuring the record encryption filter
35+
include::../modules/record-encryption/proc-configuring-record-encryption-filter.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/assemblies/assembly-record-validation-filter.adoc

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// file included in the following:
2+
//
3+
// assembly-built-in-filters.adoc
4+
5+
[id='assembly-record-validation-filter-{context}']
6+
= (Preview) Record Validation filter
7+
8+
[role="_abstract"]
9+
The Record Validation filter validates records sent by a producer.
10+
Only records that pass the validation are sent to the broker.
11+
This filter can be used to prevent _poison messages_—such as those containing corrupted data or invalid formats—from entering the Kafka system, which may otherwise lead to consumer failure.
12+
13+
The filter currently supports two modes of operation:
14+
15+
1. Schema Validation ensures the content of the record conforms to a schema stored in an https://www.apicur.io/registry/[Apicurio Registry].
16+
2. JSON Syntax Validation ensures the content of the record contains syntactically valid JSON.
17+
18+
Validation rules can be applied to check the content of the Kafka record key or value.
19+
20+
If the validation fails, the product request is rejected and the producing application receives an error response. The broker
21+
will not receive the rejected records.
22+
23+
NOTE: This filter is currently in incubation and available as a preview.
24+
We would not recommend using it in a production environment.
25+
26+
//configuring the record-validation filter
27+
include::../modules/record-validation/proc-record-validation.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/index.adoc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
= Kroxylicious guides
2+
3+
This release of Kroxylicious is documented in the following guides:
4+
5+
link:kroxylicious-proxy/[Proxy guide]:: Covers using the proxy, including configuration, security and operation.
6+
7+
// Developer's guide:: Covers writing plugins for the proxy in the Java programming language
8+
9+
// Operator for Kubernetes:: Covers the operator for running the proxy on Kubernetes

‎docs/v0.11.0/_files/kroxylicious-proxy/_assets

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../_assets

‎docs/v0.11.0/_files/kroxylicious-proxy/assemblies

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../assemblies

‎docs/v0.11.0/_files/kroxylicious-proxy/index.adoc

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
:experimental:
2+
include::_assets/attributes.adoc[]
3+
4+
:context: proxy
5+
6+
[id="using-book-{context}"]
7+
= Kroxylicious
8+
9+
include::assemblies/assembly-overview.adoc[leveloffset=+1]
10+
//broker config
11+
include::modules/con-proxy-overview.adoc[leveloffset=+2]
12+
include::modules/con-api-compatability.adoc[leveloffset=+2]
13+
14+
//built-in filters
15+
include::assemblies/assembly-built-in-filters.adoc[leveloffset=+1]
16+
17+
//community filters
18+
include::modules/con-community-filters.adoc[leveloffset=+1]
19+
20+
//custom filters
21+
include::modules/con-custom-filters.adoc[leveloffset=+1]
22+
23+
//configuring
24+
include::assemblies/assembly-configuring-proxy.adoc[leveloffset=+1]
25+
26+
//monitoring
27+
include::assemblies/assembly-monitoring-proxy.adoc[leveloffset=+1]
28+
29+
//trademark notices
30+
include::_assets/trademarks.adoc[leveloffset=+1]

‎docs/v0.11.0/_files/kroxylicious-proxy/modules

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules

‎docs/v0.11.0/_files/modules/con-api-compatability.adoc

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Module included in the following:
2+
//
3+
// assembly-overview.adoc
4+
5+
[id='con-api-compatibility{context}']
6+
= Compatibility
7+
8+
[id='con-api-compatibility-api{context}']
9+
== APIs
10+
11+
Kroxylicious follows https://semver.org/#semantic-versioning-200[Semantic Versioning] rules. While we are still in the initial development phase ({unstable-api-version}), we still take API compatibility very seriously. We aim to provide at least two minor releases between deprecation and the removal of that deprecated item.
12+
13+
We also consider our configuration file syntax a public API (though not the Java model backing it). As such, the syntax follows the same Semantic Versioning and deprecation rules.
14+
15+
Kubernetes custom resources are a public API, and we are making every effort to evolve Kroxylicious custom resources in line with https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/[Kubernetes best practices]. Kubernetes resources have their own versioning scheme, which is independent of the Kroxylicious proxy service version. As a result, we may reach {stable-api-version} of Kroxylicious while still using alpha or beta versions of the custom resources.
16+
17+
[id='con-api-compatibility-third-party{context}']
18+
=== Third-party plugins
19+
20+
Kroxylicious supports loading third-party plugins to extend the core functionality of the project. While these plugins are configured and loaded as first-class entities within Kroxylicious, we cannot guarantee the compatibility of their APIs or configuration properties.
21+
22+
We do however hold filters and plugins provided by the project to the same standards as the rest of the public API.
23+
24+
[id='con-api-compatibility-wire-protocol{context}']
25+
== Wire protocol
26+
27+
Kroxylicious offers the same backwards and forwards compatibility guarantees as https://kafka.apache.org/protocol#protocol_compatibility[Apache Kafka]. We support the same range of client and broker versions as the official Apache Kafka Java client.

0 commit comments

Comments
 (0)