Kroxylicious

• Open the Kroxylicious offer on the Azure Marketplace and choose Get It Now, then Create.
• Select your subscription, resource group and region, and choose the Standard_B2s size.
• Provide your SSH public key for the azureuser account.
• In the Network Security Group, allow inbound TCP 22 from your admin network, and TCP 9192 and 9193 from the subnet your Kafka clients run in.
• Create the VM.

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:kroxylicious-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-rg \
  --name kroxylicious-01 \
  --image sac1647283583153:kroxylicious-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

On the first boot only, a one-shot unit called kroxylicious-firstboot.service runs before either product service starts. It does four things:

• Generates this VM's unique SCRAM credential.
• Writes the credential directly into Kafka cluster metadata as the storage is formatted.
• Resolves the address the proxy will advertise to clients.
• Writes the credentials file.

Both kafka.service and kroxylicious.service are gated on the marker this unit creates when it finishes, so neither can start against half-prepared state.

First boot completes in a few seconds. Connect with SSH:

ssh azureuser@<vm-ip>

Check that both services are active:

sudo systemctl is-active kroxylicious.service kafka.service

Both report active. Then check the listening topology, because it is what makes this deployment safe:

sudo ss -ltn | grep -E ':(9092|9093|9190|9192|9193)'

The proxy listens on *:9192 and *:9193. The broker appears only on 127.0.0.1:9092 and 127.0.0.1:9093, and the proxy's metrics endpoint only on 127.0.0.1:9190. Any traffic that reaches Kafka from off the VM must therefore pass through Kroxylicious.

The per-VM SCRAM credential is written at first boot to a file that only root can read. Print it:

sudo cat /stage/scripts/kroxylicious-credentials.log

The file records the bootstrap address clients should use, the SASL user SecureAnyCloud, this VM's generated password, and the security protocol and mechanism.

A ready-made client configuration containing the same credential is also written to /etc/kroxylicious/client.properties, root-owned with mode 0600. The examples below use it directly.

The image pre-creates a topic called SecureAnyCloud. Produce a message to it through the proxy on port 9192:

echo "hello from sac" | sudo /opt/kafka/bin/kafka-console-producer.sh \
  --bootstrap-server 127.0.0.1:9192 \
  --command-config /etc/kroxylicious/client.properties \
  --topic sac

Read the message back, again through the proxy:

sudo timeout 40 /opt/kafka/bin/kafka-console-consumer.sh \
  --bootstrap-server 127.0.0.1:9192 \
  --command-config /etc/kroxylicious/client.properties \
  --topic sac --from-beginning --max-messages 1

--max-messages 1 makes the consumer exit cleanly as soon as it has read one message. Without it, the consumer waits for a timeout and then reports a TimeoutException. This is normal behaviour, but it looks like a fault.

On Kafka 4, the console tools take --command-config. The older --producer.config and --consumer.config flags are deprecated and print warnings that corrupt captured output.

Next, confirm that the client is steered to the proxy rather than to the broker. Ask the cluster which nodes it advertises:

sudo /opt/kafka/bin/kafka-broker-api-versions.sh \
  --bootstrap-server 127.0.0.1:9192 \
  --command-config /etc/kroxylicious/client.properties | awk 'NR==1'

The node reported is the proxy's node port, 9193, on this VM's advertised address. It is never the broker's 9092. Kroxylicious rewrites the cluster metadata as it passes, which keeps clients on the proxy for the whole session rather than only for the initial bootstrap.

Client-facing authentication is on by default. A client that presents the wrong password is rejected during the SASL exchange. Check the filter configuration:

sudo grep -E 'type: SaslInspection|enabledMechanisms|requireAuthentication' /etc/kroxylicious/config.yaml

requireAuthentication is set to true, so Kroxylicious forwards nothing beyond the authentication exchange until a client has authenticated successfully. The backing broker independently enforces SASL SCRAM-SHA-512 as well, so removing the proxy filter would not open the cluster.

The image ships a self-test that proves the deployment end to end, rather than merely checking that a process is running:

