Integrações — Kafka

Visão geral das integrações

O chart tdp-kafka suporta integração com bancos de dados relacionais por meio de conectores Debezium, executados sobre Kafka Connect.

O que é Kafka Connect e Debezium?

Kafka Connect é um framework do ecossistema Kafka para mover dados entre Kafka e sistemas externos de forma escalável e tolerante a falhas, sem escrever código. Cada integração é declarada como um conector.

Debezium é um conjunto de conectores Kafka Connect especializado em Change Data Capture (CDC): ao invés de consultar periodicamente o banco, o Debezium lê o log de transações do base de dados (WAL no PostgreSQL, binlog no MySQL, etc.) e publica cada inserção, atualização ou exclusão como um evento Kafka — em tempo quase real e com baixo impacto sobre o banco de origem.

base de dados  →  log de transações  →  Debezium  →  Tópico Kafka  →  consumidores

Por que usar CDC?

O CDC é superior a consultas periódicas (polling) porque: captura todas as mudanças (inclusive exclusões), opera em tempo real, não sobrecarrega o banco com queries de varredura e preserva a ordem das alterações.

Bancos suportados

Banco	Chave no chart
PostgreSQL	kafkaConnects.postgres
MySQL	kafkaConnects.mysql
SQL Server	kafkaConnects.sqlserver
Oracle	kafkaConnects.oracle

Estrutura de configuração

Cada integração segue a mesma hierarquia:

kafkaConnects:
  <tipo>:
    enabled: true          # habilita o KafkaConnect cluster
    connect:               # configurações do cluster Kafka Connect
      name: ...
      replicas: ...
      bootstrapServers: ...
      kafkaVersion: ...
    connectors:            # um ou mais conectores neste cluster
      <nome-lógico>:
        enabled: true
        name: ...          # nome do recurso KafkaConnector
        topicPrefix: ...   # prefixo dos tópicos gerados
        <tipo>:            # parâmetros específicos do banco
          ...

Gerenciamento de credenciais

O chart oferece duas opções para credenciais do banco:

Opção	Parâmetro	Quando usar
Criar Secret automaticamente	createSecret: true + credenciais nos values	Ambientes sem gestão externa de Secrets
Usar Secret existente	createSecret: false + secretName: <nome>	Ambientes com Vault, Sealed Secrets ou gestão própria

Credenciais nos values

Ao usar createSecret: true, as credenciais ficam nos values aplicados ao release. Não versione password em repositórios Git públicos ou compartilhados; use arquivos de values privados ou --set pontual em pipelines de CI/CD.

PostgreSQL

Pré-requisito no banco

O Debezium utiliza a replicação lógica do PostgreSQL. Antes de habilitar o conector:

1. Configure wal_level = logical no PostgreSQL
2. Crie um usuário com permissão de replicação e acesso às tabelas monitoradas
3. Habilite a publicação lógica (CREATE PUBLICATION) ou deixe o Debezium criá-la automaticamente

kafkaConnects:
  postgres:
    enabled: true
    connect:
      name: connect-debezium-postgres
      replicas: 1
      bootstrapServers: <kafka-cluster-name>-kafka-bootstrap:9092
      kafkaVersion: "4.1.0"
    connectors:
      appdb:
        enabled: true
        name: debezium-postgres-appdb
        topicPrefix: "pgapp"
        postgres:
          createSecret: true
          host: "<postgresql-host>.<namespace>.svc.cluster.local"
          port: "5432"
          dbname: "appdb"
          user: "debezium"
          password: "<database-password>"

Os tópicos gerados seguirão o padrão: <topicPrefix>.<schema>.<tabela>. Por exemplo, com topicPrefix: pgapp, a tabela public.orders gerará o tópico pgapp.public.orders.

MySQL

Pré-requisito no banco

O Debezium lê o binlog do MySQL. Certifique-se de que:

1. log_bin está habilitado no MySQL
2. binlog_format = ROW
3. O usuário de CDC possui permissões: SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT

