> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Helm values-large.yaml — enterprise topology

> W9.3 — 4-tier topology overlay for sustained 5K-RPS /recommend, 500-RPS /respond, 50K-row batch decisioning per minute.

## Usage

```bash theme={null}
helm upgrade --install kaireon ./helm \
  -f helm/values.yaml \
  -f helm/values-large.yaml
```

The overlay layers on top of the canonical `values.yaml`. Anything not
listed in `values-large.yaml` inherits from the canonical file.

## Tier layout

| Tier                | Replicas                | Resources                              | Notes                                                                     |
| ------------------- | ----------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| `api`               | 6 → 50 (HPA)            | 4 GiB / 2 CPU req → 8 GiB / 4 CPU lim  | Dedicated `kaireon.ai/tier=api` node group + zone-strict topology spread. |
| `cron`              | 7 CronJobs (W8.2)       | 64 MiB / 100 mCPU req                  | Independent schedules; concurrencyPolicy: Forbid.                         |
| `worker`            | 4 → 30 (KEDA)           | 4 GiB / 2 CPU req → 8 GiB / 4 CPU lim  | BullMQ batch jobs.                                                        |
| `mlWorker`          | 2 (fixed)               | 8 GiB / 2 CPU req → 16 GiB / 8 CPU lim | LightGBM training; CPU-only by default. No HPA/KEDA in this overlay.      |
| `outboxPublisher`   | 3 + PDB minAvailable: 2 | 512 MiB / 200 mCPU req                 | Faster poll (1s) for low publish-tail latency.                            |
| `stream` (optional) | 2                       | 2 GiB / 1 CPU req                      | Activate with `FLOW_STREAMING_ENABLED=true` AND a real broker.            |
| `mcp` (optional)    | 2                       | 1 GiB / 500 mCPU req                   | Activate with `mcp.dedicated: true` to isolate LLM-driven MCP traffic.    |

## Datastore expectations

* `postgres.mode: external` — pin to managed RDS / Aurora / Supabase.
* `redis.mode: external` + `redis.cluster: true` — single-node Redis
  is the wrong shape at this scale.
* `opensearch.enabled: true` — ts-vector tsearch is fine for small
  fleets but caps out under sustained search load.
* `eventbus.backend: kafka` (or `kinesis` / `pulsar`).
* `interactionStore.backend: dynamodb` — partition-by-customerId
  scales horizontally without table-bloat pain.

## Large-overlay-only keys

The base chart at `helm/values.yaml` does not define the keys below — they
exist only inside the overlay and are consumed by the chart templates as
high-level aliases over the per-backend blocks (`kafka.*`, `dynamodb.*`,
etc.) that the base chart already documents in
[Helm Chart Reference](/self-host/deploy/helm-reference).

### `postgresExternalReplicas`

Defined in `helm/values-large.yaml:163`. A single integer that records how
many PostgreSQL read replicas the operator has provisioned alongside the
primary. Advisory only — the chart does not provision RDS replicas; chart
consumers (the read-only analytics path) read this number when deciding
whether to fan out reads.

| Key                        | Type | Default (large) | Description                                                                  |
| -------------------------- | ---- | --------------- | ---------------------------------------------------------------------------- |
| `postgresExternalReplicas` | int  | `2`             | Replica count behind `postgres.mode: external`. Set to `0` for primary-only. |

### `eventbus.*`

Defined in `helm/values-large.yaml:173-175`. High-level alias that selects
one of the per-backend event-bus blocks. The base chart drives the same
choice from `config.EVENT_PUBLISHER` (`redis | kafka | msk | eventbridge |
kinesis`); the overlay surfaces it as a single key for callers who prefer
to read the topology in one place.

| Key                | Type   | Default (large) | Description                                                                                                                                |
| ------------------ | ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `eventbus.enabled` | bool   | `true`          | Whether an external event bus is in use. When `false`, the chart falls back to `config.EVENT_PUBLISHER: redis`.                            |
| `eventbus.backend` | string | `kafka`         | One of `kafka`, `kinesis`, `pulsar`. The matching per-backend block (`kafka.brokers`, `kinesis.streamName`, etc.) must still be filled in. |

### `interactionStore.*`

Defined in `helm/values-large.yaml:177-178`. Alias for
`config.INTERACTION_STORE`. Selects which backend receives the
partitioned interaction-history writes that back the `/api/v1/respond`
write path and the engagement-health recompute cron.

| Key                        | Type   | Default (large) | Description                                                                                                                                                                           |
| -------------------------- | ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interactionStore.backend` | string | `dynamodb`      | One of `pg`, `dynamodb`, `scylla`, `cassandra` (mid-tier). The target store (DynamoDB table, Scylla cluster, Keyspaces keyspace) is operator-provisioned before the value is flipped. |

The chart does not create the target store. Mismatches between
`interactionStore.backend` and the per-backend block are left to the
operator — the connector boots only when its block is enabled.

## Honest limits

* These numbers are **design targets**, not benchmarked. The `perf/baselines/`
  directory holds real numbers as they're measured. Run k6 against the
  installed cluster before committing to the topology in production.
* `mlWorker` resource numbers assume CPU-only inference. GPU support
  is roadmap and would change the resource profile dramatically.
* The streaming + mcp tiers are gated **off** by default in this
  overlay because both require operator-driven setup beyond the chart
  (broker provisioning, MCP-tool authorization).
* `postgresExternalReplicas` is advisory — the chart does not create
  replicas, fail closed if the count is wrong, or rebalance reads when
  a replica is removed. Operator owns provisioning and connection-string
  publication.
* `eventbus.backend` and `interactionStore.backend` only select the wire
  path; the actual broker / table / keyspace must already exist when the
  chart is applied. The chart does not create AWS or self-managed
  infrastructure on the operator's behalf.