sudo /usr/local/sbin/kroxylicious-selftest.sh

The self-test runs these checks in order:

• It produces a uniquely tagged message through the proxy and consumes it back, asserting that the payload matches byte for byte.
• It reads the proxy's own upstream request counter and asserts that it moved. This distinguishes traffic that traversed the proxy from traffic that reached the broker directly.
• It confirms that the client is steered to the proxy node port.
• It checks that a wrong credential is explicitly rejected.
• It stops the proxy and confirms that the round trip breaks.
• It restarts the proxy and proves the round trip again, so a passing negative result cannot be an artefact of a broken system.

The script exits non-zero if any check fails.

Kroxylicious publishes Prometheus metrics on loopback port 9190. List a sample of the proxy metrics:

curl -s http://127.0.0.1:9190/metrics | awk '/^kroxylicious_(client_to_proxy|proxy_to_server)/ && ++n <= 8'

The client_to_proxy families count what clients sent to the proxy. The proxy_to_server families count what the proxy forwarded upstream to the broker. Comparing the two is the most direct way to confirm that traffic flows through the proxy in production.

To scrape these metrics from another host, bind the management endpoint to a routable address by editing bindAddress under management in /etc/kroxylicious/config.yaml. Restrict access with a Network Security Group rule.

The bundled broker makes the image useful immediately. In production, you will usually put Kroxylicious in front of a cluster you already run, which is a single configuration change.

Edit /etc/kroxylicious/config.yaml, set bootstrapServers under targetCluster to your own cluster, then restart the proxy.

• If your cluster has more than one broker, widen nodeIdRanges so that every broker node id maps to a proxy port. Open those ports in your Network Security Group.
• If your cluster requires TLS or a different SASL mechanism upstream, add the matching tls and authentication stanzas to targetCluster.

Once the proxy serves your own cluster, you can stop and disable the bundled broker with sudo systemctl disable --now kafka.service. The bundled broker only ever listened on loopback, so leaving it running is not an exposure. Disabling it returns roughly 370 MB of RAM to the proxy.

By default, the proxy advertises this VM's private address to clients. This is deliberate. A Kafka proxy that terminates client connections should not be reachable from the internet by default, and this default keeps the deployment safe until you make an explicit decision.

To serve clients from outside the VNet, set the advertised address to a name or address that those clients can reach, then restart the proxy:

sudo sed -i 's|advertisedBrokerAddressPattern: .*|advertisedBrokerAddressPattern: <your-domain>|' \
  /etc/kroxylicious/config.yaml
sudo systemctl restart kroxylicious.service

Replace <your-domain> with the hostname your clients will use, for example kafka.internal.example.com.

Use a DNS name rather than a bare public IP. A DNS name survives address changes, and you need one anyway when you add TLS. Whichever you choose, the value must be the address the client will use, because it is handed to clients in the cluster metadata.

Also open TCP 9192 and 9193 in the Network Security Group. Restrict the source range to the networks your clients run in rather than leaving it open to the internet.

Kroxylicious ships more filters than the SASL inspection filter enabled here. They include record encryption, multi-tenancy, record validation, entity isolation and authorization. They are part of the distribution, and you enable them by adding them to filterDefinitions and defaultFilters in /etc/kroxylicious/config.yaml.

Record encryption is deliberately not enabled in this image. The filter encrypts record payloads transparently, but it needs a key management service to hold the key material. Every production backend it supports (Azure Key Vault, AWS KMS, HashiCorp Vault, Fortanix DSM and Thales CipherTrust) is an external service. The only backend that runs standalone on a single VM is intended for testing and holds key material in the proxy's memory.

Shipping that backend would mean advertising encryption backed by a test double, so the image ships the filter unconfigured. As a result, there is no encryption key material in this image and nothing sensitive baked into it.

On Azure, the natural choice is the Azure Key Vault provider. Create a vault and a key, and grant this VM's managed identity permission to use it. Then add the record encryption filter to filterDefinitions, referencing that vault. See the Kroxylicious documentation for the configuration schema that matches your version.