Deploying on Kubernetes (Helm)

replicare ships a Helm chart — replicare-controller — that runs the daemon (replicare run) on Kubernetes. This page is the deployment guide; the chart's own README is the exhaustive values reference.

Two GHCR packages

Each vX.Y.Z release publishes two independent OCI artifacts to GHCR, stamped with the same version:

ArtifactPackagePull
Daemon imageghcr.io/rudimk/replicaredocker pull ghcr.io/rudimk/replicare:0.1.1
Helm chartghcr.io/rudimk/replicare-controllerhelm pull oci://ghcr.io/rudimk/replicare-controller --version 0.1.1

The chart's appVersion defaults image.tag to the matching daemon image, so a versioned chart install pulls a matched chart + image pair unless you override image.tag.

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

my-values.yaml is where you put your config and point at your image and secrets. There is no separate config file to manage — the chart renders your config value into a ConfigMap at /etc/replicare/config.yml and runs the daemon against it.

Configuring the daemon

config is a structured YAML object (the ergonomic default): Helm merges and overrides it across -f files and --set, so --set config.logging.level=debug changes just that field and leaves the rest intact. It is the exact replicare config — any engines, any number of sources, targets, and syncs.

image:
  repository: <your-registry>/replicare
  tag: <version>

config:
  logging: { level: info, format: json }
  observability: { status_addr: ":8080", metrics_addr: ":9090" }

  # replicare's own state — Postgres, always OUTSIDE this chart (see below).
  state_store:
    engine: postgres
    postgres: { host: state.rds.amazonaws.com, port: 5432, database: replicare_state,
                user: replicare, password: ${STATE_PW}, sslmode: require }

  sources:
    cache:
      engine: redis
      redis: { host: my-redis.default.svc.cluster.local, port: 6379, password: ${SRC_PW:-} }
  targets:
    replica:
      engine: redis
      redis: { host: master.my-ec.cache.amazonaws.com, port: 6379, tls: require,
               user: ${EC_USER}, password: ${EC_PW} }
  syncs:
    - { name: cache-to-replica, source: cache, targets: [replica], include: ["*"],
        tuning: { drain_interval: 1s, drain_batch: 1000 } }

secret:
  existingSecret: my-replicare-secrets   # provides STATE_PW / SRC_PW / EC_USER / EC_PW

