Steadybit extension-kafka

A Steadybit extension to integrate Kafka into Steadybit.

Learn about the capabilities of this extension in our Reliability Hub.

Prerequisites

The extension-kafka is using these capacities, thus may need elevated rights on kafka side :

• List brokers / topics / consumer groups / offsets
• Elect leaders for partitions
• Alter broker configuration
• Create / Delete ACLs
• Delete Records

Configuration

Single Cluster Configuration

For connecting to a single Kafka cluster, use the following configuration:

Environment Variable	Helm value	Meaning	Required	Default
STEADYBIT_EXTENSION_SEED_BROKERS	kafka.seedBrokers	Brokers hosts (without scheme) with port separated by comma (example: "localhost:9092,localhost:9093"	yes
STEADYBIT_EXTENSION_SASL_MECHANISM	kafka.auth.saslMechanism	PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512	no
STEADYBIT_EXTENSION_SASL_USER	kafka.auth.saslUser	Sasl User	no
STEADYBIT_EXTENSION_SASL_PASSWORD	kafka.auth.saslPassword	Sasl Password	no
STEADYBIT_EXTENSION_KAFKA_CLUSTER_CERT_CHAIN_FILE	kafka.auth.certChainFile	The client certificate in PEM format.	no
STEADYBIT_EXTENSION_KAFKA_CLUSTER_CERT_KEY_FILE	kafka.auth.certKeyFile	The private key associated with the client certificate.	no
STEADYBIT_EXTENSION_KAFKA_CLUSTER_CA_FILE	kafka.auth.caFile	The Certificate Authority (CA) certificate in PEM format. Can be used without a client certificate, and enables TLS.	no
STEADYBIT_EXTENSION_KAFKA_CONNECTION_USE_TLS	kafka.auth.useTLS	Switch to "true" to use a TLS connection with default system certs, fill the certs fields above if you want to tune the tls connection.	no
STEADYBIT_EXTENSION_INSECURE_SKIP_VERIFY	kafka.insecureSkipVerify	Skip TLS certificate verification for all clusters. See Importing your own certificates.	no	false
STEADYBIT_EXTENSION_DISCOVERY_ATTRIBUTES_EXCLUDES_BROKERS	discovery.attributes.excludes.broker	List of Broker Attributes which will be excluded during discovery. Checked by key equality and supporting trailing "*"	no
STEADYBIT_EXTENSION_DISCOVERY_ATTRIBUTES_EXCLUDES_TOPICS	discovery.attributes.excludes.topic	List of Broker Attributes which will be excluded during discovery. Checked by key equality and supporting trailing "*"	no
STEADYBIT_EXTENSION_DISCOVERY_ATTRIBUTES_EXCLUDES_CONSUMER_GROUPS	discovery.attributes.excludes.consumer	List of Broker Attributes which will be excluded during discovery. Checked by key equality and supporting trailing "*"	no

Multi-Cluster Configuration

The extension supports connecting to multiple Kafka clusters simultaneously. When using multi-cluster configuration, all clusters are discovered in parallel and each target includes a kafka.cluster.name attribute to identify which cluster it belongs to.

Important: When kafka.clusters is defined, the single-cluster configuration (kafka.seedBrokers, kafka.auth.*) is ignored.

Helm Values

Configure multiple clusters using the kafka.clusters array:

kafka:
  clusters:
    - name: production                              # Descriptive name (for your reference)
      seedBrokers: "broker1:9092,broker2:9092"      # Required: comma-separated broker list
      auth:
        saslMechanism: "SCRAM-SHA-256"              # Optional: PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512
        saslUser: "prod-user"                       # Optional: SASL username
        saslPassword: "prod-pass"                   # Optional: SASL password
        useTLS: "true"                              # Optional: enable TLS
        caFile: "/path/to/ca.pem"                   # Optional: CA certificate path
        certChainFile: "/path/to/cert.pem"          # Optional: client certificate path
        certKeyFile: "/path/to/key.pem"             # Optional: client key path

    - name: staging
      auth:
        existingSecret: "staging-kafka-secret"      # Optional: use existing K8s secret (must also contain seedBrokers)

Using Existing Secrets

Instead of passing credentials as Helm values, you can reference an existing Kubernetes secret via kafka.auth.existingSecret (single cluster) or kafka.clusters[].auth.existingSecret (multi-cluster). The chart then skips creating its own secret and reads every setting from the referenced one.

All of the following keys must be present in the secret, otherwise the pod fails to start with CreateContainerConfigError. Set unused keys to an empty string.

Key	Meaning
seedBrokers	Comma-separated broker list (multi-cluster only)
saslMechanism	PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512
saslUser	SASL username
saslPassword	SASL password
useTLS	Enable TLS (true/false)
caFile	CA certificate path
certChainFile	Client certificate path
certKeyFile	Client key path

In multi-cluster mode the broker list is read from the secret's seedBrokers key; a seedBrokers value set next to existingSecret is ignored. In single-cluster mode the broker list always comes from kafka.seedBrokers, and the seedBrokers key is not needed.

Example secret:

apiVersion: v1
kind: Secret
metadata:
  name: staging-kafka-secret
type: Opaque
stringData:
  seedBrokers: "staging-broker:9092"
  saslMechanism: "SCRAM-SHA-256"
  saslUser: "staging-user"
  saslPassword: "staging-password"
  useTLS: "true"
  caFile: ""
  certChainFile: ""
  certKeyFile: ""

Environment Variables (Alternative)

Multi-cluster configuration can also be done via indexed environment variables. Replace X with the cluster index (0, 1, 2, ...):

Environment Variable	Meaning
STEADYBIT_EXTENSION_CLUSTER_X_SEED_BROKERS	Comma-separated broker list
STEADYBIT_EXTENSION_CLUSTER_X_SASL_MECHANISM	PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512
STEADYBIT_EXTENSION_CLUSTER_X_SASL_USER	SASL username
STEADYBIT_EXTENSION_CLUSTER_X_SASL_PASSWORD	SASL password
STEADYBIT_EXTENSION_CLUSTER_X_KAFKA_CONNECTION_USE_TLS	Enable TLS (true/false)
STEADYBIT_EXTENSION_CLUSTER_X_KAFKA_CLUSTER_CA_FILE	CA certificate path
STEADYBIT_EXTENSION_CLUSTER_X_KAFKA_CLUSTER_CERT_CHAIN_FILE	Client certificate path
STEADYBIT_EXTENSION_CLUSTER_X_KAFKA_CLUSTER_CERT_KEY_FILE	Client key path

Example:

# First cluster
STEADYBIT_EXTENSION_CLUSTER_0_SEED_BROKERS=prod-broker1:9092,prod-broker2:9092
STEADYBIT_EXTENSION_CLUSTER_0_SASL_MECHANISM=SCRAM-SHA-256
STEADYBIT_EXTENSION_CLUSTER_0_SASL_USER=prod-user
STEADYBIT_EXTENSION_CLUSTER_0_SASL_PASSWORD=prod-pass

# Second cluster
STEADYBIT_EXTENSION_CLUSTER_1_SEED_BROKERS=staging-broker:9092
STEADYBIT_EXTENSION_CLUSTER_1_SASL_MECHANISM=PLAIN
STEADYBIT_EXTENSION_CLUSTER_1_SASL_USER=staging-user
STEADYBIT_EXTENSION_CLUSTER_1_SASL_PASSWORD=staging-pass

Beyond the settings above, this extension supports the configuration common to all Steadybit extensions:

• extension-kit — HTTP and health ports, TLS and mutual TLS, unix domain socket, logging, and pprof.
• Target Filtering — stop the extension reporting targets you do not want.
• Group Matching — tag discovered targets with a group, so enrichment rules only match within it.

Importing your own certificates

If your brokers use a self-signed certificate, or one issued by a private CA, either trust the CA (recommended) or skip certificate verification. Both apply to the single-cluster and the multi-cluster configuration.

Store the CA certificate (*.crt) in a config map and mount it into the extension:

kubectl create configmap -n steadybit-agent kafka-self-signed-ca --from-file=./self-signed-ca.crt

extraVolumeMounts:
  - name: extra-certs
    mountPath: /etc/ssl/extra-certs
    readOnly: true
extraVolumes:
  - name: extra-certs
    configMap:
      name: kafka-self-signed-ca

Option 1: Trusting the CA for all clusters

Add the mounted directory to the trusted certificate directories, and enable TLS:

kafka:
  auth:
    useTLS: "true"
extraEnv:
  - name: SSL_CERT_DIR
    value: /etc/ssl/extra-certs:/etc/ssl/certs

Option 2: Trusting the CA for one cluster

Point the cluster's caFile at the mounted file. A CA file alone is enough: it enables TLS and replaces the system CAs for that cluster, no client certificate is required.

kafka:
  auth:
    caFile: /etc/ssl/extra-certs/self-signed-ca.crt

For mutual TLS, additionally set certChainFile and certKeyFile (both are required) to the mounted client certificate and key.

Option 3: Skipping certificate verification

Disables TLS certificate verification for all clusters. Suitable for testing, not recommended for production.

kafka:
  insecureSkipVerify: true
  auth:
    useTLS: "true"

Installation

Using Docker

docker run \
  --rm \
  -p 8080 \
  --name steadybit-extension-kafka \
  --env STEADYBIT_EXTENSION_SEED_BROKERS="localhost:9092" \
  ghcr.io/steadybit/extension-kafka:latest

Using Helm in Kubernetes

helm repo add steadybit-extension-kafka https://steadybit.github.io/extension-kafka
helm repo update
helm upgrade steadybit-extension-kafka \
    --install \
    --wait \
    --timeout 5m0s \
    --create-namespace \
    --namespace steadybit-agent \
    --set kafka.seedBrokers="localhost:9092" \
    steadybit-extension-kafka/steadybit-extension-kafka

Register the extension

Make sure to register the extension on the Steadybit platform. Please refer to the documentation for more information.

Generate pem files from truststore and keystore

Prerequisites

• Keystore file: kafka.keystore.jks (contains the client certificate and private key).
• Truststore file: kafka.truststore.jks (contains the CA certificate).
• Tools Required: keytool and openssl must be installed.

---

Steps to Generate PEM Files

1. Export the CA Certificate (ca-cert.pem) Extract the CA certificate from the truststore using the following command:

keytool -exportcert \
 -keystore kafka.truststore.jks \
 -alias CARoot \
 -storepass <truststore-password> \
 -rfc -file ca-cert.pem

• Replace with the password for the truststore. • The output file ca-cert.pem will contain the CA certificate in PEM format.

2. Convert the Keystore to PKCS12 Format

Convert the keystore to a PKCS12 file to facilitate extracting the certificate and private key:

keytool -importkeystore \
-srckeystore kafka.keystore.jks \
-srcstorepass <keystore-password> \
-srcalias kafka \
-destkeystore kafka-keystore.p12 \
-deststoretype PKCS12 \
-deststorepass <p12-password>

• Replace with the password for the keystore. • Replace with a new password for the PKCS12 file. • This will generate the file kafka-keystore.p12, which contains both the client certificate and private key.

3. Extract the Private Key (client-key.pem) Use the following command to extract the private key from the PKCS12 file:

 openssl pkcs12 -in kafka-keystore.p12 \
 -nocerts -nodes -out client-key.pem \
 -passin pass:<p12-password>

• Replace with the password set for the PKCS12 file. • This will generate the file client-key.pem, which contains the private key in PEM format.

4. Extract the Client Certificate (client-cert.pem) Use the following command to extract the client certificate from the PKCS12 file:

 openssl pkcs12 -in kafka-keystore.p12 \
 -clcerts -nokeys -out client-cert.pem \
 -passin pass:<p12-password>

• Replace with the password set for the PKCS12 file. • This will generate the file client-cert.pem, which contains the client certificate in PEM format.

5. (Optional) Verifying the Generated PEM Files

openssl x509 -in ca-cert.pem -text -noout
openssl rsa -in client-key.pem -check
openssl x509 -in client-cert.pem -text -noout

Ensure that: • The CA certificate includes the correct issuer and validity period. • The private key matches the client certificate.

Issue: “Alias not found”

Verify the contents of the keystore and truststore:

keytool -list -v -keystore kafka.keystore.jks -storepass <keystore-password>
keytool -list -v -keystore kafka.truststore.jks -storepass <truststore-password>

Notes

1. The private key (client-key.pem) must be kept secure. Unauthorized access to this file can compromise the client.
2. Ensure the Kafka broker’s hostname or IP address matches the Subject Alternative Name (SAN) in the server’s certificate.
3. Always use strong passwords for your keystore, truststore, and PKCS12 files.

Version and Revision

The version and revision of the extension:

• are printed during the startup of the extension
• are added as a Docker label to the image
• are available via the version.txt/revision.txt files in the root of the image