Debezium Server - Control Plane

Overview

Debezium Server is a standalone Change Data Capture (CDC) application that tails a database’s transaction log and streams row-level change events to a messaging system. Unlike Debezium connectors that run inside Kafka Connect, Debezium Server runs as a self-contained process — no Kafka Connect cluster required. This template deploys Debezium Server on Control Plane with configurable source connectors, multiple sink options, flexible offset storage, and Universal Cloud Identity integration for AWS and GCP sinks.

Architecture

Debezium workload — Reads the source database’s replication stream (WAL for PostgreSQL, binlog for MySQL, oplog for MongoDB), converts each change to a structured event, and delivers it to the configured sink. Stateful when using file-based offset storage; stateless when using Redis or JDBC offset storage.
pgdog.toml / application.properties — Rendered as a secret and mounted at startup. Defines the source, sink, serialization format, and offset storage settings.

What Gets Created

Standard Debezium Server Workload — Single-replica CDC workload.
Volume Set — For offset and schema history persistence (only when using file offset storage).
Identity & Policy — Identity with access to credential secrets, and cloud account access when using Kinesis or Pub/Sub sinks.
Secrets — Three opaque secrets: Debezium configuration (application.properties), credentials (passwords for source, sink, offset storage), and a startup entrypoint script.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

Source Database

Configure your source database to allow Debezium to read its replication stream before deploying.

PostgreSQL
MySQL
MongoDB
SQL Server

Enable logical replication

Add the following to postgresql.conf and restart PostgreSQL:

wal_level = logical
max_replication_slots = 4
max_wal_senders = 4

When using the PostgreSQL Highly Available template, set postgres.walLevel: logical in its values before installing.

Create a publication

CREATE PUBLICATION dbz_publication FOR ALL TABLES;

Debezium creates the replication slot automatically on first connect.

Grant permissions

GRANT USAGE ON SCHEMA public TO debezium;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO debezium;
ALTER USER debezium REPLICATION;

Enable binary logging

Add the following to my.cnf and restart MySQL:

server-id         = 1
log_bin           = mysql-bin
binlog_format     = ROW
binlog_row_image  = FULL

Grant permissions

GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT
  ON *.* TO 'debezium'@'%';

MongoDB must be running as a replica set. Debezium tails the oplog; no additional configuration is needed beyond connection credentials with read access to the databases you want to capture.

CDC must be enabled on the SQL Server instance and on each database/table you want to capture:

EXEC sys.sp_cdc_enable_db;
EXEC sys.sp_cdc_enable_table @source_schema = 'dbo', @source_name = 'my_table', @role_name = NULL;

Cloud Sinks (Kinesis / Pub/Sub)

For AWS Kinesis or GCP Pub/Sub sinks, set up a Cloud Account in Control Plane before installing:

Kinesis: Create an AWS Cloud Account and enable it under sink.kinesis.cloudAccount.
Pub/Sub: Create a GCP Cloud Account and enable it under sink.pubsub.cloudAccount.

To install, 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

Quick Start Examples

PostgreSQL → Kafka:

source:
  type: postgres
  database:
    hostname: my-postgres.my-gvc.cpln.local
    port: 5432
    name: mydb
    user: debezium
    password: secret
  serverName: myserver
  tableIncludeList: "public.users,public.orders"
  postgres:
    slotName: debezium_slot
    publicationName: dbz_publication

sink:
  type: kafka
  kafka:
    bootstrapServers: kafka.my-gvc.cpln.local:9092
    topic: cdc-events

MySQL → Redis Streams:

source:
  type: mysql
  database:
    hostname: mysql.my-gvc.cpln.local
    port: 3306
    name: mydb
    user: debezium
    password: secret
  serverName: myserver
  mysql:
    serverId: 85744
    includeSchemaChanges: true

sink:
  type: redis
  redis:
    address: redis.my-gvc.cpln.local:6379
    streamName: cdc-stream

PostgreSQL → AWS Kinesis (Universal Cloud Identity):

source:
  type: postgres
  database:
    hostname: my-rds.us-east-1.rds.amazonaws.com
    port: 5432
    name: mydb
    user: debezium
    password: secret
  serverName: myserver

