Kafka / Message Broker

The system utilizes an Apache Kafka message broker to trigger its workflows. The related Kafka topic is published by Zammad upon ticket creation or update events. Our Zammad-AI service subscribes to this topic to process incoming tickets and generate AI-driven responses.

Events have the following structure:

{
  "action": "created",
  "ticket": "3720",
  "status": "new",
  "statusId": "1",
  "anliegenart": "technischer Bürgersupport",
  "lhmExtId": ""
}

The structure is defined in the dbs/ticketing-eventing service and can be found in its GitHub repository.

Kafka Configuration & Security

Kafka settings are nested under the kafka key in config.yaml and support environment variable overrides using the prefix ZAMMAD_AI_KAFKA__. Security settings are further nested under security.

Example YAML

kafka:
  broker_url: "localhost:9092"
  topic: "ticket-events"
  group_id: "zammad-ai"
  security:
    # Choose one of the following security schemas:
    # A: For mTLS via environment variables:
    ca_file_base64: "QkFTRTY0X0NBX0NFUlQ=" # use actual base64-encoded CA cert
    pkcs12_base64: "QkFTRTY0X1BLQ1MxMl9CTE9C" # use actual base64-encoded PKCS#12 blob
    pkcs12_pw_base64: "QkFTRTY0X1BBU1NXT1JE" # use actual base64-encoded PKCS#12 password


    # B: For mTLS via file paths:
    # ca_file_path: "/path/to/ca.pem"
    # client_cert_path: "/path/to/client.crt"
    # client_key_path: "/path/to/client.key"

Environment Variable Overrides

Use double underscores for nesting:

• ZAMMAD_AI_KAFKA__BROKER_URL
• ZAMMAD_AI_KAFKA__SECURITY__CA_FILE_BASE64
• ZAMMAD_AI_KAFKA__SECURITY__PKCS12_BASE64
• ZAMMAD_AI_KAFKA__SECURITY__PKCS12_PW_BASE64

Security Schemas

Kafka connections can be secured either via classic PEM files or via PKCS#12 blobs delivered through environment variables. Choose one of the following schemas:

1. KafkaMTLSEnvSecurity (Environment Variables)

• ca_file_base64: Base64-encoded CA certificate
• pkcs12_base64: Base64-encoded PKCS#12 payload
• pkcs12_pw_base64: Base64-encoded PKCS#12 password

2. KafkaMTLSFileSecurity (File Paths)

• ca_file_path: Path to CA certificate file (PEM)
• client_cert_path: Path to client certificate file (PEM)
• client_key_path: Path to client private key file (PEM)

When using PKCS#12, the broker security layer decodes the secret in-memory, converts it to PEM, and feeds it into aiokafka's SSL context. The CA material is taken from the configured file or environment variable.