Two 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 here — they render in block style.
  • Prefer a verbatim string for byte-exact control: set config to a block-scalar string and the chart emits it unchanged (Helm can't merge a string, but nothing is re-serialized either).

Secrets

Keep passwords and tokens out of config with ${VAR} placeholders — replicare expands env vars in any field. Supply them via a Secret, injected into the pod with envFrom:

  • secret.existingSecret — reference a Secret you manage (preferred for production; the chart creates none, so secrets never live in Helm state).
  • secret.env — a map the chart renders into a Secret (fine for dev).

Endpoints & monitoring

The pod serves the operator HTTP surface (see operations):

  • /healthz — liveness/readiness (both probes use it), on the status port.
  • /status — per-sync phase, progress, lag (JSON); what replicare status renders.
  • /metrics — Prometheus scrape.

The Service exposes the status and metrics ports. Set serviceMonitor.enabled: true to scrape /metrics via the Prometheus Operator.

Port alignment: service.ports.status / .metrics must match the addresses your config binds (observability.status_addr, metrics_addr). The defaults line up at :8080 / :9090; if you change one, change both.

Checking progress without Prometheus/Grafana

When you can't run a metrics stack next to the pod — e.g. the daemon runs inside the source cluster for network reasons — exec the CLI directly against the mounted config. The image is minimal, so target the binary rather than a shell (kubectl exec runs a command without needing /bin/sh):

kubectl exec deploy/replicare -- /usr/local/bin/replicare status /etc/replicare/config.yml   # live counts + delta backlog
kubectl exec deploy/replicare -- /usr/local/bin/replicare verify /etc/replicare/config.yml   # source<->target convergence (exit 0 = converged)

status is live by default (source/target row counts + per-target delta backlog); verify is a read-only convergence spot-check. Both accept --json, --sync <name>, and --watch <dur>. See the CLI reference and Checking progress from the CLI.

The runtime image is Chainguard wolfi-base, which also ships /bin/sh if you want an interactive session for ad-hoc debugging (kubectl exec -it deploy/replicare -- /bin/sh) — but the direct-exec form above needs no shell.

Single-active, rollouts & state

  • Keep replicaCount: 1. replicare is single-active per sync — a second daemon just stands by on the state store's ownership lock, so extra replicas are wasted and never run two writers. The chart uses a Recreate rollout so the old daemon fully exits (releasing its lock) before the new one starts.
  • Config changes roll the pod automatically: a checksum annotation over the rendered ConfigMap means helm upgrade after editing config restarts the daemon cleanly.
  • Pause one pipeline without touching the others by setting enabled: false on that sync (a per-pipeline switch; omit it or true to run). Because it's a config change, the upgrade's pod rollout applies it — it is start-time, not a live command. Prefer editing the sync's block in your values file by name, so you pause the pipeline you mean to:
    config:
      syncs:
        - name: pg-pipeline
          # ...
          enabled: false        # pauses THIS pipeline only
        - name: redis-pipeline
          # ...                  # (no enabled / true) keeps running
    
    then helm upgrade -f values.yaml. You can use --set, but it addresses syncs by array index, not name — config.syncs[0] is the first sync in your list, which may not be the one you want:
    # WRONG target if redis-pipeline is the 2nd sync — this pauses syncs[0] (e.g. pg-pipeline):
    helm upgrade ... --set-string 'config.syncs[0].enabled=false'
    # Pause the second sync instead:
    helm upgrade ... --set-string 'config.syncs[1].enabled=false'
    
    Verify which sync actually paused in the pod logs: sync disabled (paused); skipping sync=<name> for the paused one, and sync streaming sync=<name> for each still running. replicare status also shows [PAUSED] per sync. The paused sync's source capture stays installed, so re-enabling it drains the queued backlog with no data loss. Full semantics and the long-pause caveat (source-side delta growth): configuration.md → Pausing a sync.
  • The state store lives outside the chart, always. Every sync needs a Postgres state store (v1's only backend) — including Redis→Redis and MySQL→MySQL. Point state_store at your own managed Postgres (e.g. RDS). The chart never bundles it; it is control-plane bookkeeping, separate from your data.

Security

The container runs non-root (uid 65534), with a read-only root filesystem and all capabilities dropped (a writable emptyDir is mounted at /tmp). Grant the daemon's database/Redis roles the least privilege documented in deploy/ — grants-*.sql for Postgres/MySQL and acl-*-redis.txt for Redis (note the explicit +restore on Redis targets). Mount a CA bundle via extraVolumes/extraVolumeMounts if you use tls: verify-full.

Worked example: in-cluster Redis → ElastiCache

A common shape is replicating a self-managed Redis running in EKS to ElastiCache. Run replicare as a pod in the same cluster — with the AWS VPC CNI the pod gets a VPC IP, so it can reach both the in-cluster Redis (via its Service DNS) and ElastiCache (only reachable inside the VPC; open its security group to the node/pod SG). Watch-outs specific to that move:

  • Version direction: RESTORE rejects a newer-than-target payload, so the ElastiCache engine version must be ≥ the source version, or pre-flight blocks.
  • RESTORE must be permitted on the target (it is @dangerous; grant +restore via RBAC). Run replicare validate against the real endpoint first — some managed tiers restrict commands.
  • TLS + AUTH: set tls: require (or verify-full) and the RBAC user/password on the target block. Redis tls defaults to disable, so set it explicitly.
  • Cluster-mode ElastiCache: use mode: cluster seeded with the configuration endpoint (DB 0 only); cluster-mode-disabled connects as standalone to the primary endpoint.
  • Deletes lag the sweep interval, and big keys briefly block the source on DUMP — see the Redis engine page and troubleshooting.

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 -