Skip to content

AKHQ

AKHQ is an open source web application that helps you manage, inspect, and debug Kafka-compatible workloads.

Deploy AKHQ with a production Bufstream cluster

Prerequisites

  • A live Bufstream cluster
  • An enterprise deployment of the Buf Schema Registry, with the Confluent integration enabled (optional)
  • A Buf bot user and token (optional)

Basic configuration

Configuring AKHQ to work with Bufstream requires setting the cluster's bootstrap address and specifying a client ID. The simplest way to do so is by setting client.id and bootstrap.servers in the AKHQ configuration file (/app/application.yml by default).

  • Set bootstrap.servers to the bootstrap address of your Bufstream cluster.
  • Set client.id by choosing a unique identifier for AKHQ, then appending ;broker_count=1. For example, you might choose akhq;broker_count=1. This instructs the Bufstream cluster to present itself as a single Kafka broker, allowing AKHQ to display statistics for each topic correctly.
/app/application.yml
akhq:
  connections:
    bufstream:
      properties:
        client.id: "akhq;broker_count=1"
        bootstrap.servers: "localhost:9092" # your cluster's bootstrap address
        metadata.recovery.strategy: REBOOTSTRAP

Connecting to the Buf Schema Registry

To display binary Protobuf messages as human-readable JSON, AKHQ can integrate with the Buf Schema Registry. Add the following configuration block to your AKHQ configuration to enable the schema registry:

Add schema registry to /app/application.yml
akhq:
  connections:
    bufstream:
      properties:
        client.id: "akhq;broker_count=1"
        bootstrap.servers: "localhost:9092" # your cluster's bootstrap address
        metadata.recovery.strategy: REBOOTSTRAP
+     schema-registry:
+       type: "confluent"
+       # The URL for your instance of the Confluent Schema Registry within the Buf Schema Registry
+       url: "https://buf.example.com/integrations/confluent/my-registry"
+       # The username of the Buf bot user that will manage the connections for your schema registry
+       basic-auth-username: "example-bot-user"
+       # The token generated for the above bot user
+       basic-auth-password: "example-bot-token"

For complete documentation of all the available configuration options, refer to the AKHQ configuration documentation and the Java schema registry client documentation.

Try AKHQ with a local Bufstream instance

To try AKHQ with Bufstream on your local machine, you'll need Docker installed.

First, start an in-memory Bufstream instance listening on the default Kafka port:

docker run -p 9092:9092 \
  us-docker.pkg.dev/buf-images-1/bufstream-public/images/bufstream:latest \
  --inmemory \
  --config.kafka.public_address.host host.docker.internal \
  --config.kafka.public_address.port 9092 \
  --config.kafka.address.host 0.0.0.0

In a separate terminal, add the following configuration to akhq.yaml in your current working directory:

akhq.yaml
akhq:
  connections:
    bufstream-demo:
      properties:
        client.id: "akhq;broker_count=1"
        bootstrap.servers: "host.docker.internal:9092"

Then run AKHQ with Docker:

docker run -p 8080:8080 \
  -v ./akhq.yaml:/app/application.yml \
  tchiotludo/akhq:latest

Once both Bufstream and AKHQ are running, navigate to localhost:8080 in your browser.

AKHQ homescreen

You can now use AKHQ to create new topics, view and publish messages, view detailed statistics for each topic, and more.