kafkaConnects:
  mysql:
    enabled: true
    connect:
      name: connect-debezium-mysql
      replicas: 1
      bootstrapServers: <kafka-cluster-name>-kafka-bootstrap:9092
      kafkaVersion: "4.1.0"
    connectors:
      appdb:
        enabled: true
        name: debezium-mysql-appdb
        topicPrefix: "mysqlapp"
        mysql:
          createSecret: true
          host: "<mysql-host>.<namespace>.svc.cluster.local"
          port: "3306"
          user: "debezium"
          password: "<database-password>"
          databaseIncludeList: "appdb"

O campo databaseIncludeList restringe a captura aos bancos listados (separados por vírgula).

SQL Server

Pré-requisito no banco

O Debezium usa o CDC nativo do SQL Server. Para cada banco/tabela a monitorar:

1. Habilite o CDC no banco: EXEC sys.sp_cdc_enable_db
2. Habilite o CDC nas tabelas: EXEC sys.sp_cdc_enable_table
3. O usuário de CDC deve ter permissão de leitura nas tabelas de CDC (cdc.*)

kafkaConnects:
  sqlserver:
    enabled: true
    connect:
      name: connect-debezium-sqlserver
      replicas: 1
      bootstrapServers: <kafka-cluster-name>-kafka-bootstrap:9092
      kafkaVersion: "4.1.0"
    connectors:
      appdb:
        enabled: true
        name: debezium-sqlserver-appdb
        topicPrefix: "mssqlapp"
        sqlserver:
          createSecret: true
          host: "<sqlserver-host>.<namespace>.svc.cluster.local"
          port: "1433"
          user: "debezium"
          password: "<database-password>"
          databaseNames: "AppDb"

O campo databaseNames lista os bancos SQL Server a monitorar (separados por vírgula).

Oracle

Pré-requisito no banco

O Debezium usa o LogMiner do Oracle para ler o redo log. É necessário:

1. Banco em modo ARCHIVELOG
2. LogMiner habilitado e configurado
3. Usuário com permissões: LOGMINING, SELECT_CATALOG_ROLE, acesso às tabelas monitoradas e às views do LogMiner

kafkaConnects:
  oracle:
    enabled: true
    connect:
      name: connect-debezium-oracle
      replicas: 1
      bootstrapServers: <kafka-cluster-name>-kafka-bootstrap:9092
      kafkaVersion: "4.1.0"
    connectors:
      appdb:
        enabled: true
        name: debezium-oracle-appdb
        topicPrefix: "oraapp"
        oracle:
          createSecret: true
          host: "<oracle-host>.<namespace>.svc.cluster.local"
          port: "1521"
          user: "debezium"
          password: "<database-password>"
          dbname: "ORCLCDB"
          pdbName: "ORCLPDB1"

Campo	Descrição
dbname	Nome do Container Database (CDB)
pdbName	Nome do Pluggable Database (PDB) onde estão as tabelas monitoradas

Oracle e driver JDBC

O driver JDBC Oracle não é distribuído com o Debezium por restrições de licença. Verifique a documentação da imagem do chart para confirmar como o driver é disponibilizado na sua versão do tdp-kafka.

Deploy

Terminal input

helm upgrade --install <release> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-kafka \
  -n <namespace> \
  -f values.yaml \
  -f values-connectors.yaml

Verificação

Terminal input

# Listar todos os conectores no namespace
kubectl -n <namespace> get kafkaconnectors

# Inspecionar status de um conector específico
kubectl -n <namespace> describe kafkaconnector <connector-name>

# Ver logs do pod Kafka Connect
kubectl -n <namespace> logs -l strimzi.io/cluster=connect-debezium-postgres

O campo status.connectorStatus.connector.state deve mostrar RUNNING para um conector saudável.

Autorização de tópicos com Ranger

A integração com Apache Ranger para políticas de autorização em tópicos Kafka não faz parte do escopo configurável por este chart; trate como configuração avançada do ambiente, realizada diretamente no plugin Ranger para Kafka.