Skip to main content

Overview

Debezium Server is a standalone change data capture (CDC) application. It reads a database’s change stream — the write-ahead log for PostgreSQL, the binlog for MySQL — turns every row-level insert, update and delete into an event, and delivers it to a messaging system, with no Kafka Connect cluster involved. This template runs one Debezium Server connector: one source database and one sink. It deploys neither the source nor the sink — both must already exist and be reachable from the workload. Every credential the connector uses comes from a dictionary secret you create before installing, so no password passes through Helm or lands in the release.
This template deploys into an existing GVC that you already have. It does not create or manage a GVC.

What Gets Created

Prerequisites

Two things must be in place before you install: a source database configured for CDC, and the credentials secret.
1

Configure the source database for change data capture

A source left on default settings produces a connector that starts, connects and never emits a change, so do this first.PostgreSQL — enable logical replication in postgresql.conf and restart the server:
Create the publication named in source.postgres.publicationName and give the connector user replication rights:
Debezium creates the replication slot named in source.postgres.slotName on first connect.MySQL — enable row-based binary logging in my.cnf and restart the server:
MongoDB, SQL Server and Oracle — follow the setup section of the matching upstream connector guide. This template has no extra steps for them.
2

Create the credentials secret

One dictionary secret holds every credential the connector needs. Secrets are org-level, so no GVC flag is involved, and secret names are org-wide — give each release its own. Include only the keys your configuration uses:For the default PostgreSQL-to-Kafka shape that is a single key:
Add one --entry per extra key, for example --entry kafkaSaslPassword='YOUR-SASL-PASSWORD' for a SASL-authenticated Kafka. Read the secret back with cpln secret reveal SECRET_NAME -o yaml.Set credentialsSecretName to this name.
Create the secret before installing, or the deployment wedges silently. The template refuses to render when credentialsSecretName is blank, but a name that points at a secret which does not exist — or that lacks a key your configuration references — installs successfully and then never starts. The container never runs, so cpln logs returns zero lines. The one place the reason appears is status.versions[].message:
Use get-deployments — plain cpln workload get has no versions key. Creating the missing secret repairs the deployment on its own within several minutes, or run cpln workload force-redeployment RELEASE_NAME-debezium --gvc GVC_NAME to skip the wait.
The Kinesis and Pub/Sub sinks also need a Control Plane cloud account — see Sink.

Installation

Install from the marketplace registry with your secret, your source connection and your Kafka brokers. Replace DATABASE_HOST, DATABASE_NAME, DATABASE_USER and KAFKA_BOOTSTRAP_SERVERS with your own values:
For any other source or sink, put the settings from Configuration in a values file and pass it with -f. Or follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Each block below is the shipped default for that part of values.yaml.

Image and Resources

The workload always runs exactly one replica — Debezium Server is a single connector process, and there is no replica knob.

Source Connection

source.database.port follows the source type when left empty; the shipped 5432 suits PostgreSQL, so change it for any other source. serverName becomes the prefix of every topic, stream or subject the connector writes to.

Connector-Specific Settings

Only the block that matches source.type is used.
For PostgreSQL with heartbeatIntervalMs above 0, a startup step runs before the server: it creates a debezium_heartbeat table (columns id and ts, seeded with row 1) and creates the replication slot if it does not exist yet. That table is what the commented heartbeatActionQuery example updates. If the step fails it logs a warning and Debezium Server starts anyway, so read the logs after enabling it.

Offset Storage

Offsets record how far through the change stream the connector has read, so a restart resumes instead of re-snapshotting the source.

Schema History

Used only by MySQL and SQL Server, which must track DDL changes. The backends are the same three as offset storage.

Error Retries

Sink

Set sink.type and fill in only that sink’s block. Every sink writes one destination per captured table, named from its prefix and the table.
Kafka with SASL needs both saslMechanism and saslUsername set, plus kafkaSaslPassword in the secret. The template always generates a PlainLoginModule JAAS configuration, which matches saslMechanism: PLAIN. Pulsar token auth needs both authPluginClassName (for example org.apache.pulsar.client.impl.auth.AuthenticationToken) and authEnabled: true, plus pulsarAuthToken in the secret — set all three together. Kinesis and Pub/Sub authenticate through a Control Plane cloud account instead of keys. Set cloudAccount.enabled: true and cloudAccount.name to your cloud account. The template links that cloud account to the workload identity — with the pubsub scope for GCP — but attaches no AWS IAM policy and no GCP role, so grant the identity access to your stream or topic yourself. Inspect the identity with:
The cloud sinks have not been verified end to end on this version.