sink:
  type: kinesis
  kinesis:
    region: us-east-1
    streamName: cdc-events
    credentialsProvider: default
    cloudAccount:
      enabled: true
      name: my-aws-account

Full `values.yaml`

image: quay.io/debezium/server:3.0

resources:
  cpu: 500m
  memory: 512Mi

source:
  type: postgres  # options: postgres, mysql, mongodb, sqlserver, oracle

  database:
    hostname: ""
    port: 5432
    name: ""
    user: ""
    password: ""

  serverName: "dbserver1"
  tableIncludeList: ""
  tableExcludeList: ""

  postgres:
    slotName: "debezium"
    publicationName: "dbz_publication"
    pluginName: "pgoutput"        # options: pgoutput, decoderbufs
    slotDropOnStop: false
    heartbeatIntervalMs: 0        # set to 5000 for HA/patroni setups
    heartbeatActionQuery: ""

  mysql:
    serverId: 85744
    includeSchemaChanges: true

  mongodb:
    connectionString: ""
    replicaSet: ""

  sqlserver:
    databaseNames: ""
    snapshotMode: "initial"       # options: initial, schema_only, initial_only

  oracle:
    pdbName: ""
    logMiningStrategy: "online_catalog"

  offset:
    storage: file  # options: file, redis, jdbc
    flushIntervalMs: 10000
    flushTimeoutMs: 60000

    file:
      filename: "/debezium/data/offsets.dat"

    redis:
      address: ""
      key: "debezium:offsets"
      password: ""
      ssl: false

    jdbc:
      url: ""
      user: ""
      password: ""
      tableName: "debezium_offsets"

  schemaHistory:              # MySQL and SQL Server only
    storage: file             # options: file, redis, jdbc
    file:
      filename: "/debezium/data/schema-history.dat"
    redis:
      address: ""
      key: "debezium:schema-history"
      password: ""
      ssl: false
    jdbc:
      url: ""
      user: ""
      password: ""
      tableName: "debezium_schema_history"

  errors:
    retryDelayInitialMs: 300
    retryDelayMaxMs: 10000
    maxRetries: -1              # -1 = infinite retries

sink:
  type: kafka  # options: kafka, redis, nats-jetstream, http, kinesis, pubsub, pulsar, eventhubs

  kafka:
    bootstrapServers: ""
    topic: ""
    securityProtocol: "PLAINTEXT"
    saslMechanism: ""
    saslUsername: ""
    saslPassword: ""

  redis:
    address: ""
    password: ""
    ssl: false
    streamName: ""

  nats:
    url: ""
    subject: ""
    username: ""
    password: ""

  http:
    url: ""
    headers: {}
    authType: ""              # options: none, basic, bearer
    username: ""
    password: ""
    bearerToken: ""

  kinesis:
    region: ""
    streamName: ""
    credentialsProvider: "default"
    cloudAccount:
      enabled: false
      name: ""

  pubsub:
    projectId: ""
    topic: ""
    cloudAccount:
      enabled: false
      name: ""

  pulsar:
    serviceUrl: ""
    topic: ""
    authPluginClassName: ""
    authToken: ""

  eventhubs:
    connectionString: ""
    hubName: ""

format:
  key: json    # options: json, avro, protobuf
  value: json
  schemaRegistry:
    url: ""
    username: ""
    password: ""

volumeset:
  capacity: 10                         # GiB — only used with file offset storage
  performanceClass: general-purpose-ssd

firewall:
  internal:
    inboundAllowType: same-gvc         # options: none, same-gvc, same-org, workload-list
    workloads: []
  external:
    outboundAllowCIDR:
      - 0.0.0.0/0

Supported Sources

Database	Default Port	Key Settings
PostgreSQL	`5432`	`slotName`, `publicationName`, `pluginName`
MySQL	`3306`	`serverId`, `includeSchemaChanges`
MongoDB	`27017`	`connectionString`, `replicaSet`
SQL Server	`1433`	`databaseNames`, `snapshotMode`
Oracle	`1521`	`pdbName`, `logMiningStrategy`

Supported Sinks

