Kroxylicious

https://kroxylicious.io/documentation
Admin
Kroxylicious is an open-source proxy for Apache Kafka that enables advanced filtering, encryption,...
Tokens:291,736
Snippets:2,711
Trust Score:7.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start Minikube Cluster

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Starts a Minikube Kubernetes cluster. Defaults are suitable for this quickstart.

```bash
$ minikube start

```

--------------------------------

### Start Kroxylicious Proxy

Source: https://kroxylicious.io/documentation/0.20.0/html/proxy-quick-start

Start the Kroxylicious proxy using the provided script, pointing to your configuration file. Use a custom configuration by replacing the file path after the --config flag.

```bash
cd kroxylicious-app-0.20.0

./bin/kroxylicious-start.sh --config config/example-proxy-config.yaml
```

--------------------------------

### Configure Standard Micrometer Binders

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Example configuration for registering standard Micrometer binders to expose JVM and system metrics.

```yaml
micrometer:
  - type: "StandardBindersHook"
    config:
      binderNames:
      - "JvmGcMetrics"
      - "JvmHeapPressureMetrics"
```

--------------------------------

### Example Kroxylicious Configuration with Record Encryption

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

This configuration demonstrates setting up the Record Encryption filter using Vault as the KMS. It includes details for KMS configuration, TLS authentication, and virtual cluster setup with gateway definitions.

```yaml
filterDefinitions:
  - name: encryption
    type: RecordEncryption
    config:
      kms: VaultKmsService
      kmsConfig:
        vaultTransitEngineUrl: https://vault.vault.svc.cluster.local:8200/v1/transit
        vaultToken:
          passwordFile: /opt/proxy/server/token.txt
        tls:
          key:
            storeFile: /opt/cert/server.p12
            storePassword:
              passwordFile: /opt/cert/store.password
            keyPassword:
              passwordFile: /opt/cert/key.password
            storeType: PKCS12
      selector: TemplateKekSelector
      selectorConfig:
        template: "$(topicName)"
defaultFilters:
  - encryption
virtualClusters:
  - name: my-cluster-proxy
    targetCluster:
      bootstrapServers: my-cluster-kafka-bootstrap.kafka.svc.cluster.local:9093
      bootstrapServerSelection:
        strategy: "round-robin"
      tls:
        trust:
          storeFile: /opt/proxy/trust/ca.p12
          storePassword:
            passwordFile: /opt/proxy/trust/ca.password
    gateways:
    - name: mygateway
      sniHostIdentifiesNode:
        bootstrapAddress: my-cluster-proxy.kafka:9092
        advertisedBrokerAddressPattern: broker$(nodeId).my-cluster-proxy.kafka
      tls:
        key:
          storeFile: /opt/proxy/server/key-material/keystore.p12
          storePassword:
            passwordFile: /opt/proxy/server/keystore-password/storePassword

```

--------------------------------

### KafkaProxyIngress Status Example

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

This example demonstrates the status of a KafkaProxyIngress resource when its spec.proxyRef exists. It includes the observedGeneration and the ResolvedRefs condition.

```yaml
kind: KafkaProxyIngress
apiVersion: kroxylicious.io/v1alpha1
metadata:
  name: cluster-ip
  namespace: my-proxy
  generation: 12
spec:
  # ...
status:
  observedGeneration: 12 __**(1)**
  conditions:
    - type: ResolvedRefs __**(2)**
      status: True __**(3)**
      observedGeneration: 12
```

--------------------------------

### Basic KafkaProxy configuration

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Example configuration for a KafkaProxy resource. An empty `spec` utilizes default proxy settings.

```yaml
kind: KafkaProxy
apiVersion: kroxylicious.io/v1alpha1
metadata:
  namespace: my-proxy
  name: simple
spec: {}
```

--------------------------------

### Start Minikube Tunnel

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Enable the Minikube Load Balancer tunnel by running this command in a separate console window. The command must remain running for the tunnel to function.

```bash
minikube tunnel
```

--------------------------------

### Example Metrics Output from Prometheus Scrape

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Example metrics returned from a Prometheus scrape request after configuring Micrometer integration.

```text
jvm_gc_memory_allocated_bytes_total{zone="euc-1a",} 0.0
```

--------------------------------

### Configure Target Cluster with Default Bootstrap Server Selection

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

This example shows how to configure the target cluster's bootstrap servers. When no explicit strategy is set, 'round-robin' is used by default.

```yaml
#...
virtualClusters:
    - name: my-cluster-proxy
      # ...
      targetCluster:
        bootstrapServers: my-cluster-kafka-bootstrap-0.kafka.svc.cluster.local:9093,my-cluster-kafka-bootstrap-1.kafka.svc.cluster.local:9093,my-cluster-kafka-bootstrap-2.kafka.svc.cluster.local:9093
        tls: {}
#...
```

--------------------------------

### Vault Transit Engine URL Examples

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-guide

Examples of Vault Transit Engine URLs with and without namespacing, and with a custom path.

```shell
https://myvaultinstance:8200/v1/transit
```

```shell
https://myvaultinstance:8200/v1/a/b/transit
```

```shell
https://myvaultinstance:8200/v1/mytransit
```

--------------------------------

### Configure Target Cluster with Explicit Round-Robin Bootstrap Server Selection

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

This example explicitly configures the 'round-robin' strategy for selecting a bootstrap server from the provided list.

