# Configuration Reference (/integrations/rayserve/reference/configuration)



This page is the authoritative reference for configuring `kubemq-rayserve`: every
`KubeMQAdapterConfig` field, its default and validation rule, the package dependencies, and the
broker the adapter connects to. For the adapter methods, autoscaling policy, and metrics surface,
see the [API reference](/integrations/rayserve/reference/api). For task-oriented walkthroughs see the
[configuration guide](/integrations/rayserve/how-to/configuration) and [connection & security guide](/integrations/rayserve/how-to/connection-security).

## KubeMQAdapterConfig [#kubemqadapterconfig]

`KubeMQAdapterConfig` is a Pydantic `BaseModel`. It is passed via `TaskProcessorConfig.adapter_config`
when deploying a Ray Serve `@task_consumer`, or directly to `KubeMQTaskProcessorAdapter(config)` for
standalone use. Every field has a default, so `KubeMQAdapterConfig()` is valid and connects to
`localhost:50000`.

<TypeTable
  type="{
  address: { type: 'str', default: '&#x22;localhost:50000&#x22;', description: 'KubeMQ broker address (host:port).' },
  client_id: { type: 'str', default: '&#x22;&#x22;', description: 'Client identifier. Auto-generated rayserve-{8hex} suffix if empty.' },
  auth_token: { type: 'str', default: '&#x22;&#x22;', description: 'JWT authentication token.' },
  tls: { type: 'bool', default: 'False', description: 'Enable TLS connection.' },
  tls_cert_file: { type: 'str', default: '&#x22;&#x22;', description: 'mTLS client certificate path.' },
  tls_key_file: { type: 'str', default: '&#x22;&#x22;', description: 'mTLS client key path.' },
  tls_ca_file: { type: 'str', default: '&#x22;&#x22;', description: 'CA certificate path.' },
  result_channel_prefix: { type: 'str', default: '&#x22;rayserve-result-&#x22;', description: 'Prefix for result storage queue channels.' },
  result_expiry_seconds: { type: 'int', default: '3600', description: 'Result TTL in seconds. Constrained to 0..86400 (1 hour default).' },
  visibility_timeout: { type: 'int', default: '120', description: 'Reserved for future SDK support — not currently wired.' },
  consumer_poll_timeout_seconds: { type: 'int', default: '1', description: 'Queue poll wait timeout (seconds).' },
  max_send_size: { type: 'int', default: '4194304', description: 'Max message send size in bytes (4 MB).' },
  max_receive_size: { type: 'int', default: '4194304', description: 'Max message receive size in bytes (4 MB).' },
  sync_inference_timeout: { type: 'int', default: '30', description: 'Default timeout for sync Query inference (seconds).' },
  on_dlq: { type: 'Callable[[str, str], None] | None', default: 'None', description: 'Callback (task_id, error) -> None fired when a task moves to the DLQ.' },
}"
/>

```python title="config.py"
config = KubeMQAdapterConfig(
    address="kubemq:50000",
    auth_token="your-jwt-token",
    tls=True,
    tls_ca_file="/etc/kubemq/ca.pem",
    result_expiry_seconds=7200,
    sync_inference_timeout=45,
    on_dlq=lambda task_id, error: print(f"DLQ {task_id}: {error}"),
)
```

<Callout type="warn">
  `result_expiry_seconds` is validated with `ge=0, le=86400` — values outside `0..86400` raise a
  Pydantic `ValidationError` at construction. `auth_token` is marked `repr=False` and `on_dlq` is
  excluded from serialization, so neither leaks into `model_dump()` or log output.
</Callout>

## Validation and serialization [#validation-and-serialization]

Two field-level choices make the model safe to serialize even though it carries a callback:

* `model_config = {"arbitrary_types_allowed": True}` is required because `on_dlq` is a `Callable`,
  which Pydantic would otherwise reject as a field type.
* `auth_token` is declared with `repr=False`, so it never appears in `repr(config)` or log output,
  and `on_dlq` is declared with `exclude=True`, so it is dropped from `model_dump()` /
  `model_dump_json()`. Dumping the config to JSON therefore yields a clean, secret-free,
  callable-free record.

```python title="config.py"
result_expiry_seconds: int = Field(default=3600, ge=0, le=86400)
auth_token: str = Field(default="", repr=False)
on_dlq: Callable[[str, str], None] | None = Field(default=None, exclude=True)

model_config = {"arbitrary_types_allowed": True}
```

## TLS modes [#tls-modes]

The four TLS fields map directly onto the SDK's `TLSConfig`. Each is normalized to `None` when
empty, so one config shape covers plaintext, server-auth TLS, and mutual TLS.

| Mode                | `tls`   | `tls_ca_file` | `tls_cert_file` | `tls_key_file` |
| ------------------- | ------- | ------------- | --------------- | -------------- |
| Plaintext (default) | `False` | —             | —               | —              |
| TLS (server auth)   | `True`  | required      | —               | —              |
| Mutual TLS          | `True`  | required      | required        | required       |

The [connection & security guide](/integrations/rayserve/how-to/connection-security) walks through each mode with
runnable examples.

## Dependencies and supported Python [#dependencies-and-supported-python]

`kubemq-rayserve` targets CPython 3.10 through 3.13 (`requires-python = ">=3.10"`).

| Dependency   | Constraint | Purpose                                                     |
| ------------ | ---------- | ----------------------------------------------------------- |
| `kubemq`     | `>=4.1.5`  | KubeMQ Python SDK (Queues, Queries, Events clients).        |
| `ray[serve]` | `>=2.50.0` | Ray Serve runtime and the `TaskProcessorAdapter` framework. |
| `pydantic`   | `>=2.0`    | Config model validation.                                    |

```bash title="install"
uv pip install kubemq-rayserve
```

## Broker requirement [#broker-requirement]

`kubemq-rayserve` is a client-side Python package built on native gRPC SDK clients — it needs **no
connector enable flag** on the broker. It talks to the standard gRPC port `50000`, which is always
available on a running KubeMQ server. For local development, start one with Docker:

<RunKubeMQ ports="[50000, 9090]" />

<Callout type="info">
  Port `50000` is the gRPC endpoint the adapter and the `kubemq_queue_depth_policy` autoscaler use.
  Port `9090` is the shared HTTP server (REST and the AI-agent connectors), and the dashboard runs
  on port `8080` — neither is required by the adapter itself.
</Callout>