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 Create the publication named in Debezium creates the replication slot named in MongoDB, SQL Server and Oracle — follow the setup section of the matching upstream connector guide. This template has no extra steps for them.
postgresql.conf and restart the server:source.postgres.publicationName and give the connector user replication rights:source.postgres.slotName on first connect.MySQL — enable row-based binary logging in my.cnf and restart the server: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:Add one
For the default PostgreSQL-to-Kafka shape that is a single key:
--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.Installation
Install from the marketplace registry with your secret, your source connection and your Kafka brokers. ReplaceDATABASE_HOST, DATABASE_NAME, DATABASE_USER and KAFKA_BOOTSTRAP_SERVERS with your own values:
-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 ofvalues.yaml.
Image and Resources
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 matchessource.type is used.
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
Setsink.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:
Serialization Format
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
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:
Operations
Backing Up
Withfile 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:
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.
- Create the credentials secret with a key for every credential your release uses (see Prerequisites).
- Remove every removed credential from your values file, set
credentialsSecretName, and set the new switches that apply. - Upgrade with the full values file:
Scaling and Availability
The connector is a single replica and cannot be scaled out. For PostgreSQL behind a failover-capable cluster, keepsource.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:
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:
source.postgres.slotName.
Troubleshooting
Workload never starts and logs are empty
Workload never starts and logs are empty
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.Connector is healthy but no events arrive
Connector is healthy but no events arrive
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.Source disk fills with WAL
Source disk fills with WAL
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.Install or upgrade fails with credentialsSecretName is required
Install or upgrade fails with credentialsSecretName is required
Cause:
credentialsSecretName is blank. Fix: set it to the name of your credentials secret.Upgrade fails with was REMOVED
Upgrade fails with was REMOVED
Cause: your values still carry a credential that 1.2.0 moved into the secret. Fix: follow Upgrading from 1.1.x.
Connector re-snapshots the whole source
Connector re-snapshots the whole source
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.slotNameand credentials secret. - After rotating a credential in the secret, force a redeployment — a running replica keeps the old value.
External References
- Debezium Server documentation
- Debezium connectors
- Debezium PostgreSQL connector
- Debezium MySQL connector
- CDC Pipeline template — PostgreSQL Highly Available, Kafka and Debezium Server in one install