kubemq-celery is a Kombu virtual transport for KubeMQ — it sends Celery task messages over KubeMQ Queues and routes pidbox and monitoring traffic over KubeMQ Events. Everything beyond the broker URL is tuned through two option dictionaries: broker_transport_options for the task transport and result_backend_transport_options for the queue-peek result backend. This page is the exhaustive key-by-key reference for both. For URL schemes, the public API, and Celery-settings compatibility, see Configuration; for worked examples and TLS recipes, see the Configuration guide.

broker_transport_options

Pass transport-level settings through app.conf.broker_transport_options. All nineteen keys are listed below.

broker_transport_options.py

app.conf.broker_transport_options = {
    "wait_timeout": 1,
    "auth_token": "my-token",
    "dead_letter_queue": "celery-dead-letters",
    "max_receive_count": 3,
    "client_id_prefix": "celery",
    "tls_enabled": False,
    "tls_cert_file": "/path/to/cert.pem",
    "tls_key_file": "/path/to/key.pem",
    "tls_ca_file": "/path/to/ca.pem",
    "max_send_size": 4_194_304,
    "max_receive_size": 4_194_304,
    "connection_timeout": 10.0,
    "purge_wait_seconds": 1,
    "message_expiration": 3600,
    "max_batch_size": 10,
    "fanout_max_retries": 5,
    "grpc_keepalive_time": 30,
    "grpc_keepalive_timeout": 10,
    "grpc_permit_without_calls": True,
}

Option	Type	Default	Description
`wait_timeout`	`int`	`1`	Blocking receive timeout in seconds. Controls how long an internal `_get()` waits for a message before returning empty. Must be less than Celery's `drain_events` timeout (default 2s). Increase for higher-latency environments.
`auth_token`	`str \| None`	`None`	KubeMQ authentication token. Overrides the token in the broker URL if both are set.
`dead_letter_queue`	`str`	`""`	KubeMQ channel name for dead-letter messages. Messages that exceed `max_receive_count` are routed here.
`max_receive_count`	`int`	`0`	Maximum receive attempts before routing to the dead-letter queue. `0` disables the DLQ (messages redelivered indefinitely). Requires `dead_letter_queue` to be set.
`client_id_prefix`	`str`	`"celery"`	Prefix for KubeMQ client IDs. Each worker gets a unique ID: `{prefix}-queues-{random8}` and `{prefix}-pubsub-{random8}`.
`tls_enabled`	`bool`	`False`	Enable TLS for gRPC connections. Automatically set to `True` when using a `kubemq+tls://` URL scheme. Set explicitly to override URL-based detection.
`tls_cert_file`	`str`	`""`	Path to the client certificate file for mTLS authentication.
`tls_key_file`	`str`	`""`	Path to the client private key file for mTLS authentication.
`tls_ca_file`	`str`	`""`	Path to the CA certificate file for custom certificate-authority verification.
`max_send_size`	`int`	`4_194_304`	Maximum gRPC send message size in bytes (default 4 MB). Increase for large task payloads.
`max_receive_size`	`int`	`4_194_304`	Maximum gRPC receive message size in bytes (default 4 MB). Increase for large task results.
`connection_timeout`	`float \| None`	`None`	Initial gRPC connection timeout in seconds; `None` = SDK default. Read by both the transport and the result backend — see `examples/error_handling/reconnection.py`.
`purge_wait_seconds`	`int`	`1`	Seconds the server waits while purging a queue (an `ack_all` on the channel). The KubeMQ SDK's 60s default is too slow for empty-queue purges, so this defaults to `1`. Used by Celery's queue-reset / `_purge()` path.
`message_expiration`	`int`	`0`	Per-message TTL in seconds. Messages older than this are discarded by KubeMQ. `0` disables expiration. Maximum `86400` (24 hours). A task-level `expires` header takes precedence if set.
`max_batch_size`	`int`	`10`	Maximum messages per gRPC receive call. Higher values reduce round-trips but increase memory. Range: 1–100.
`fanout_max_retries`	`int`	`5`	Maximum re-subscription attempts when a fanout (Events) subscription encounters an error. Uses exponential backoff (1s, 2s, 4s, … max 30s).
`grpc_keepalive_time`	`int`	`30`	Seconds between gRPC keepalive pings. Prevents idle connections from being dropped by load balancers or firewalls.
`grpc_keepalive_timeout`	`int`	`10`	Seconds to wait for a keepalive ping response before considering the connection dead.
`grpc_permit_without_calls`	`bool`	`True`	Send keepalive pings even when there are no active RPCs. Keep `True` for long-lived connections that may be idle between task bursts.

