Configuration Reference

This page is the configuration reference for kubemq-faststream: package facts, the KubeMQBroker constructor surface, URL formats, validation rules, the environment-variable overrides, and the FastStream standard broker options. For the exported symbols, enums, subscriber fields, and the broker.request() signature, see the API reference. For runnable walkthroughs, start with Getting Started.

Package Facts

Install with uv or pip:

uv add kubemq-faststream

pip install kubemq-faststream

KubeMQBroker Constructor

KubeMQBroker extends FastStream's BrokerUsecase, so it accepts the standard FastStream broker options alongside the KubeMQ-specific connection settings. The first positional argument is the broker URL; everything else is keyword-only.

from kubemq_faststream import KubeMQBroker

broker = KubeMQBroker(
    "kubemq://localhost:50000",
    client_id="my-service",
    auth_token="my-token",
    default_cq_timeout=30,
    graceful_timeout=15.0,
)

KubeMQ Connection Parameters

For TLS, mTLS, and authentication setups with full examples, see Configuration & Security.

FastStream Standard Parameters

These keyword-only options mirror the other FastStream brokers (the KafkaBroker pattern). They are optional and default to FastStream's standard values.

URL Formats

The url argument (or the KUBEMQ_ADDRESS environment variable) accepts three forms:

KubeMQBroker("kubemq://localhost:50000")           # plain
KubeMQBroker("kubemq+tls://broker.example:50000")  # TLS via scheme
KubeMQBroker("localhost:50000")                    # bare host:port

Environment Variables

Every connection parameter can be supplied through an environment variable. Environment variables take precedence over constructor arguments when set, so you can ship code with sensible defaults and override the target broker at deploy time without changing source.

A broker constructed with no arguments reads its entire configuration from the environment:

import os
from kubemq_faststream import KubeMQBroker

os.environ.setdefault("KUBEMQ_ADDRESS", "localhost:50000")
os.environ.setdefault("KUBEMQ_CLIENT_ID", "env-var-demo")

broker = KubeMQBroker()  # picks up KUBEMQ_ADDRESS and KUBEMQ_CLIENT_ID

Validation Rules

The broker config validates these settings as it is constructed. Violations raise ValueError immediately — before any connection is attempted — so misconfiguration fails fast:

• max_send_size must be greater than 0.
• max_receive_size must be greater than 0.
• default_cq_timeout must be greater than 0.
• For mutual TLS, tls_cert_file and tls_key_file are paired: setting one without the other raises ValueError.
• An auth_token that is set but blank (empty or whitespace-only) is rejected. To run without authentication, leave the token unset rather than passing an empty string.

See also