Configure the Kafka agent

Available in versions: 26.3 and later

This task describes how to configure the OpenText Service Virtualization Kafka agent. The Kafka agent handles communication between Kafka clients and real or virtual Kafka services. Each agent configuration represents a connection to a single Kafka cluster.

In this topic:

Configure the agent settings

From the main menu, select Tools > Options. Click Agents. Under Kafka, select a configuration. For user interface details, see Kafka agent settings.

Security configuration

The Kafka agent supports four security modes, selected by the Security Protocol field.

Security Protocol	Encryption	Authentication
PLAINTEXT	None	None
SSL	TLS	Broker certificate validation (one-way TLS). Optional mutual TLS with a client certificate.
SASL_PLAINTEXT	None	SASL credentials
SASL_SSL	TLS	SASL credentials and broker certificate validation. Optional mutual TLS.

SASL authentication

When using SASL_PLAINTEXT or SASL_SSL, configure the following:

• SASL Mechanism. The authentication protocol. Supported values are PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512.

• SASL Username. The username for the SASL connection.

• SASL Password. The password for the SASL connection.

All these fields are required when a SASL security protocol is selected.

SSL broker certificate validation (server trust)

When using SSL or SASL_SSL, the agent must be able to validate the broker TLS certificate. Configure one of the following:

Option 1 - SSL CA Location (recommended)

Set SSL CA Location to the path of a CA certificate file or bundle (PEM format) that signed the broker certificate. The agent uses this file directly to validate the broker.

Option 2 - SSL Truststore Location

Set SSL Truststore Location to the path of a truststore file (PKCS12/PFX format) containing trusted CA or intermediate certificates. If the truststore is password-protected, also set SSL Truststore Password.

SSL client authentication (mutual TLS)

Mutual TLS (mTLS) is required only when the broker is configured to authenticate clients by certificate. Configure the following:

• SSL Keystore Location. Path to the file containing the client certificate and private key (PKCS12/PFX format).

• SSL Keystore Password. Password for the keystore file, if password-protected.

If SSL Keystore Location is not set, the agent connects without presenting a client certificate. Most Kafka deployments do not require mutual TLS.

Debug the connection to a Kafka broker

Verify the broker address, security configuration, and credentials before deploying virtual services.

Click Test Configuration to validate the settings. If the test fails, review the error message and consult the following table.

Symptom	Possible cause	Solution
Agent fails to start. Connection to broker fails.	Incorrect bootstrap server address or port.	Verify the Bootstrap Servers value. Confirm host and port are reachable from the SV Server machine.
Agent fails to start. Connection to broker fails.	Firewall is blocking the Kafka port (for example, 9092 for PLAINTEXT, 9093 for SSL).	Check network access between SV Server and the Kafka broker.
SSL handshake fails. Broker certificate is not trusted.	CA certificate is missing or incorrect.	Verify that SSL CA Location or SSL Truststore Location points to the correct root CA.
SSL handshake fails.	Security Protocol mismatch between agent and broker listener.	Make sure Security Protocol in the agent matches the listener type on the broker (for example, SSL versus SASL_SSL).
SASL authentication error.	Incorrect credentials or mechanism.	Verify SASL Mechanism, SASL Username, and SASL Password. Confirm the user exists and has the required broker permissions.
SASL authentication error.	Mechanism mismatch between agent and broker.	Make sure SASL Mechanism matches the mechanism enabled on the broker (for example, PLAIN or SCRAM-SHA-256).
Truststore load error at startup.	Truststore file format is incorrect or password is wrong.	Confirm the truststore is in PKCS12/PFX format. Verify SSL Truststore Password.
Consumer receives no messages.	Wrong topic name or partition configuration.	Verify virtual and real endpoint topic names. Check the partition filter if configured on the endpoint.
Consumer receives no messages.	Group ID conflict with another consumer.	Use a unique Group ID per agent configuration.
Agent connects but messages are not matched.	Auto Offset Reset starts too late.	Set Auto Offset Reset to earliest to consume from the beginning of the topic.