wait_timeout must stay below Celery's drain_events timeout (default 2s). The transport's blocking receive runs inside Celery's event-drain loop; if wait_timeout meets or exceeds the drain timeout, the loop can deadlock instead of cycling. The default wait_timeout of 1 is safe.

result_backend_transport_options

The queue-peek result backend stores task results as KubeMQ Queue messages and retrieves them with a non-destructive peek. It runs its own KubeMQ client — configured independently of the broker — and accepts its own auth and TLS settings, gRPC message-size, keepalive, and connection-timeout tuning, plus two result-specific options. All thirteen keys are listed below.

result_backend_transport_options.py

app.conf.result_backend = "kubemq://localhost:50000"
app.conf.result_backend_transport_options = {
    "auth_token": "my-token",
    "tls_enabled": False,
    "tls_cert_file": "/path/to/cert.pem",
    "tls_key_file": "/path/to/key.pem",
    "tls_ca_file": "/path/to/ca.pem",
    "max_send_size": 4_194_304,
    "max_receive_size": 4_194_304,
    "connection_timeout": 10.0,
    "grpc_keepalive_time": 30,
    "grpc_keepalive_timeout": 10,
    "grpc_permit_without_calls": True,
    "result_channel_prefix": "celery-result-",
    "peek_timeout": 1,
}

Option	Type	Default	Description
`auth_token`	`str \| None`	`None`	KubeMQ authentication token for the result backend connection.
`tls_enabled`	`bool`	`False`	Enable TLS for the result backend gRPC connection.
`tls_cert_file`	`str`	`""`	Path to the client certificate file for mTLS.
`tls_key_file`	`str`	`""`	Path to the client private key file for mTLS.
`tls_ca_file`	`str`	`""`	Path to the CA certificate file.
`max_send_size`	`int`	`4_194_304`	Maximum gRPC send message size in bytes (4 MB) for the result backend client.
`max_receive_size`	`int`	`4_194_304`	Maximum gRPC receive message size in bytes (4 MB) for the result backend client.
`connection_timeout`	`float \| None`	`None`	Initial gRPC connection timeout in seconds for the result backend client; `None` = SDK default.
`grpc_keepalive_time`	`int`	`30`	Seconds between gRPC keepalive pings on the result backend connection.
`grpc_keepalive_timeout`	`int`	`10`	Seconds to wait for a keepalive ping response before the result backend connection is considered dead.
`grpc_permit_without_calls`	`bool`	`True`	Send keepalive pings on the result backend connection even when there are no active RPCs.
`result_channel_prefix`	`str`	`"celery-result-"`	Prefix for per-task result channel names. Each task's result is stored on `{prefix}{task_id}` (e.g. `celery-result-<task_id>`).
`peek_timeout`	`int`	`1`	Seconds the non-destructive peek waits for a result message before returning empty.

Result storage behavior

Results are stored on per-task channels named celery-result-{task_id}.
Retrieval uses peek_queue_messages(), which is non-destructive — multiple callers can read the same result independently.
Maximum result expiration is 86400 seconds (24 hours), a KubeMQ limitation. Celery's default result_expires of 24 hours matches the maximum exactly.
State transitions (PENDING → STARTED → SUCCESS) purge and rewrite the result message.
Chord support uses Celery's polling fallback via the chord_unlock task.

Transport Options

broker_transport_options

result_backend_transport_options

Result storage behavior

See also

Configuration reference

Result Backend

Configuration guide

On this page