Sink	Key Settings	Notes
Kafka	`bootstrapServers`, `topic`	No Kafka Connect required
Redis	`address`, `streamName`	Redis Streams
NATS JetStream	`url`, `subject`	Cloud-native messaging
HTTP	`url`	Webhooks and custom endpoints
AWS Kinesis	`region`, `streamName`	Uses Universal Cloud Identity
GCP Pub/Sub	`projectId`, `topic`	Uses Universal Cloud Identity
Apache Pulsar	`serviceUrl`, `topic`	Optional token auth
Azure Event Hubs	`connectionString`, `hubName`	Kafka-compatible protocol

Offset Storage

Debezium tracks its position in the source database’s replication stream using offset storage. If the process restarts, it resumes from the last committed offset.

Backend	Persistence	Notes
`file`	Volume Set mounted at `/debezium/data`	Default. Simple, requires a Volume Set.
`redis`	Redis key	No Volume Set needed. Use with an existing Redis instance.
`jdbc`	Relational table	No Volume Set needed. Use with an existing PostgreSQL/MySQL instance.

Schema History (MySQL and SQL Server only)

MySQL and SQL Server connectors track DDL changes in a schema history store. Configure source.schemaHistory.storage with the same backend options as offset storage (file, redis, or jdbc).

Serialization Formats

Events can be serialized as JSON, Avro, or Protobuf. For Avro or Protobuf, configure a Schema Registry:

format:
  key: avro
  value: avro
  schemaRegistry:
    url: http://schema-registry.my-gvc.cpln.local:8081
    username: ""
    password: ""

Universal Cloud Identity

AWS Kinesis and GCP Pub/Sub sinks support credential-free access via Control Plane’s Universal Cloud Identity — no access keys or service account JSON files are needed. Enable by setting cloudAccount.enabled: true and providing the Cloud Account name registered in Control Plane:

sink:
  type: kinesis
  kinesis:
    region: us-east-1
    streamName: my-stream
    credentialsProvider: default
    cloudAccount:
      enabled: true
      name: my-aws-account

Health Checks

Debezium Server exposes Quarkus health endpoints:

Endpoint	Purpose
`/q/health/ready`	Connector is ready and connected to source
`/q/health/live`	Server process is alive

Troubleshooting

Connector not starting

Verify database hostname and port are reachable from the GVC (check firewall.external.outboundAllowCIDR).
Confirm the database user has the required replication permissions.
View startup logs: cpln workload logs {release-name}-debezium --gvc {gvc}

Offset storage errors

File storage: confirm the Volume Set is mounted and has sufficient capacity.
Redis/JDBC: verify connectivity, credentials, and that the backend is accessible within the GVC.

Sink delivery failures

Verify the sink endpoint is reachable from the workload.
For Kinesis/Pub/Sub: confirm the Cloud Account is configured and has the correct IAM/IAM permissions.
For Kafka with SASL: verify saslUsername, saslPassword, and saslMechanism match the broker config.

External References

Debezium Server Documentation

Full Debezium Server configuration reference

Debezium Connectors

Source connector configuration for each supported database

CDC Pipeline Template

Deploy a complete CDC pipeline (PostgreSQL HA + Kafka + Debezium) in one step

Create a Cloud Account

Set up AWS or GCP cloud accounts for Kinesis and Pub/Sub sinks

​Overview

​Architecture

​What Gets Created

​Prerequisites

​Source Database

​Cloud Sinks (Kinesis / Pub/Sub)

UI

CLI

Terraform

Pulumi

​Configuration

​Quick Start Examples

​Full values.yaml

​Supported Sources

​Supported Sinks

​Offset Storage

​Schema History (MySQL and SQL Server only)

​Serialization Formats

​Universal Cloud Identity

​Health Checks

​Troubleshooting

​External References

Debezium Server Documentation

Debezium Connectors

CDC Pipeline Template

Create a Cloud Account

Overview

Architecture

What Gets Created

Prerequisites

Source Database

Cloud Sinks (Kinesis / Pub/Sub)

Configuration

Quick Start Examples

Full `values.yaml`

Supported Sources

Supported Sinks

Offset Storage

Schema History (MySQL and SQL Server only)

Serialization Formats

Universal Cloud Identity

Health Checks

Troubleshooting

External References