```yaml
#...
virtualClusters:
  - name: my-cluster-proxy
    #...
    targetCluster:
      bootstrapServers: my-cluster-kafka-bootstrap-0.kafka.svc.cluster.local:9093,my-cluster-kafka-bootstrap-1.kafka.svc.cluster.local:9093,my-cluster-kafka-bootstrap-2.kafka.svc.cluster.local:9093
      bootstrapServerSelection:
        strategy: "round-robin" __**(1)**
      tls: {}
#...
```

--------------------------------

### VirtualKafkaCluster Status Example

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

This example shows the status of a VirtualKafkaCluster resource when all referenced resources exist. It highlights the observedGeneration and the ResolvedRefs condition.

```yaml
kind: VirtualKafkaCluster
apiVersion: kroxylicious.io/v1alpha1
metadata:
  # ...
  generation: 12
spec:
  # ...
status:
  observedGeneration: 12 __**(1)**
  conditions:
    - type: ResolvedRefs __**(2)**
      status: True __**(3)**
      observedGeneration: 12
```

--------------------------------

### Example FilterDefinitions for Record Encryption with Vault KMS

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-guide

An example of how to define the RecordEncryption filter within the `filterDefinitions` in a Kroxylicious Proxy configuration file, specifically for Vault KMS.

```yaml
filterDefinitions:
  - name: my-encryption-filter
    type: RecordEncryption
    config:
      kms: VaultKmsService
      kmsConfig:
        vaultTransitEngineUrl: # ...
        tls: # ...
        vaultToken:
          passwordFile: /opt/vault/token
      selector: TemplateKekSelector
      selectorConfig:
        template: "KEK-$(topicName)"
      unresolvedKeyPolicy: PASSTHROUGH_UNENCRYPTED
      experimental:
        encryptionDekRefreshAfterWriteSeconds: 3600
        encryptionDekExpireAfterWriteSeconds: 7200
        maxEncryptionsPerDek: 5000000
```

--------------------------------

### Example KafkaProxyIngress for loadBalancer

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

This configuration demonstrates how to set up the `loadBalancer` ingress type for Kroxylicious. It includes the `bootstrapAddress` and `advertisedBrokerAddressPattern` which are crucial for off-cluster access and broker routing.

```yaml
kind: KafkaProxyIngress
apiVersion: kroxylicious.io/v1alpha1
metadata:
  namespace: my-proxy
  name: load-balancer
spec:
  proxyRef:
    name: simple
  loadBalancer:
    bootstrapAddress: "$(virtualClusterName).kafkaproxy.example.com"
    advertisedBrokerAddressPattern: "broker-$(nodeId).$(virtualClusterName).kafkaproxy.example.com"

```

--------------------------------

### Configure Micrometer Integration with Common Tags and JVM GC Metrics

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Example proxy configuration for Micrometer integration. This sets up common tags for metrics and registers the JvmGcMetrics binder.

```yaml
management:
  endpoints:
    prometheus: {}
micrometer:
  - type: "CommonTagsHook" 
    config:
      commonTags:
        zone: "euc-1a" 
  - type: "StandardBindersHook" 
    config:
      binderNames:
      - "JvmGcMetrics" 
```

--------------------------------

### Kroxylicious Filter Definition and Application Example

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Demonstrates how to define filters globally and apply them as defaults or to specific virtual clusters. This allows for flexible and reusable filter configurations.

```yaml
filterDefinitions:
  - name: encryption
    type: RecordEncryption
    config:
      # ...
  - name: validation
    type: RecordValidation
    config:
      # ...
  - name: special-encryption
    type: RecordEncryption
    config:
      # ...
defaultFilters:
  - validation
  - encryption
virtualClusters:
  - name: my-proxy-with-default-filters
    # ...
  - name: my-proxy-with-custom-filters
    filters:
      - validation
      - special-encryption
    # ...

```

--------------------------------

### Install HashiCorp Vault KMS with Helm

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Installs HashiCorp Vault using Helm for standalone use on Minikube, enabling the Transit Secrets Engine required for record encryption.

```bash
$ helm repo add --force-update hashicorp https://helm.releases.hashicorp.com
$ helm upgrade --install vault hashicorp/vault --namespace kms --create-namespace --version 0.32.0 --set server.dev.enabled=true,server.dev.devRootToken=myroottoken --wait

```

--------------------------------

### Install Strimzi Operator with Helm

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Installs the Strimzi Operator using Helm, which is used to deploy and manage the Kafka cluster that Kroxylicious will proxy.

```bash
$ helm repo add --force-update strimzi https://strimzi.io/charts/
$ helm upgrade --install strimzi-operator strimzi/strimzi-kafka-operator --namespace kafka --create-namespace --version 0.51.0

```

--------------------------------

### Install LocalStack KMS with Helm

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Installs AWS LocalStack using Helm to serve as a Key Management Service (KMS). This is for development and testing purposes.

```bash
$ helm repo add --force-update localstack-repo https://helm.localstack.cloud
$ helm upgrade --install localstack localstack-repo/localstack --namespace kms --create-namespace --version 0.6.27 --set image.tag=4.14.0@sha256:3ebc37595918b8accb852f8048fef2aff047d465167edd655528065b07bc364a --set service.type=ClusterIP --wait

```

--------------------------------

### Check Java Version

Source: https://kroxylicious.io/documentation/0.20.0/html/proxy-quick-start

Verify that Java 21 or higher is installed. If this command fails, you may need to install a JRE or add it to your system’s PATH variable.

```bash
java -version
```

--------------------------------

### Deploy Kroxylicious with Record Encryption

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Applies the Kroxylicious configuration for record encryption. This assumes the example configuration is available locally.

```bash
$ kubectl apply -f examples/record-encryption/
```

