replicare-controller Helm chart
Deploys the replicare daemon (replicare run) on Kubernetes: one replica that
brings up and streams every sync in your config, exposing the /status,
/healthz, and /metrics endpoints.
The chart is published as an OCI artifact at
ghcr.io/rudimk/replicare-controller — a package distinct from the daemon image
(ghcr.io/rudimk/replicare). Both are stamped with the same version on each
vX.Y.Z release.
Install
# From the published OCI chart (recommended) — pin the version:
helm install my-replicare oci://ghcr.io/rudimk/replicare-controller \
--version 0.1.1 \
-f my-values.yaml
# ...or from a checkout of the repo:
helm install my-replicare deploy/helm/replicare-controller \
-f my-values.yaml
The chart's appVersion defaults image.tag to the matching daemon image
(ghcr.io/rudimk/replicare:<version>), so a versioned OCI install pulls a matched
chart + image pair. Override image.tag to decouple them.
How it's configured
replicare is driven by one config file. This chart renders the config value
into a ConfigMap mounted at /etc/replicare/config.yml — you get replicare's full
expressiveness (any engines, any number of sources/targets/syncs). See the
configuration reference.
config is a structured YAML object by default, so Helm merges and overrides
it the normal way — layer -f files or --set config.logging.level=debug and only
that field changes:
config:
logging: { level: info, format: json }
observability: { status_addr: ":8080", metrics_addr: ":9090" }
state_store:
engine: postgres # always OUTSIDE this chart — point at your own Postgres
postgres: { host: state.rds, port: 5432, database: replicare_state, user: replicare, password: ${STATE_PW}, sslmode: require }
sources:
cache: { engine: redis, redis: { host: my-redis, port: 6379, password: ${SRC_PW:-} } }
targets:
ec: { engine: redis, redis: { host: my-elasticache, port: 6379, tls: require, user: ${EC_USER}, password: ${EC_PW} } }
syncs:
- { name: cache-to-ec, source: cache, targets: [ec], include: ["*"], tuning: { drain_interval: 1s } }
Two small caveats for the structured form: quote any all-digit scalar you inline
(e.g. a numeric-only password) so it decodes as a string, not an int; ${VAR}
placeholders need no quoting (they render in block style). If you'd rather hand the
daemon a byte-exact config, set config to a block-scalar string instead and
it is emitted verbatim.
Pausing a pipeline. Each sync (and cluster) takes an optional enabled: true|false
— set it false to pause just that pipeline; the others keep running. Because it's a
config change, the helm upgrade pod rollout applies it (it's start-time, not live).
Prefer editing the sync's block by name in your values so you pause the right one:
config:
syncs:
- name: pg-pipeline
enabled: false # pauses THIS pipeline only
- name: redis-pipeline
# ... # keeps running
--set works too but addresses syncs by array index, not name — config.syncs[0]
is the first sync in your list, which may not be the one you intend
(--set-string 'config.syncs[1].enabled=false' for the second, etc.). After the
rollout, confirm which sync paused in the pod logs (sync disabled (paused); skipping sync=<name> vs sync streaming sync=<name>) or via replicare status ([PAUSED]).
The paused sync's source capture stays installed, so re-enabling it drains the queued
backlog with no data loss (a long pause grows the source-side delta tables). Full
semantics: configuration.md → Pausing a sync.
Secrets stay out of config using ${VAR} placeholders (replicare expands env vars
in any field), supplied via a Secret:
secret:
# Option A — let the chart create a Secret (fine for dev):
env: { EC_USER: replicare, EC_PW: the-token }
# Option B — reference a Secret you manage (preferred for prod; `env` is ignored):
existingSecret: my-replicare-secrets
The pod loads the Secret via envFrom, so every key becomes an env var the config
can reference.
Key values
| Value | Default | Notes |
|---|---|---|
image.repository / image.tag | ghcr.io/rudimk/replicare / chart appVersion | the daemon image (a separate GHCR package from this chart) |
replicaCount | 1 | keep at 1 — single-active per sync; more just stand by |
config | a Redis→Redis sample | your full replicare config as a structured map (mergeable), or a string for a verbatim config |
secret.existingSecret | "" | reference an existing Secret for ${VAR} values |
secret.env | {} | chart-managed Secret (dev) |
service.ports.status / .metrics | 8080 / 9090 | must match observability.status_addr/metrics_addr in config |
serviceMonitor.enabled | false | scrape /metrics via the Prometheus Operator |
resources, nodeSelector, tolerations, affinity | — | standard scheduling knobs |
extraVolumes / extraVolumeMounts | [] | e.g. a CA bundle for tls: verify-full |
Notes & gotchas
- Single active. The rollout is
Recreateso the old daemon exits (releasing its ownership lock) before the new one starts — never two writers. Scaling above 1 replica is unsupported. - Port alignment. The chart's Service/probe ports must match the addresses your
configbinds (observability.status_addr,metrics_addr). Defaults line up at:8080/:9090. - Scraping metrics. With the Prometheus Operator, set
serviceMonitor.enabled=true. Without it (e.g. an OpenTelemetry Collector or plain Prometheus), use the scrape job in the metrics-scraping guide. - Grafana dashboard. Once
/metricsis scraped (viaserviceMonitor.enabledor your own scrape job), importdeploy/grafana/replicare-dashboard.json— it has a configurable Prometheus data source and covers per-table backlog/lag, catch-up, initial-copy progress, throughput, and errors. - State store. Every sync needs a Postgres state store (v1's only backend),
including Redis→Redis and MySQL→MySQL. Point
state_storeat a reachable Postgres. - Config changes roll the pod automatically (a checksum annotation), so
helm upgradeafter editingconfigrestarts the daemon cleanly. - Least privilege. The container runs non-root (uid 65534), read-only root FS,
all capabilities dropped. Grant the daemon roles per
deploy/(grants-*.sql,acl-*-redis.txt).
Validate before applying
helm lint deploy/helm/replicare-controller
helm template my-replicare deploy/helm/replicare-controller -f my-values.yaml | kubectl apply --dry-run=client -f -