Merge pull request #71 from robobario/add-0.8.0-docs

Add v0.8.0 docs

_data/kroxylicious.yml

@@ -1,6 +1,8 @@
 versions:
   - title: 'Development'
     url: '/kroxylicious'
+  - title: 'v0.8.0'
+    url: '/docs/v0.8.0/'
   - title: 'v0.7.0'
     url: '/docs/v0.7.0/'
   - title: 'v0.6.0'

docs/v0.8.0/_files/_assets/attributes.adoc

@@ -0,0 +1,44 @@
+// AsciiDoc settings
+:data-uri!:
+:doctype: book
+:experimental:
+:idprefix:
+:imagesdir: images
+:numbered:
+:sectanchors!:
+:sectnums:
+:source-highlighter: highlight.js
+:toc: left
+:linkattrs:
+:toclevels: 2
+:icons: font
+
+//Latest version
+:ProductVersion: 0.8
+:gitRef: releases/tag/v0.8.0
+:ApicurioVersion: 2.6.x
+
+//Proxy links
+:github: https://github.com/kroxylicious/kroxylicious
+:github-releases: https://github.com/kroxylicious/kroxylicious/{gitRef}
+:github-issues: https://github.com/kroxylicious/kroxylicious/issues[Kroxylicious issues^]
+:api-javadoc: https://javadoc.io/doc/io.kroxylicious/kroxylicious-api/{ProductVersion}
+:kms-api-javadoc: https://javadoc.io/doc/io.kroxylicious/kroxylicious-kms/{ProductVersion}
+:encryption-api-javadoc: https://javadoc.io/doc/io.kroxylicious/kroxylicious-encryption/{ProductVersion}
+:start-script: https://github.com/kroxylicious/kroxylicious/blob/{gitRef}/kroxylicious-app/src/assembly/kroxylicious-start.sh
+
+//Kafka links
+:ApacheKafkaSite: https://kafka.apache.org[Apache Kafka website^]
+:kafka-protocol: https://kafka.apache.org/protocol.html
+
+//java links
+:java-17-javadoc: https://docs.oracle.com/en/java/javase/17/docs/api
+
+//Vault links
+:hashicorp-vault: https://developer.hashicorp.com/vault
+
+//AWS links
+:aws:  https://docs.aws.amazon.com/
+
+// Apicurio links
+:apicurio-docs: https://www.apicur.io/registry/docs/apicurio-registry/{ApicurioVersion}/

docs/v0.8.0/_files/_assets/trademarks.adoc

@@ -0,0 +1,5 @@
+= Trademark notice
+
+* Hashicorp Vault is a registered trademark of HashiCorp, Inc.
+* AWS Key Management Service is a trademark of Amazon.com, Inc. or its affiliates.
+* Apache Kafka is a registered trademark of The Apache Software Foundation.

docs/v0.8.0/_files/assemblies/assembly-aws-kms.adoc

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

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

@@ -0,0 +1,14 @@
+// file included in the following:
+//
+// index.adoc
+
+[id='assembly-built-in-filters-{context}']
+= Built-in filters
+
+[role="_abstract"]
+Kroxylicious comes with a suite of built-in filters designed to enhance the functionality and security of your Kafka clusters.
+
+include::assembly-record-encryption-filter.adoc[leveloffset=+1]
+include::assembly-multi-tenancy-filter.adoc[leveloffset=+1]
+include::assembly-record-validation-filter.adoc[leveloffset=+1]
+include::../modules/oauthbearer/con-oauthbearer.adoc[leveloffset=+1]

docs/v0.8.0/_files/assemblies/assembly-hashicorp-vault.adoc

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

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

@@ -0,0 +1,31 @@
+// file included in the following:
+//
+// assembly-built-in-filters.adoc
+
+[id='assembly-multi-tenancy-filter-{context}']
+= (Preview) Multi-tenancy filter
+
+[role="_abstract"]
+Kroxylicious’s Multi-tenancy filter presents a single Kafka cluster to tenants as if it were multiple clusters.
+Operations are isolated to a single tenant by prefixing resources with an identifier.
+
+NOTE: This filter is currently in incubation and available as a preview. 
+We would not recommend using it in a production environment.
+
+The Multi-tenancy filter works by intercepting all Kafka RPCs (remote procedure calls) that reference resources, such as topic names and consumer group names:
+
+Request path:: On the request path, resource names are prefixed with a tenant identifier.
+Response path:: On the response path, the prefix is removed.
+
+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.
+
+To set up the filter, configure it in Kroxylicious.
+
+IMPORTANT: While the Multi-tenancy filter isolates operations on resources, it does not isolate user identities across tenants. 
+User authentication and ACLs (Access Control Lists) are shared across all tenants, meaning that identity is not scoped to individual tenants. 
+For more information on open issues related to this filter, see {github-issues}.
+
+NOTE: For more information on Kafka's support for multi-tenancy, see the {ApacheKafkaSite}.
+
+//configuring the multi-tenancy filter
+include::../modules/multi-tenancy/proc-multi-tenancy.adoc[leveloffset=+1]