--------------------------------

### Basic Kroxylicious Configuration Outline

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Illustrates the fundamental structure of a Kroxylicious configuration file, including filter definitions, default filters, and virtual cluster setup. Use this as a template for your own configurations.

```yaml
filterDefinitions:
  - name: example
    type: org.example.filter.Example
    config:
      # ...
defaultFilters:
  - example
virtualClusters:
  - name: my-cluster-proxy
    targetCluster:
      # ...
    gateways:
    - name: ...
      # ...
    subjectBuilder:
      # ...

# ...

```

--------------------------------

### Run Kafka in Docker

Source: https://kroxylicious.io/documentation/0.20.0/html/proxy-quick-start

Deploy a Kafka service in a container using Podman. This is an easy way to set up a Kafka cluster if you have a container engine installed.

```bash
podman pull apache/kafka:4.2.0
podman run -p 9092:9092 apache/kafka:4.2.0
```

--------------------------------

### Configure DNS Mappings

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Example DNS mappings required for load balancer ingress. These ensure that bootstrap and broker names resolve to the external address of the load balancer.

```dns
my-cluster.kafkaproxy.example.com => <external address>
broker-0.my-cluster.kafkaproxy.example.com => <external address>
broker-1.my-cluster.kafkaproxy.example.com => <external address>
broker-2.my-cluster.kafkaproxy.example.com => <external address>
```

--------------------------------

### Get and Initialize Plugin Instance in FilterFactory

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/plugin/package-summary.html

Demonstrates how to obtain and initialize a configured plugin instance (HttpGetter) within a FilterFactory using the FilterFactoryContext.

```java
 class FooFilterFactory implements FilterFactory<FooFilterConfig, Void> {
     Void initialize(FilterFactoryContext context, FooFilterConfig config) {
       // get the configured HttpGetter
       this.httpGetter = context.pluginInstance(HttpGetter.class, config.httpGetterPluginImplName());
       // initialize it
       this.httpGetter.configure(config.httpGetterConfig());
       return null;
     }
     Filter createFilter(FilterFactoryContext context, Void v) {
         return new Filter() {
           // use the httpGetter
         };
     }
 }
 
```

--------------------------------

### Configure TLS Client Authentication with PKCS #12 Truststore

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Example of setting up TLS client authentication for a gateway using a PKCS #12 truststore. This ensures clients present valid certificates signed by trusted CAs.

```yaml
virtualClusters:
  - name: my-cluster-proxy
    # ...
    gateways:
    - name: mygateway
      # ...
      tls:
        key:
           # ...
        trust:
          storeFile: <path>/trust.p12 __**(1)**
          storePassword:
            passwordFile: <path>/trust.password __**(2)**
          storeType: PKCS12 __**(3)**
          trustOptions:
            clientAuth: REQUIRED __**(4)**
```

--------------------------------

### Example Port Identifies Node Gateway Configuration

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

This configuration sets up a gateway using the Port Identifies Node scheme. It specifies the bootstrap address for client connections. Ensure the bootstrap address is resolvable and routable by the Kafka client.

```yaml
virtualClusters:
  - name: my-cluster-proxy
    # ...
    gateways:
    - name: mygateway
      portIdentifiesNode:
        bootstrapAddress: localhost:9192 __**(1)**
    # ...
```

--------------------------------

### Example KafkaProxyIngress for openShiftRoute

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

This configuration shows how to use the `openShiftRoute` ingress type, which is specific to OpenShift environments. It leverages OpenShift Routes for off-cluster access and automatically generates bootstrap and broker addresses.

```yaml
kind: KafkaProxyIngress
apiVersion: kroxylicious.io/v1alpha1
metadata:
  namespace: my-proxy
  name: openshift-route
spec:
  proxyRef:
    name: simple
  openShiftRoute: {}

```

--------------------------------

### KmsService.initialize(C)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/index-all.html

Initialises the service.

```APIDOC
## KmsService.initialize(C)

### Description
Initialises the service.

### Method
(Not specified, likely a Java method call)

### Endpoint
(Not applicable, this is an interface method)

### Parameters
- **C** - Configuration object for the service.

### Response
(No return type specified, likely void or a status indicator.)
```

--------------------------------

### Example KafkaProtocolFilter Resource for Multi-tenancy on Kubernetes

Source: https://kroxylicious.io/documentation/0.20.0/html/multi-tenancy-guide

Configure the MultiTenant filter within a `KafkaProtocolFilter` resource for Kroxylicious deployments on Kubernetes. The `configTemplate.prefixResourceNameSeparator` option customizes the separator used for tenant prefixes.

```yaml
kind: KafkaProtocolFilter
metadata:
  name: my-validation-filter
spec:
  type: MultiTenant
  configTemplate:
    prefixResourceNameSeparator: "." __**(1)**
```

--------------------------------

### Run Sample Filter in Proxy

Source: https://kroxylicious.io/documentation/0.20.0/html/developer-quick-start

Make the run script executable and then run the sample filter module within the Kroxylicious proxy using a provided configuration file.

```bash
chmod +x run.sh
./run.sh --config sample-proxy-config.yaml
```

--------------------------------

### Example Kroxylicious Proxy Configuration for Multi-tenancy

Source: https://kroxylicious.io/documentation/0.20.0/html/multi-tenancy-guide

Configure the MultiTenant filter in the `filterDefinitions` list for a standalone Kroxylicious proxy deployment. The `prefixResourceNameSeparator` option customizes the separator used for tenant prefixes.

```yaml
filterDefinitions:
  - name: my-multi-tenant-filter
    type: MultiTenant
    config:
      prefixResourceNameSeparator: "." __**(1)**
```

