Skip to content

Deploy Read Replicas

This walkthrough shows how to add extra query capacity to a package that is already deployed, using the bundled read-replica template.

read-replica is a bundled template supplied with kdb Insights Enterprise. It stands up a second set of data access processes reading the same idb and hdb volumes as an existing deployment, optionally behind their own aggregator and resource coordinator, without changing the primary deployment. You author nothing: the template is available to any package you can deploy against, and you deploy it by name.

Use it to:

  • Add query capacity for a heavy reporting or backfill workload.
  • Isolate an expensive or experimental query workload from the primary deployment.
  • Run a debug instance with different resources, labels, entrypoints, or Python dependencies.

This walkthrough covers read-replica end to end. For the general mechanism it is built on, refer to deploying a template by name.

Prerequisites

  • The kxi CLI installed and authenticated against your kdb Insights Enterprise environment.
  • Execute entitlement on the parent package, which is the access level that permits deploying and tearing it down.
  • The parent package already deployed under its own name. The template asserts this and fails the request if the parent is not deployed, because the replica needs the parent's live stream bus and mount configuration.
  • A parent package with a database and idb/hdb mounts. The replica mounts the parent's existing volume claims.

The parent needs idb and hdb mounts

The template attaches the parent's {package-name}-idb and {package-name}-hdb volume claims by name, and its data access processes mount rdb, idb and hdb. A parent deployed without those mounts, such as an RDB-only package, has no claims for the replica to attach to.

1. Deploy the parent package

The replica reuses the parent's mounts, stream bus, and storage manager, so the parent must be running first:

kxi pm push ./insights-demo
kxi pm deploy insights-demo
kxi pm list deployment

2. Deploy a read replica

kxi pm deploy insights-demo --template read-replica

That is the whole command, because every value has a default. It creates a deployment named insights-demo-rr: the template's manifest declares a fixed name, so repeat calls target that same deployment rather than generating a new one.

To supply values inline:

kxi pm deploy insights-demo --template read-replica \
  --set replicas=3 \
  --set resources.requests.memory=8Gi \
  --set resources.limits.memory=16Gi

Or from a file:

# rr-values.yaml
replicas: 3
resources:
  requests: { cpu: "2", memory: "8Gi" }
  limits:   { cpu: "4", memory: "16Gi" }
agg: 2

kxi pm deploy insights-demo --template read-replica -f rr-values.yaml

Flags that do not apply to a template deploy

The positional VERSION argument and --force are ignored, because the replica tracks the parent's deployed version. --db and --pipeline are rejected outright, because a template deploy stands up exactly what the template defines.

3. Verify

The replica is a deployment in its own right, labelled as a template instance with insights.kx.com/template-instance: read-replica:

kxi pm list deployment

The template column shows read-replica for the instance, and is empty for the parent package's own deployment.

4. Change the replica

Re-run the deploy with different values. Without passing a --name this will update the existing replica rather than adding a second one. If you wish to add a second replica, you can use --name to give it a unique name:

kxi pm deploy insights-demo --template read-replica --set replicas=5 # updates the existing read replica
kxi pm deploy insights-demo --template read-replica --name insights-demo-rr2 # creates a second read replica

5. Tear it down

Tear down by deployment name, not package name. Tearing down insights-demo removes the parent, not the replica:

kxi pm teardown insights-demo-rr

Values reference

All values are optional. The defaults below are declared inline in the template and merged at the lowest priority, under -f files applied left to right, then --set-file, then --set. The merge is deep, so --set resources.requests.memory=8Gi keeps the default CPU request rather than replacing the whole resources block. Values are YAML-coerced, so replicas=3 arrives as an integer.

Value Default Effect
replicas 1 Number of data access instances in the replica.
resources.requests.cpu / .memory "1" / "1Gi" Per-instance resource requests.
resources.limits.cpu / .memory "2" / "2Gi" Per-instance resource limits.
deps "" Comma-separated requirement strings, appended to the instance's dependencies. They never replace the parent's, for example "my-lib>=1.0,other-pkg".
entrypoints {} Per-role entrypoint override, for example {default: "init.q"}. Empty means the parent package's entrypoints are used.
labels {} Extra labels applied to the replica's shard, for example {team: indigo}. Merged alongside the kxname label that identifies the parent package.
agg 0 Aggregator pod count. 0 means not deployed.
rc 0 Resource coordinator pod count. 0 means not deployed.

The recognized entrypoints roles are default, data-access, aggregator, resource-coordinator, and storage-manager. default is the fallback for any role not listed.

List a template's values from the CLI

--help on a deploy command prints the template's values and their defaults as a table, so you do not have to read them from this page:

kxi pm deploy insights-demo --template read-replica --help

The package named in the command must already exist on the server, because the values are read back from it. Without it, or if the package cannot be resolved, the table is omitted and the rest of the help still prints.

agg and rc are a pair: setting either to a positive size implicitly deploys the other at size 1, because a query-routing layer needs both to function. Leave both at 0 for a plain set of extra data access processes with no router of their own.

# Extra query capacity behind its own router
kxi pm deploy insights-demo --template read-replica --set replicas=4 --set agg=2

# A debug instance with an extra Python dependency and its own entrypoint
kxi pm deploy insights-demo --template read-replica \
  --set deps="pandas>=2.0" \
  --set entrypoints.default=src/debug.q

An entrypoints value must name a q file that already exists in the parent package, src/debug.q included. The replica runs the parent's files; it does not add any of its own.

What gets created

Rendering read-replica against a package produces one assembly containing:

  • A shard named after the deployment, with a single da instance group over mountList: [rdb, idb, hdb], sized by replicas and using the resources values.
  • Mounts pointing at the parent package's existing volume claims, {package}-idb and {package}-hdb, plus a stream rdb mount. The replica reads the same data; it does not copy it.
  • A deployment configuration that inherits the parent deployment's stream bus configuration and sets KXI_SM_LABEL_SELECTOR to the parent's storage manager, so the replica follows the parent's write-down cycle.
  • A router section, only when agg or rc is set.
  • Manifest overrides carrying deps, appended to the assembly's dependencies, and entrypoints, applied as KXI_PACKAGE_ENTRYPOINTS on the matching roles.

The replica's version tracks the parent package's version.

A package can also ship its own template named read-replica. A package-owned template of the same name takes precedence over the bundled one, so you can supply a variant without renaming it.

The equivalent REST call is POST /v2/deployments with template set to read-replica, documented in the Package Manager API reference.

Troubleshooting

Message Cause Fix
read-replica.yaml.j2: Parent package (<name>) must be deployed. (HTTP 400) The template's precondition. The replica needs the parent's live bus and mount configuration. Run kxi pm deploy <name> first, then deploy the replica.
Template 'read-replica' rendered no deployable components. (HTTP 400) Every rendered document was dropped, typically because of an undefined variable, such as a parent deployment with no bus configuration. Check that the deployed parent assembly exposes spec.bus, and that it has a database with the expected idb/hdb mounts. Which variable was undefined appears only in the package manager service logs.
Template 'read-replica' not found for package '<name>'. (HTTP 404) Most often a typo in the --template value. Check the spelling. The bundled template's name is exactly read-replica.
--db/--pipeline cannot be combined with --template. Component filters apply to package deploys only. A template deploy renders exactly what the template defines. Drop --db and --pipeline.
Invalid format for --set: ... Expected KEY=VALUE. A --set argument without =. Use --set key=value, nesting with dots, for example --set resources.limits.cpu=4.

Next steps

Back to top