docs/v0.8.0/_files/assemblies/assembly-overview.adoc

@@ -0,0 +1,24 @@
+// file included in the following:
+//
+// index.adoc
+
+[id='assembly-overview-{context}']
+= Kroxylicious overview
+
+[role="_abstract"]
+Kroxylicious is an Apache Kafka protocol-aware ("Layer 7") proxy designed to enhance Kafka-based systems.
+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. 
+Built-in filters are provided as part of the solution.
+
+Functioning as an intermediary, the Kroxylicious mediates communication between a Kafka cluster and its clients. 
+It takes on the responsibility of receiving, filtering, and forwarding messages.
+
+An API provides a convenient means for implementing custom logic within the proxy.
+
+[role="_additional-resources"]
+.Additional resources
+
+* {ApacheKafkaSite}
+
+//broker config (upstream)
+include::../modules/con-proxy-overview.adoc[leveloffset=+1]

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

@@ -0,0 +1,32 @@
+// file included in the following:
+//
+// assembly-built-in-filters.adoc
+
+[id='assembly-record-encryption-filter-{context}']
+= Record Encryption filter
+
+[role="_abstract"]
+Kroxylicious's Record Encryption filter enhances the security of Kafka messages.
+The filter uses industry-standard cryptographic techniques to apply encryption to Kafka messages, ensuring the confidentiality of data stored in the Kafka Cluster.
+Kroxylicious centralizes topic-level encryption, ensuring streamlined encryption across Kafka clusters.
+
+There are three steps to using the filter:
+
+1. Setting up a Key Management System (KMS).
+2. Establishing the encryption keys within the KMS that will be used to encrypt the topics.
+3. Configuring the filter within Kroxylicious.
+
+The filter integrates with a Key Management Service (KMS), which has ultimate responsibility for the safe storage of sensitive key material.
+The filter relies on a KMS implementation. 
+Currently, Kroxylicious integrates with either HashiCorp Vault or AWS Key Management Service. 
+You can provide implementations for your specific KMS systems. 
+Additional KMS support will be added based on demand.
+
+//overview of the record encryption process
+include::../modules/record-encryption/con-record-encryption-overview.adoc[leveloffset=+1]
+//setting up hashicorp vault
+include::assembly-hashicorp-vault.adoc[leveloffset=+1]
+//setting up AWS KMS
+include::assembly-aws-kms.adoc[leveloffset=+1]
+//configuring the record encryption filter
+include::../modules/record-encryption/proc-configuring-record-encryption-filter.adoc[leveloffset=+1]

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

@@ -0,0 +1,27 @@
+// file included in the following:
+//
+// assembly-built-in-filters.adoc
+
+[id='assembly-record-validation-filter-{context}']
+= (Preview) Record Validation
+
+[role="_abstract"]
+The Record Validation filter validates records sent by a producer.
+Only records that pass the validation are sent to the broker.
+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.
+
+The filter currently supports two modes of operation:
+
+1. Schema Validation ensures the content of the record conforms to a schema stored in an https://www.apicur.io/registry/[Apicurio Registry].
+2. JSON Syntax Validation ensures the content of the record contains syntactically valid JSON.
+
+Validation rules can be applied to check the content of the Kafka record key or value.
+
+If the validation fails, the product request is rejected and the producing application receives an error response.  The broker
+will not receive the rejected records.
+
+NOTE: This filter is currently in incubation and available as a preview.
+We would not recommend using it in a production environment.
+
+//configuring the record-validation filter
+include::../modules/record-validation/proc-record-validation.adoc[leveloffset=+1]

docs/v0.8.0/_files/index.adoc

@@ -0,0 +1,24 @@
+:experimental:
+include::_assets/attributes.adoc[]
+
+:context: proxy
+
+[id="using-book-{context}"]
+= Kroxylicious
+
+include::assemblies/assembly-overview.adoc[leveloffset=+1]
+
+//built-in filters
+include::assemblies/assembly-built-in-filters.adoc[leveloffset=+1]
+
+//community filters
+include::modules/con-community-filters.adoc[leveloffset=+1]
+
+//custom filters
+include::modules/con-custom-filters.adoc[leveloffset=+1]
+
+include::modules/con-deploying.adoc[leveloffset=+1]
+include::modules/con-operating.adoc[leveloffset=+1]
+
+//trademark notices
+include::_assets/trademarks.adoc[leveloffset=+1]

docs/v0.8.0/_files/modules/con-community-filters.adoc

@@ -0,0 +1,13 @@
+// file included in the following:
+//
+// index.adoc
+
+[id='con-community-filters-{context}']
+= Community filters
+
+[role="_abstract"]
+Community contributed filters are showcased in the
+https://github.com/kroxylicious/kroxylicious-community-gallery[Community Gallery^].
+
+NOTE: These filters are contributed by the community and are not managed or maintained by the Kroxylicious team. 
+Use them at your own risk.