--------------------------------

### Example ACL Rules Syntax

Source: https://kroxylicious.io/documentation/0.20.0/html/authorization-guide

Define access control rules for users, topics, and transactional IDs. This syntax specifies permissions like 'allow' or 'deny' for specific resources and actions.

```java
from io.kroxylicious.filter.authorization import TopicResource as Topic, GroupResource as Group, TransactionalIdResource as TransactionalId;
deny User with name = "alice" to * Topic with name = "payments-received";
allow User with name = "alice" to * Topic with name like "payments-*";
allow User with name = "bob" to * Topic with name = "payments-received";
allow User with name = "bob" to READ Group with name = "payment-consumer-group";
allow User with name = "alice" to * TransactionalId with name like "alice-transaction-*";
otherwise deny;
```

--------------------------------

### Modify namespace in installation files

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Use `sed` to update the namespace in Kroxylicious installation YAML files. This command is for Linux systems.

```bash
sed -i 's/namespace: .*/namespace: my-kroxylicious-operator-namespace/' install/*.yaml
```

--------------------------------

### KeyStore.accept(KeyProviderVisitor<T> visitor)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/KeyProviderVisitor.html

Accepts a KeyProviderVisitor to perform an operation on the KeyStore.

```APIDOC
## KeyStore.accept(KeyProviderVisitor<T> visitor)

### Description
Accepts a visitor object to perform operations on the KeyStore.

### Method Signature
`<T> T KeyStore.accept(KeyProviderVisitor<T> visitor)`
```

--------------------------------

### Configure VirtualKafkaCluster with TLS Ingresses and Multiple Filters

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Define a VirtualKafkaCluster exposed to clients both on and off the cluster using TLS. This example includes two ingresses with TLS certificates and two protocol filters.

```yaml
kind: VirtualKafkaCluster
apiVersion: kroxylicious.io/v1alpha1
metadata:
  name: my-cluster
  namespace: my-proxy
spec:
  proxyRef:
    name: simple
  targetKafkaServiceRef:
    name: my-cluster
  ingresses:
    - ingressRef:
        name: cluster-ip
        certificateRef:
          name: 'cluster-ip-server-cert' __**(1)**
          kind: Secret
    - ingressRef:
        name: load-balancer
        certificateRef:
          name: 'external-server-cert' __**(2)**
          kind: Secret
  filterRefs:
    - name: my-filter-1
    - name: my-filter-2
```

--------------------------------

### KeyStore Constructor

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/index-all.html

Creates an instance of a `KeyStore` record class.

```APIDOC
## KeyStore(String, PasswordProvider, PasswordProvider, String)

### Description
Creates an instance of a `KeyStore` record class.

### Constructor Signature
`KeyStore(String, PasswordProvider, PasswordProvider, String)`

### Class
`io.kroxylicious.proxy.config.tls.KeyStore`
```

--------------------------------

### Modify namespace in installation files (macOS)

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Use `sed` to update the namespace in Kroxylicious installation YAML files. This command is for macOS systems.

```bash
sed -i '' 's/namespace: .*/namespace: my-kroxylicious-operator-namespace/' install/*.yaml
```

--------------------------------

### AuthorizerService.initialize(C)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/index-all.html

Initialises the service.

```APIDOC
## AuthorizerService.initialize(C)

### Description
Initialises the service.

### Method
(Not specified, likely a Java method call)

### Endpoint
(Not applicable, this is an interface method)

### Parameters
- **C** - Configuration object for the service.

### Response
(No return type specified, likely void or a status indicator.)
```

--------------------------------

### Kroxylicious Filter Configuration Example

Source: https://kroxylicious.io/documentation/0.20.0/html/developer-guide

Example of how a custom filter with configuration is defined in Kroxylicious YAML. Kroxylicious uses Jackson to deserialize the config object into the specified class.

```yaml
filterDefinitions:
- name: my-replacer
  type: SampleFetchResponse
  config:
    findValue: a
    replacementValue: b
```

--------------------------------

### KeyProviderVisitor.visit(KeyStore)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/KeyStore.html

This method in KeyProviderVisitor accepts a KeyStore object, indicating a way to process or utilize KeyStore configurations within the visitor pattern for TLS settings.

```APIDOC
## KeyProviderVisitor.visit(KeyStore)

### Description
This method is part of the KeyProviderVisitor interface and is designed to accept a KeyStore object. It's used within the visitor pattern to handle KeyStore configurations, likely for managing TLS certificates and keys.

### Method Signature
`T visit(KeyStore keyStore)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (T)
- **T** (Generic Type) - The return type of the visit method, specific to the visitor implementation.

#### Response Example
None
```

--------------------------------

### SASL Subject Builder Configuration Example

Source: https://kroxylicious.io/documentation/0.20.0/html/sasl-inspection-guide

Customize the SASL subject builder by specifying a default builder and configuring how principals are generated from extracted fields. This example shows mapping fields and fallback behavior.

```yaml
# ...
subjectBuilder: DefaultSaslSubjectBuilderService
subjectBuilderConfig:
    addPrincipals:
      - from: <field name>
        map:
          - replaceMatch: <match replace flags 1>
          - # ...
          - replaceMatch: <match replace flags n>
          - else: identity|anonymous
        principalFactory: <principal factory>