Serialization Format

The schema registry is used only when key or value is avro or protobuf and url is set. With a username, put the password in the secret as schemaRegistryPassword.

Storage

Used only when a volume is created (see Offset Storage).

Firewall

The workload has no public endpoint. firewall.internal controls who in Control Plane can reach port 8080; firewall.external.outboundAllowCIDR must allow the source database and the sink. A firewall change can take several minutes to take effect.

Connecting

Debezium Server exposes only health endpoints; change events go to your sink. To check health from your own machine, tunnel to the workload and query it:
To confirm events flow, read the connector log for snapshot and streaming progress or errors, then change a row in a captured table and look for the event in your sink:

Operations

Backing Up

With file storage the offsets and schema history live on the RELEASE_NAME-debezium-data volume, which Control Plane snapshots; a final snapshot is kept for 7 days when the volume is deleted. Take one on demand before a risky change:
With redis or jdbc storage, back up that store instead. The captured data itself lives in the source database and the sink.

Restoring a Backup

Restoring offsets from a volume snapshot has not been verified on this template. If offsets are lost, the connector re-snapshots the source on its next start, then resumes streaming — correct, but expensive on large tables.

Upgrading from 1.1.x

Version 1.2.0 moves every credential out of values. The source password, the offset and schema-history store passwords, every sink credential and the schema-registry password are now keys in the credentials secret, and five switches replace settings that used to be inferred from a credential being set: source.mongodb.useConnectionString, and authEnabled on source.offset.redis, source.schemaHistory.redis, sink.redis and sink.pulsar.
  1. Create the credentials secret with a key for every credential your release uses (see Prerequisites).
  2. Remove every removed credential from your values file, set credentialsSecretName, and set the new switches that apply.
  3. Upgrade with the full values file:
The values file must use the chart’s nesting, exactly as the blocks in Configuration show. A flat dotted key is accepted without error and silently changes nothing. An upgrade that still carries a removed credential is refused before anything is changed, with an error such as:

Scaling and Availability

The connector is a single replica and cannot be scaled out. For PostgreSQL behind a failover-capable cluster, keep source.postgres.slotDropOnStop: false and set source.postgres.heartbeatIntervalMs (for example 5000); the heartbeat also keeps the slot advancing on a low-traffic source.

Rotating Credentials

Apply the whole secret with the new value — cpln secret update cannot change values — then force a redeployment, because a running replica keeps the old value:
Include every key the secret already holds in rotate.yaml; the apply replaces the whole secret.

Removing a Connector

helm uninstall does not touch the source database. On PostgreSQL the replication slot stays behind, and PostgreSQL retains WAL for an inactive slot indefinitely until the disk fills. Drop it once the connector is gone:
Use the name from source.postgres.slotName.

Troubleshooting

Cause: the credentials secret, or a key your configuration references, does not exist. Fix: read status.versions[].message with cpln workload get-deployments RELEASE_NAME-debezium --gvc GVC_NAME -o yaml, create the secret or add the key, and wait or force a redeployment.
Cause: the source is not configured for CDC — PostgreSQL without wal_level = logical or the publication, MySQL without row-based binlog — or the table is outside tableIncludeList. Fix: complete the source steps in Prerequisites, then check the connector log for snapshot and streaming messages.
Cause: a replication slot is not advancing — the connector was removed and its slot left behind, or a quiet source never moves the slot forward. Fix: drop abandoned slots (see Removing a Connector) and set source.postgres.heartbeatIntervalMs on a low-traffic source.
Cause: credentialsSecretName is blank. Fix: set it to the name of your credentials secret.
Cause: your values still carry a credential that 1.2.0 moved into the secret. Fix: follow Upgrading from 1.1.x.
Cause: the offsets were lost — the volume was deleted with file storage, or the Redis key or JDBC table was cleared. Fix: keep the volume or store between reinstalls; see Restoring a Backup.

Important Notes

  • Configure the source for CDC before installing; otherwise the connector runs healthy and emits nothing.
  • Deleting the volume (or clearing the Redis key or JDBC table) loses the offsets and forces a full re-snapshot.
  • Drop the PostgreSQL replication slot when you remove a connector, or retained WAL will fill the source disk.
  • One release runs one connector; capture several sources with several releases, each with its own source.postgres.slotName and credentials secret.
  • After rotating a credential in the secret, force a redeployment — a running replica keeps the old value.

External References