```

--------------------------------

### Example Oauth Bearer Filter Configuration

Source: https://kroxylicious.io/documentation/0.20.0/html/oauth-bearer-validation

Configure the OauthBearerValidation filter in a standalone proxy deployment's filterDefinitions. This example shows essential parameters like JWKS endpoint URL, refresh intervals, and audience/issuer verification.

```yaml
filterDefinitions:
  - name: my-oauth-filter
    type: OauthBearerValidation
    config:
      jwksEndpointUrl: https://oauth/JWKS   __**(1)**
      jwksEndpointRefreshMs: 3600000        __**(2)**
      jwksEndpointRetryBackoffMs: 100       __**(3)**
      jwksEndpointRetryBackoffMaxMs: 10000  __**(4)**
      scopeClaimName: scope                 __**(5)**
      subClaimName: sub                     __**(6)**
      authenticateBackOffMaxMs: 60000       __**(7)**
      authenticateCacheMaxSize: 1000        __**(8)**
      expectedAudience: https://first.audience, https//second.audience __**(9)**
      expectedIssuer: https://your-domain.auth/ __**(10)**
```

--------------------------------

### initialize Method

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/authorizer/service/AuthorizerService.html

Initialises the AuthorizerService with the provided configuration. This method must be called exactly once before the `build()` method.

```APIDOC
## Method: initialize

### Signature

`void initialize(@UnknownNullness C config)`

### Description

Initialises the service. This method must be invoked exactly once before `build()` is called.

### Parameters

- `config` (C) - Service configuration

### Throws

- `AuthorizerException` - If the service could not be initialized
```

--------------------------------

### Tls.getStoreTypeOrPlatformDefault

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/index-all.html

Gets the store type or platform default for TLS configuration.

```APIDOC
## getStoreTypeOrPlatformDefault(String)

Static method in record class io.kroxylicious.proxy.config.tls.Tls
```

--------------------------------

### ClientSaslContext

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/allclasses-index.html

Exposes SASL authentication information to plugins, for example using `FilterContext.clientSaslContext()`.

```APIDOC
## Class: ClientSaslContext

### Description
Exposes SASL authentication information to plugins, for example using `FilterContext.clientSaslContext()`.

### Type
Class
```

--------------------------------

### KeyStore Constructor

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/KeyStore.html

Creates an instance of a KeyStore record class with specified store file, password providers, and store type.

```APIDOC
## KeyStore Constructor

### Description
Creates an instance of a `KeyStore` record class.

### Signature
`public KeyStore(String storeFile, @Nullable PasswordProvider storePasswordProvider, @Nullable PasswordProvider keyPasswordProvider, String storeType)`

### Parameters
* `storeFile` (String) - the value for the `storeFile` record component
* `storePasswordProvider` (PasswordProvider) - the value for the `storePasswordProvider` record component
* `keyPasswordProvider` (PasswordProvider) - the value for the `keyPasswordProvider` record component
* `storeType` (String) - the value for the `storeType` record component
```

--------------------------------

### ServerOptions Constructor

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/ServerOptions.html

Creates a new instance of ServerOptions with the specified client authentication settings.

```APIDOC
## ServerOptions Constructor

### Description
Creates an instance of a `ServerOptions` record class.

### Parameters
* `clientAuth` (TlsClientAuth) - The value for the `clientAuth` record component.
```

--------------------------------

### Getting TrustOptions from TrustStore

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/TrustOptions.html

The TrustStore record component allows retrieval of TrustOptions.

```APIDOC
## Method
`TrustOptions trustOptions()`

### Description
Returns the value of the `trustOptions` record component.
```

--------------------------------

### build Method

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/authorizer/service/AuthorizerService.html

Builds an Authorizer service instance. The `initialize(C)` method must have been called prior to invoking this method.

```APIDOC
## Method: build

### Signature

`@NonNull Authorizer build() throws IllegalStateException`

### Description

Builds an Authorizer service. `initialize(C)` must have been called before this method is invoked.

### Returns

- `Authorizer` - the authorizer

### Throws

- `IllegalStateException` - if the service has not been initialised or the service is closed.
- `AuthorizerException` - If the authorizer could not be built
```

--------------------------------

### ClientTlsContext

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/allclasses-index.html

Exposes TLS information about the client-to-proxy connection to plugins, for example using `FilterContext.clientTlsContext()`.

```APIDOC
## Class: ClientTlsContext

### Description
Exposes TLS information about the client-to-proxy connection to plugins, for example using `FilterContext.clientTlsContext()`.

### Type
Class
```

--------------------------------

### KeyPair.accept(KeyProviderVisitor<T> visitor)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/KeyProviderVisitor.html

Accepts a KeyProviderVisitor to perform an operation on the KeyPair.

```APIDOC
## KeyPair.accept(KeyProviderVisitor<T> visitor)

### Description
Accepts a visitor object to perform operations on the KeyPair.

### Method Signature
`<T> T KeyPair.accept(KeyProviderVisitor<T> visitor)`
```

--------------------------------

### TlsClientAuth Enum Methods

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/TlsClientAuth.html

Provides details on how to get or create TlsClientAuth enum constants.

```APIDOC
## `static TlsClientAuth` valueOf(String name)

### Description
Returns the enum constant of this class with the specified name.

### Method
`static TlsClientAuth`

### Parameters
#### Path Parameters
- **name** (String) - The name of the enum constant to return.
```

```APIDOC
## `static TlsClientAuth[]` values()

### Description
Returns an array containing the constants of this enum class, in the order they are declared.

### Method
`static TlsClientAuth[]`
```

--------------------------------

### Getting TrustOptions from TrustProvider

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/TrustOptions.html

The TrustProvider interface provides a default method to obtain TrustOptions.

```APIDOC
## Method
`default TrustOptions trustOptions()`

### Description
Trust options that apply to this TLS peer.
```

--------------------------------

### Importing Resource Types in Kroxylicious

Source: https://kroxylicious.io/documentation/0.20.0/html/authorization-guide

Demonstrates how to import resource types from the authorization package. Use 'as' to provide an alias for the resource type.

```java
from <package> import <element> [as <alias>][,... , <elementn> [as <aliasn>]];
```

```java
from io.kroxylicious.filter.authorization import TopicResource;
```

```java
from io.kroxylicious.filter.authorization import TopicResource as Topic;
```

--------------------------------

### UnknownKeyException Constructors

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/kms/service/UnknownKeyException.html

Provides details on how to instantiate the UnknownKeyException.

```APIDOC
## Constructor Summary

Constructors

Constructor
Description
`UnknownKeyException()`
`UnknownKeyException(String message)`
```

```APIDOC
## Constructor Details

### UnknownKeyException

public UnknownKeyException()

### UnknownKeyException

public UnknownKeyException(String message)
```

--------------------------------

### Deploy Kroxylicious Operator

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Apply the installation files to deploy the Kroxylicious operator to your Kubernetes cluster.

```bash
kubectl create -f install
```

--------------------------------

### accept(TrustProviderVisitor<T> visitor)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/TrustProvider.html

Visits the trust provider using a TrustProviderVisitor. Implementors should call one of the visitor's `visit` methods.

```APIDOC
## Method: accept

### Signature
`<T> T accept(TrustProviderVisitor<T> visitor)`

### Description
Visits the trust provider `TrustProviderVisitor`. Implementor should call one `visit` method on visitor.

### Parameters
* `visitor` (TrustProviderVisitor<T>) - The visitor to accept.
```

--------------------------------

### KeyPair Constructor

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/KeyPair.html

This constructor is used to create a new KeyPair instance, which holds the file paths for the private key and certificate, and an optional password provider.

```APIDOC
## KeyPair(String privateKeyFile, String certificateFile, PasswordProvider keyPasswordProvider)

### Description
Creates an instance of a `KeyPair` record class.

### Parameters
* **privateKeyFile** (String) - Required - The location of the file containing the private key.
* **certificateFile** (String) - Required - The location of the file containing the certificate and intermediates.
* **keyPasswordProvider** (PasswordProvider) - Optional - The provider for the private key's password, or null if the key does not require a password.
```

--------------------------------

### Configure Common Tags for Metrics

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Example configuration for adding common tags to metrics, which will appear as labels in Prometheus scrapes.

```yaml
- type: "CommonTagsHook"
  config:
    commonTags:
      zone: "euc-1a"
      owner: "team-a"
```

--------------------------------

### Build Sample Filter Project

Source: https://kroxylicious.io/documentation/0.20.0/html/developer-quick-start

Build the generated sample filter project using Maven. This command also runs the project's unit and integration tests.

```bash
mvn verify
```

--------------------------------

### KeyProvider.accept(KeyProviderVisitor<T> visitor)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/KeyProviderVisitor.html

Visits the trust provider KeyProvider using a KeyProviderVisitor.

```APIDOC
## KeyProvider.accept(KeyProviderVisitor<T> visitor)

### Description
Visits the trust provider KeyProvider using a KeyProviderVisitor. This method allows for different operations to be performed based on the type of KeyProvider.

### Method Signature
`<T> T KeyProvider.accept(KeyProviderVisitor<T> visitor)`
```

--------------------------------

### User Constructor

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/authentication/User.html

Creates a new User instance with the provided name.

```APIDOC
## User(String name)

### Description
Creates an instance of a `User` record class.

### Parameters
- `name` (String) - the value for the `name` record component
```

--------------------------------

### Install Kroxylicious Operator

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Applies the Kroxylicious Operator manifests to the Kubernetes cluster and waits for the operator deployment to become available.

```bash
$ kubectl apply -f install
$ kubectl wait --namespace kroxylicious-operator deployment/kroxylicious-operator --for=condition=Available=True --timeout=300s

```

--------------------------------

### KeyProviderVisitor.visit(KeyPair)

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/index-all.html

Visits a `KeyPair` configuration within the `KeyProviderVisitor`.

```APIDOC
## Method: visit

### Description
Visits a `KeyPair` configuration.

### Method Signature
`visit(KeyPair)`

### Interface
io.kroxylicious.proxy.config.tls.KeyProviderVisitor
```

--------------------------------

### Get Direct Kafka Bootstrap Servers

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Retrieves the bootstrap server addresses for the direct Kafka cluster and assigns them to a variable.

```bash
$ DIRECT_CLUSTER_BOOTSTRAP_SERVERS=$(kubectl get -n kafka kafka my-cluster -o=jsonpath='{.status.listeners[0].bootstrapServers}')
```

--------------------------------

### Configure Pause Detector Hook

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Example configuration for the PauseDetectorHook, specifying sleep interval and pause threshold in milliseconds. Use with caution.

```yaml
micrometer:
  - type: "PauseDetectorHook"
    config:
      sleepIntervalMs: 500
      pauseThresholdMs: 500
```

--------------------------------

### Creating TrustStore with TrustOptions

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/class-use/TrustOptions.html

A TrustStore can be instantiated with specific TrustOptions.

```APIDOC
## Constructor
`TrustStore(String storeFile, PasswordProvider storePasswordProvider, String storeType, TrustOptions trustOptions)`

### Description
Creates an instance of a `TrustStore` record class.
```

--------------------------------

### Download and Unpack Kroxylicious Operator

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Downloads the Kroxylicious Operator release zip file and unpacks it into a temporary directory. This prepares for the operator's installation.

```bash
$ QUICKSTART_DIR=/tmp/ko-install-${RANDOM}
$ mkdir -p ${QUICKSTART_DIR}
$ cd ${QUICKSTART_DIR}
$ curl --fail --location --silent https://github.com/kroxylicious/kroxylicious/releases/download/v0.20.0/kroxylicious-operator-0.20.0.zip --output kroxylicious-operator.zip
$ unzip -q kroxylicious-operator.zip

```

--------------------------------

### Enable Vault Transit Secrets Engine

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Enables the Transit Secrets Engine for HashiCorp Vault after installation. This engine is necessary for Kroxylicious record encryption.

```bash
$ kubectl wait -n kms --for=condition=Ready pod/vault-0 && kubectl exec -n kms statefulsets/vault -- vault secrets enable transit

```

--------------------------------

### Tls Constructor

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/Tls.html

Creates a new Tls configuration instance.

```APIDOC
## Tls Constructor

`public Tls(@Nullable KeyProvider key, @Nullable TrustProvider trust, @Nullable AllowDeny<String> cipherSuites, @Nullable AllowDeny<String> protocols)`

Creates an instance of a `Tls` record class.

### Parameters

- `key` (KeyProvider): The value for the `key` record component.
- `trust` (TrustProvider): The value for the `trust` record component.
- `cipherSuites` (AllowDeny<String>): The value for the `cipherSuites` record component.
- `protocols` (AllowDeny<String>): The value for the `protocols` record component.
```

--------------------------------

### Define an HttpGetter Plugin Interface

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/plugin/package-summary.html

Defines a generic interface for making HTTP GET requests, allowing implementations to be plugged in without direct dependency.

```java
 interface HttpGetter<C> {
     void configure(C config);
     String get(String url);
 }
 
```

--------------------------------

### KeyProviderVisitor Interface

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/index-all.html

Visitor for implementations of `KeyProvider`

```APIDOC
## KeyProviderVisitor<T> Interface

### Description
Visitor for implementations of `KeyProvider`

### Interface
`io.kroxylicious.proxy.config.tls.KeyProviderVisitor<T>`
```

--------------------------------

### Get Proxied Cluster Bootstrap Server Address

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-quick-start

Retrieves the bootstrap server address for the proxied Kafka cluster and assigns it to a variable for later use.

```bash
$ PROXIED_CLUSTER_BOOTSTRAP_SERVER=$(kubectl get -n my-proxy virtualkafkacluster my-cluster -o=jsonpath='{.status.ingresses[?(@.name=="cluster-ip")].bootstrapServer}')
```

--------------------------------

### Configure Metrics Endpoint with Custom Bind Address and Port

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Customize the bind address and port for the Prometheus metrics endpoint. This example sets it to listen on 127.0.0.1:9999.

```yaml
management:
  bindAddress: 127.0.0.1
  port: 9999
  endpoints:
    prometheus: {}
```

--------------------------------

### Generate Sample Filter Project with Maven

Source: https://kroxylicious.io/documentation/0.20.0/html/developer-quick-start

Use the kroxylicious-filter-archetype to generate a basic filter project. Ensure you are in the project's root directory after generation.

```bash
mvn archetype:generate -DarchetypeGroupId=io.kroxylicious \
                       -DarchetypeArtifactId=kroxylicious-filter-archetype \
                       -DarchetypeVersion=0.20.0 \
                       -DgroupId=org.example \
                       -DartifactId=sample-filter \
                       -Dversion=1.0-SNAPSHOT \
                       -DinteractiveMode=false
cd sample-filter
```

--------------------------------

### KmsService.buildKms()

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/index-all.html

Builds a KMS service.

```APIDOC
## buildKms()

### Description
Builds a KMS service.

### Method
Method

### Signature
`buildKms()`
```

--------------------------------

### Proxy Log Example for Lost KEK

Source: https://kroxylicious.io/documentation/0.20.0/html/record-encryption-guide

This log entry indicates a failed decryption attempt due to a missing KEK, which is reported to the client as RESOURCE_NOT_FOUND(91).

```log
Failed to decrypt record in topic-partition <topic>-<partition> owing to key not found condition.
This will be reported to the client as a RESOURCE_NOT_FOUND(91).
Client may see a message like 'Unexpected error code 91 while fetching at offset' (java) or or 'Request illegally referred to resource that does not exist' (librdkafka).
Cause message: key 'd691a642-d8b4-4445-b668-d390df7000bb' is not found (AWS error: ErrorResponse{type='KMSInvalidStateException', message='arn:aws:kms:us-east-1:000000000000:key/d691a642-d8b4-4445-b668-d390df7000bb is pending deletion.'}).
Raise log level to DEBUG to see the stack.
```

--------------------------------

### Restrict TLS Protocol Versions

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Example VirtualKafkaCluster configuration to restrict TLS protocol versions for client-to-proxy connections. Allows explicit specification of supported protocols.

```yaml
kind: VirtualKafkaCluster
metadata:
  # ...
spec:
  # ...
  ingresses:
    - ingressRef:
        name: cluster-ip
      tls:
        certificateRef:
          # ...
        protocols: __**(1)**
          allow: __**(2)**
            - TLSv1.3
```

--------------------------------

### BeginQuorumEpochRequestFilter.onBeginQuorumEpochRequest

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/filter/class-use/FilterContext.html

Handles BeginQuorumEpoch requests. It receives the API version, request header, request data, and filter context. It returns a RequestFilterResult.

```APIDOC
## onBeginQuorumEpochRequest

### Description
Handle the given `header` and `request` pair, returning the `header` and `request` pair to be passed to the next filter using the RequestFilterResult.

### Method Signature
`onBeginQuorumEpochRequest(short apiVersion, org.apache.kafka.common.message.RequestHeaderData header, org.apache.kafka.common.message.BeginQuorumEpochRequestData request, FilterContext context)`

### Return Type
`CompletionStage<ResponseFilterResult>`
```

--------------------------------

### KeyPair Visitor Pattern

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/KeyPair.html

The `accept` method allows a `KeyProviderVisitor` to process the KeyPair.

```APIDOC
## accept(KeyProviderVisitor<T> visitor)

### Description
Visits the trust provider `KeyProviderVisitor`. Implementor should call one `visit` method on visitor.

### Parameters
* **visitor** (KeyProviderVisitor<T>) - The visitor to apply.
```

--------------------------------

### Configure VirtualKafkaCluster with Single Ingress and Filter

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-operator

Define a VirtualKafkaCluster for clients within the same Kubernetes cluster. This example shows a single ingress and a single protocol filter.

```yaml
kind: VirtualKafkaCluster
apiVersion: kroxylicious.io/v1alpha1
metadata:
  name: my-cluster
  namespace: my-proxy
spec:
  proxyRef: __**(1)**
    name: simple
  targetKafkaServiceRef: __**(2)**
    name: my-cluster
  ingresses:
    - ingressRef: __**(3)**
        name: cluster-ip
  filterRefs: __**(4)**
    - name: my-filter
```

--------------------------------

### Set Custom Log4j2 Configuration

Source: https://kroxylicious.io/documentation/0.20.0/html/kroxylicious-proxy

Use this environment variable with the `bin/kroxylicious-start.sh` script to load a custom log4j2 configuration file.

```bash
KROXYLICIOUS_LOGGING_OPTIONS="-Dlog4j2.configurationFile=/path/to/custom/log4j2.yaml"
```

--------------------------------

### Filter Specific API Versions

Source: https://kroxylicious.io/documentation/0.20.0/html/developer-guide

Override `shouldHandleXyzRequest` methods to apply filters only to specific API versions. This example filters FetchRequests for versions greater than 7.

```java
public class FetchFilter implements FetchRequestFilter {

    @Override
    public boolean shouldHandleFetchRequest(short apiVersion) {
        return apiVersion > 7;
    }

    @Override
    @Override
    public CompletionStage<RequestFilterResult> onRequest(ApiKeys apiKey,
                                                          RequestHeaderData header,
                                                          ApiMessage body,
                                                          FilterContext filterContext) {
        return context.forwardRequest(header, request);
    }
}
```

--------------------------------

### Kubernetes KafkaProtocolFilter for Authorization

Source: https://kroxylicious.io/documentation/0.20.0/html/authorization-guide

Use a `KafkaProtocolFilter` resource in Kubernetes to configure the Authorization filter. This example shows referencing ACL rules from a ConfigMap using interpolation.

```yaml
kind: KafkaProtocolFilter
metadata:
  name: my-authorization
spec:
  type: Authorization
  configTemplate:
    authorizer: AclAuthorizerService
    authorizerConfig:
      aclFile: ${configmap:acl-rules:acl-rules.txt}
```

--------------------------------

### Create Kafka Topic via Proxy

Source: https://kroxylicious.io/documentation/0.20.0/html/proxy-quick-start

Use the kafka-topics.sh client to create a topic named 'my_topic' by connecting through the Kroxylicious proxy.

```bash
bin/kafka-topics.sh --create --topic my_topic \
--bootstrap-server localhost:9192
```

--------------------------------

### TrustStore Constructors

Source: https://kroxylicious.io/documentation/0.20.0/javadoc/io/kroxylicious/proxy/config/tls/TrustStore.html

Provides details on how to create instances of the TrustStore class.

```APIDOC
## Constructor Details

### TrustStore
public TrustStore(String storeFile, @Nullable PasswordProvider storePasswordProvider, @Nullable String storeType, @Nullable TrustOptions trustOptions)
Creates an instance of a `TrustStore` record class.

Parameters:
    `storeFile` - the value for the `storeFile` record component
    `storePasswordProvider` - the value for the `storePasswordProvider` record component
    `storeType` - the value for the `storeType` record component
    `trustOptions` - the value for the `trustOptions` record component

### TrustStore
public TrustStore(String storeFile, PasswordProvider storePasswordProvider, String storeType)
A `TrustProvider` backed by a Java Truststore.

Parameters:
    `storeFile` - location of a key store, or reference to a PEM file containing both private-key/certificate/intermediates.
    `storePasswordProvider` - provider for the store password or null if store does not require a password.
    `storeType` - specifies the server key type. Legal values are those types supported by the platform `KeyStore`, and PEM (for X-509 certificates express in PEM format).
```

--------------------------------

### Implement RequestFilter in Java

Source: https://kroxylicious.io/documentation/0.20.0/html/developer-guide

Example of a custom filter implementing the RequestFilter interface to intercept and modify client requests. It sets a fixed client ID before forwarding the request.

```java
public class FixedClientIdFilter implements RequestFilter {

    @Override
    public CompletionStage<RequestFilterResult> onRequest(ApiKeys apiKey,
                                                          RequestHeaderData header,
                                                          ApiMessage body,
                                                          FilterContext filterContext) {
        header.setClientId("example!");
        return filterContext.forwardRequest(header, body);
    }

}
```
Tokens:
Raw