All Products
Search
Document Center

Realtime Compute for Apache Flink:Kafka connector

Last Updated:Sep 24, 2026

Gunakan Kafka SQL connector sebagai tabel sumber atau tabel sink dalam Realtime Compute for Apache Flink.

Ikhtisar

Apache Kafka adalah platform streaming event terdistribusi open-source yang banyak digunakan untuk pemrosesan data berkinerja tinggi, analitik streaming, dan integrasi data. Kafka connector untuk Realtime Compute for Apache Flink menggunakan klien Apache Kafka open-source untuk menyediakan throughput data berkinerja tinggi, mendukung pembacaan dan penulisan berbagai format data, serta menawarkan semantik tepat-sekali (exactly-once semantics).

Kategori

Deskripsi

Jenis yang didukung

Sumber SQL, sink

Sumber Flink CDC, sink

Sumber DataStream, sink

Mode eksekusi

Streaming

Format data

Format data yang didukung

  • CSV

  • JSON

  • Apache Avro

  • Confluent Avro

  • Debezium JSON

  • Canal JSON

  • Maxwell JSON

  • Raw

  • Protobuf

Catatan
  • Format Data Protobuf bawaan hanya didukung untuk Ververica Runtime (VVR) 8.0.9 dan versi setelahnya.

  • Setiap format data yang didukung memiliki parameter terkait yang dapat ditentukan dalam klausa WITH. Untuk informasi selengkapnya, lihat Formats.

Metrik

Metrik

  • Tabel Sumber

    • numRecordsIn

    • numRecordsInPerSecond

    • numBytesIn

    • numBytesInPerSecond

    • currentEmitEventTimeLag

    • currentFetchEventTimeLag

    • sourceIdleTime

    • pendingRecords

  • Tabel Sink

    • numRecordsOut

    • numRecordsOutPerSecond

    • numBytesOut

    • numBytesOutPerSecond

    • currentSendTime

Catatan

Untuk informasi lebih lanjut mengenai metrik tersebut, lihat Metrics.

Jenis API

SQL, DataStream, Flink CDC

Pembaruan/penghapusan sink

Connector ini hanya mendukung penambahan data ke tabel sink. Pembaruan dan penghapusan tidak didukung.

Catatan

Untuk informasi lebih lanjut tentang cara memperbarui atau menghapus data di Tabel Sink, lihat Upsert Kafka.

Prasyarat

Sebelum memulai, pastikan Anda memenuhi prasyarat berikut sesuai jenis kluster Kafka Anda:

  • Menghubungkan ke kluster ApsaraMQ for Kafka

    • Versi kluster Kafka minimal 0.11.

    • Anda telah membuat kluster ApsaraMQ for Kafka. Untuk informasi selengkapnya, lihat Langkah 3: Buat sumber daya.

    • Ruang kerja Flink dan kluster Kafka berada dalam Virtual Private Cloud (VPC) yang sama, dan Anda telah menambahkan Blok CIDR ruang kerja Flink ke daftar putih ApsaraMQ for Kafka. Untuk informasi selengkapnya, lihat Konfigurasi daftar putih.

    Penting

    Batasan saat menulis data ke ApsaraMQ for Kafka:

    • ApsaraMQ for Kafka tidak mendukung format kompresi Zstandard (zstd) untuk operasi tulis.

    • ApsaraMQ for Kafka tidak mendukung tulisan idempoten atau transaksional, sehingga mencegah Anda menggunakan semantik tepat-sekali yang disediakan oleh tabel sink Kafka. Mulai dari Ververica Runtime (VVR) 8.0.0, Kafka connector menggunakan klien Kafka 3.x, di mana properti properties.enable.idempotence secara default bernilai true. Oleh karena itu, untuk mencegah kegagalan tulis saat menggunakan Ververica Runtime (VVR) 8.0.0 atau versi setelahnya untuk menulis ke ApsaraMQ for Kafka, Anda harus menambahkan konfigurasi properties.enable.idempotence=false ke dalam definisi tabel sink Anda. Untuk perbandingan mesin penyimpanan dan batasan fitur ApsaraMQ for Kafka, lihat Perbandingan antar mesin penyimpanan.

  • Menghubungkan ke kluster Apache Kafka yang dikelola sendiri

    • Versi kluster Apache Kafka yang dikelola sendiri minimal 0.11.

    • Ruang kerja Flink memiliki konektivitas jaringan ke kluster Apache Kafka yang dikelola sendiri. Untuk detail cara menghubungkan ke kluster melalui internet publik, lihat FAQ tentang konektivitas jaringan.

    • Hanya opsi konfigurasi klien untuk Apache Kafka versi 2.8 yang didukung. Untuk informasi selengkapnya, lihat dokumentasi Apache Kafka mengenai Consumer Configs dan Producer Configs.

Catatan

Tulisan transaksional tidak direkomendasikan karena adanya keterbatasan desain yang diketahui pada Apache Flink dan Apache Kafka. Saat Anda mengatur sink.delivery-guarantee = 'exactly-once', Kafka connector mengaktifkan tulisan transaksional, dengan isu-isu berikut:

  • Setiap checkpoint menghasilkan ID Transaksi baru. Jika interval checkpoint terlalu singkat, banjir ID Transaksi yang dihasilkan dapat menyebabkan koordinator kluster Kafka kehabisan memori, sehingga mengganggu stabilitas kluster.

  • Setiap transaksi membuat instans Producer baru. Jika terlalu banyak transaksi dikomit secara bersamaan, Pengelola Tugas (TaskManager) dapat kehabisan memori, sehingga mengganggu pekerjaan Apache Flink.

  • Jika beberapa pekerjaan Apache Flink menggunakan sink.transactional-id-prefix yang sama, ID Transaksi yang dihasilkan dapat bentrok. Ketika operasi tulis gagal pada satu pekerjaan, hal ini dapat mencegah Log Start Offset (LSO) partisi Apache Kafka maju. Hal ini memengaruhi semua konsumen partisi tersebut.

Jika Anda memerlukan semantik tepat-sekali, gunakan connector Upsert Kafka untuk menulis ke tabel kunci primer, sehingga memastikan idempotensi. Jika Anda harus menggunakan tulisan transaksional, lihat Catatan penggunaan semantik tepat-sekali.

Pemecahan masalah konektivitas jaringan

Error Timed out waiting for a node assignment saat pekerjaan Realtime Compute for Apache Flink gagal dimulai biasanya menunjukkan adanya masalah konektivitas jaringan antara Realtime Compute for Apache Flink dan kluster Kafka.

Klien Kafka menghubungkan ke broker sebagai berikut:

  1. Klien menggunakan alamat yang ditentukan dalam bootstrap.servers untuk membuat koneksi awal ke kluster Kafka.

  2. Kluster Kafka mengembalikan metadata untuk setiap broker, termasuk titik akhirnya (endpoints).

  3. Klien kemudian menggunakan titik akhir tersebut untuk menghubungkan ke broker guna membaca atau menulis data.

Meskipun alamat bootstrap.servers dapat dijangkau, klien tidak dapat membaca atau menulis data jika Kafka mengembalikan titik akhir broker yang salah. Masalah ini sering terjadi pada arsitektur jaringan yang menggunakan proxy, penerusan port, atau jalur sewa.

Langkah pemecahan masalah

ApsaraMQ for Kafka

  1. Konfirmasi jenis Titik Akhir (Endpoint)

    • Titik Akhir Default (jaringan internal)

    • Titik Akhir SASL (jaringan internal dengan otentikasi)

    • Titik Akhir Publik (memerlukan aplikasi terpisah)

    Gunakan fitur Network Probe di Konsol pengembangan Realtime Compute for Apache Flink untuk mengesampingkan masalah konektivitas dengan alamat bootstrap.servers.

  2. Periksa grup keamanan dan daftar putih

    Tambahkan Blok CIDR ruang kerja Realtime Compute for Apache Flink ke daftar putih instans Kafka Anda. Untuk informasi selengkapnya, lihat Lihat Blok CIDR VPC dan Konfigurasi daftar putih.

  3. Periksa konfigurasi SASL (jika diaktifkan)

    Jika Anda menggunakan titik akhir SASL_SSL, pastikan mekanisme JAAS, SSL, dan SASL dikonfigurasi dengan benar dalam pekerjaan Realtime Compute for Apache Flink Anda. Tanpa otentikasi yang tepat, koneksi dapat gagal pada fase handshake, yang juga dapat muncul sebagai timeout. Untuk informasi selengkapnya, lihat Keamanan dan otentikasi.

Kafka yang dikelola sendiri

  1. Gunakan fitur Network Probe

    Fitur ini membantu Anda mengesampingkan masalah konektivitas dengan alamat bootstrap.servers dan memverifikasi bahwa titik akhir internal atau publik yang benar digunakan.

  2. Periksa grup keamanan dan daftar putih

    • Grup keamanan untuk instans Elastic Compute Service (ECS) harus mengizinkan lalu lintas masuk pada port titik akhir Kafka, biasanya 9092 atau 9093.

    • Pastikan firewall pada instans ECS mengizinkan trafik dari VPC ruang kerja Realtime Compute for Apache Flink Anda. Untuk informasi selengkapnya, lihat Lihat Blok CIDR VPC.

  3. Periksa konfigurasi

    1. Gunakan tool zkCli.sh atau zookeeper-shell.sh untuk login ke kluster ZooKeeper yang digunakan Kafka.

    2. Jalankan perintah untuk mendapatkan metadata broker. Misalnya, jalankan get /brokers/ids/0. Di bidang endpoints respons, temukan alamat yang diiklankan Kafka kepada klien.

      
      # bin/zookeeper-shell.sh localhost:2181
      Connecting to localhost:2181
      Welcome to ZooKeeper!
      JLine support is disabled
      
      WATCHER::
      
      WatchedEvent state:SyncConnected type:None path:null
      get /brokers/ids/0
      {"listener_security_protocol_map":{"PLAINTEXT":"PLAINTEXT"},"endpoints":["PLAINTEXT://116.62.xxx:9092"],"jmx_port":-1,"host":"116.62.xxx","timestamp":"1614840078030","port":9092,"version":4}
      
    3. Gunakan fitur Network Probe di Konsol pengembangan Realtime Compute for Apache Flink untuk menguji apakah alamat ini dapat diakses.

      Catatan
      • Jika alamat tidak dapat diakses, hubungi administrator Kafka Anda untuk memeriksa dan memperbaiki konfigurasi listeners dan advertised.listeners agar alamat yang diiklankan dapat diakses dari Realtime Compute for Apache Flink.

      • Untuk informasi lebih lanjut tentang koneksi klien Kafka, lihat Troubleshoot Connectivity.

  4. Periksa konfigurasi SASL (jika diaktifkan)

    Jika Anda menggunakan titik akhir SASL_SSL, pastikan mekanisme JAAS, SSL, dan SASL dikonfigurasi dengan benar dalam pekerjaan Realtime Compute for Apache Flink Anda. Tanpa otentikasi yang tepat, koneksi dapat gagal pada fase handshake, yang juga dapat muncul sebagai timeout. Untuk informasi selengkapnya, lihat Keamanan dan otentikasi.

SQL

Gunakan Kafka connector sebagai tabel sumber atau tabel sink dalam pekerjaan SQL.

Sintaksis

CREATE TABLE KafkaTable (
  `user_id` BIGINT,
  `item_id` BIGINT,
  `behavior` STRING,
  `ts` TIMESTAMP_LTZ(3) METADATA FROM 'timestamp' VIRTUAL
) WITH (
  'connector' = 'kafka',
  'topic' = 'user_behavior',
  'properties.bootstrap.servers' = 'localhost:9092',
  'properties.group.id' = 'testGroup',
  'scan.startup.mode' = 'earliest-offset',
  'format' = 'csv'
)

Kolom metadata

Definisikan kolom metadata dalam tabel sumber atau sink untuk mengakses metadata pesan Kafka. Misalnya, saat Anda berlangganan ke beberapa topik, kolom metadata dapat mengidentifikasi topik asal setiap catatan.

CREATE TABLE kafka_source (
  -- Baca topik pesan sebagai kolom `record_topic`
  `record_topic` STRING NOT NULL METADATA FROM 'topic' VIRTUAL,
  -- Baca timestamp dari ConsumerRecord sebagai kolom `ts`
  `ts` TIMESTAMP_LTZ(3) METADATA FROM 'timestamp' VIRTUAL,
  -- Baca offset pesan sebagai kolom `record_offset`
  `record_offset` BIGINT NOT NULL METADATA FROM 'offset' VIRTUAL,
  ...
) WITH (
  'connector' = 'kafka',
  ...
);

CREATE TABLE kafka_sink (
  -- Tulis timestamp dari kolom `ts` sebagai timestamp ProducerRecord ke Kafka
  `ts` TIMESTAMP_LTZ(3) METADATA FROM 'timestamp' VIRTUAL,
  ...
) WITH (
  'connector' = 'kafka',
  ...
);

Tabel berikut mencantumkan kolom metadata yang didukung oleh tabel sumber dan sink Kafka.

Kunci

Tipe

Deskripsi

Lingkup

topic

STRING NOT NULL METADATA VIRTUAL

Topik pesan.

Tabel sumber

partition

INT NOT NULL METADATA VIRTUAL

ID partisi pesan.

Tabel sumber

headers

MAP<STRING, BYTES> NOT NULL METADATA VIRTUAL

Header pesan.

Tabel sumber dan tabel sink

leader-epoch

INT NOT NULL METADATA VIRTUAL

Leader-epoch pesan.

Tabel sumber

offset

BIGINT NOT NULL METADATA VIRTUAL

Offset pesan.

Tabel sumber

timestamp

TIMESTAMP(3) WITH LOCAL TIME ZONE NOT NULL METADATA VIRTUAL

Timestamp pesan.

Tabel sumber dan tabel sink

timestamp-type

STRING NOT NULL METADATA VIRTUAL

Jenis timestamp pesan. Nilai yang valid:

  • NoTimestampType: Tidak ada timestamp yang didefinisikan dalam pesan.

  • CreateTime: Waktu pesan dibuat.

  • LogAppendTime: Waktu pesan ditambahkan ke log broker Kafka.

Tabel sumber

__raw_key__

STRING NOT NULL METADATA VIRTUAL

Kunci pesan mentah.

Tabel sumber dan tabel sink

Catatan

Parameter ini hanya didukung di Ververica Runtime (VVR) 11.4 dan versi setelahnya.

__raw_value__

STRING NOT NULL METADATA VIRTUAL

Nilai pesan mentah.

Tabel sumber dan tabel sink

Catatan

Parameter ini hanya didukung di Ververica Runtime (VVR) 11.4 dan versi setelahnya.

Opsi konektor

  • Umum

    Opsi

    Deskripsi

    Tipe

    Wajib

    Default

    Keterangan

    connector

    Jenis connector.

    String

    Ya

    –

    Nilainya harus kafka.

    properties.bootstrap.servers

    Daftar alamat broker Kafka.

    String

    Ya

    –

    Format: host1:port1,host2:port2,.... Pisahkan alamat dengan koma (,).

    properties.*

    Properti tambahan untuk klien Kafka.

    String

    Tidak

    –

    Kunci properti harus merupakan opsi yang valid sebagaimana didefinisikan dalam dokumentasi resmi Apache Kafka untuk Producer Configs dan Consumer Configs.

    Realtime Compute for Apache Flink menghapus prefiks properties. dan meneruskan pasangan kunci-nilai yang tersisa ke klien Kafka yang mendasari. Misalnya, Anda dapat mengatur 'properties.allow.auto.create.topics' = 'false' untuk menonaktifkan pembuatan topik otomatis.

    Kafka connector menimpa opsi-opsi berikut, sehingga Anda tidak dapat mengonfigurasinya dengan cara ini:

    • key.deserializer

    • value.deserializer

    format

    Format untuk serialisasi dan deserialisasi nilai pesan Kafka.

    String

    Tidak

    –

    Format yang didukung:

    • csv

    • json

    • avro

    • debezium-json

    • canal-json

    • maxwell-json

    • avro-confluent

    • raw

    Catatan

    Untuk informasi selengkapnya, lihat Opsi format.

    key.format

    Format untuk serialisasi dan deserialisasi kunci pesan Kafka.

    String

    Tidak

    –

    Format yang didukung:

    • csv

    • json

    • avro

    • debezium-json

    • canal-json

    • maxwell-json

    • avro-confluent

    • raw

    Catatan

    Saat Anda menggunakan konfigurasi ini, key.options wajib diisi.

    key.fields

    Bidang dari skema tabel yang digunakan sebagai kunci pesan Kafka.

    String

    Tidak

    –

    Pisahkan beberapa nama bidang dengan titik koma (;). Contoh: 'field1;field2'.

    key.fields-prefix

    Awalan kustom untuk semua bidang kunci guna mencegah bentrok nama dengan bidang nilai.

    String

    Tidak

    –

    Awalan ini digunakan untuk membedakan antara bidang kunci dan bidang nilai. Awalan ini dihapus sebelum serialisasi kunci atau setelah deserialisasi.

    Catatan

    Jika Anda menggunakan opsi ini, value.fields-include harus diatur ke EXCEPT_KEY.

    value.format

    Format untuk serialisasi dan deserialisasi nilai pesan Kafka.

    String

    Tidak

    –

    Konfigurasi ini setara dengan format. Anda hanya dapat mengatur salah satu dari format atau value.format. Jika keduanya dikonfigurasi, value.format menggantikan format.

    value.fields-include

    Menentukan apakah bidang kunci disertakan dalam format nilai.

    String

    Tidak

    ALL

    Nilai yang valid:

    • ALL: Nilai pesan Kafka mencakup semua kolom tabel.

    • EXCEPT_KEY: Nilai pesan Kafka mencakup semua kolom tabel kecuali yang didefinisikan dalam key.fields.

  • Tabel sumber

    Opsi

    Deskripsi

    Tipe

    Wajib

    Default

    Keterangan

    topic

    Topik atau topik-topik yang akan dibaca.

    String

    Tidak

    –

    Untuk berlangganan ke beberapa topik, pisahkan nama-namanya dengan titik koma (;), contohnya 'topic-1;topic-2'.

    Catatan

    Anda hanya dapat menentukan salah satu dari opsi ini atau topic-pattern, tidak keduanya.

    topic-pattern

    Ekspresi reguler yang cocok dengan topik yang akan dilanggan. Konsumen berlangganan ke semua topik yang namanya sesuai dengan pola ini.

    String

    Tidak

    –

    Contoh:

    • user_event_.*: Cocok dengan semua topik yang diawali dengan user_event_.

    • prod\.logs\..*: Cocok dengan topik yang diawali dengan prod.logs. (karakter . harus di-escape).

    Catatan

    Anda hanya dapat menentukan salah satu dari opsi ini atau topic, tidak keduanya.

    properties.group.id

    ID kelompok konsumen sumber Kafka.

    String

    Tidak

    KafkaSource-{Nama-Tabel-Sumber}

    Jika Anda menggunakan ID kelompok konsumen untuk pertama kalinya, Anda juga harus mengatur properties.auto.offset.reset ke earliest atau latest untuk menentukan offset startup awal.

    scan.startup.mode

    Offset startup konsumen Kafka.

    String

    Tidak

    group-offsets

    Nilai yang valid:

    • earliest-offset: Mulai membaca dari offset paling awal yang tersedia.

    • latest-offset: Mulai membaca dari offset terbaru.

    • group-offsets: Mulai membaca dari offset yang telah dikomit oleh properties.group.id yang ditentukan.

    • timestamp: Mulai membaca dari scan.startup.timestamp-millis yang ditentukan.

    • specific-offsets: Mulai membaca dari offset yang ditentukan dalam scan.startup.specific-offsets.

    Catatan

    Opsi ini hanya berlaku saat pekerjaan dimulai tanpa status. Jika pekerjaan dilanjutkan dari checkpoint, pekerjaan membaca dari offset yang disimpan dalam status checkpoint.

    scan.startup.specific-offsets

    Offset awal per-partisi saat scan.startup.mode bernilai specific-offsets.

    String

    Tidak

    –

    Contoh: partition:0,offset:42;partition:1,offset:300

    scan.startup.timestamp-millis

    Timestamp awal dalam milidetik saat scan.startup.mode diatur ke timestamp.

    Long

    Tidak

    –

    Unitnya adalah milidetik.

    scan.topic-partition-discovery.interval

    Interval penemuan partisi.

    Durasi

    Tidak

    5 menit

    Connector secara berkala menemukan dan membaca dari partisi baru. Saat Anda menggunakan topic-pattern, connector juga menemukan topik baru yang sesuai dengan pola tersebut. Atur interval ke nilai non-positif untuk menonaktifkan fitur ini.

    Catatan

    Di Ververica Runtime (VVR) 6.0.x, penemuan partisi dinamis dinonaktifkan secara default. Mulai dari VVR 8.0, fitur ini diaktifkan secara default dengan interval penemuan 5 menit.

    scan.header-filter

    Memfilter pesan berdasarkan header pesan Kafka.

    String

    Tidak

    –

    Kunci header dan nilainya dipisahkan dengan tanda titik dua (:). Beberapa kondisi header dihubungkan dengan operator logika (& dan |). Operator logika NOT (!) juga didukung. Contoh: depart:toy|depart:book&!env:test menyimpan data Kafka jika header berisi depart=toy atau depart=book dan tidak berisi env=test.

    Catatan
    • Opsi ini hanya didukung di Ververica Runtime (VVR) 8.0.6 dan versi setelahnya.

    • Tanda kurung dalam ekspresi tidak didukung.

    • Operasi logika dievaluasi dari kiri ke kanan.

    • Nilai header dikonversi ke string UTF-8 untuk perbandingan.

    scan.check.duplicated.group.id

    Memeriksa apakah sudah ada konsumen aktif lain yang menggunakan properties.group.id.

    Boolean

    Tidak

    false

    Nilai yang valid:

    • true: Sebelum memulai pekerjaan, sistem memeriksa duplikasi kelompok konsumen. Jika ditemukan, pekerjaan gagal untuk mencegah konflik.

    • false: Memulai pekerjaan tanpa memeriksa konflik.

    Catatan

    Opsi ini hanya didukung di Ververica Runtime (VVR) 6.0.4 dan versi setelahnya.

  • Tabel sink

    Opsi

    Deskripsi

    Type

    Wajib

    Default

    Keterangan

    topic

    Topik target.

    String

    Ya

    –

    –

    sink.partitioner

    Memetakan catatan dari instans sink paralel ke partisi Kafka.

    String

    Tidak

    default

    Nilai yang valid:

    • default: Menggunakan partitioner Kafka default.

    • fixed: Setiap instans sink paralel menulis ke partisi Kafka tetap.

    • round-robin: Catatan didistribusikan ke partisi secara bergiliran (round-robin).

    • Partitioner kustom: Untuk menggunakan partitioner kustom, berikan nama kelas lengkap dari subclass FlinkKafkaPartitioner, misalnya org.mycompany.MyPartitioner.

    sink.delivery-guarantee

    Jaminan pengiriman sink.

    String

    Tidak

    at-least-once

    Nilai yang valid:

    • none: Tidak memberikan jaminan apa pun. Catatan mungkin hilang atau diduplikasi.

    • at-least-once: Menjamin tidak ada catatan yang hilang, tetapi mungkin diduplikasi.

    • exactly-once: Menggunakan transaksi Kafka untuk memberikan semantik tepat-sekali, memastikan catatan tidak hilang maupun diduplikasi.

    Catatan

    Saat menggunakan semantik exactly-once, Anda juga harus menentukan sink.transactional-id-prefix.

    sink.transactional-id-prefix

    Awalan ID transaksi. Diperlukan saat sink.delivery-guarantee bernilai exactly-once.

    String

    Ya, jika sink.delivery-guarantee bernilai exactly-once

    –

    Hanya diperlukan saat sink.delivery-guarantee diatur ke exactly-once.

    sink.parallelism

    Paralelisme operator sink.

    Integer

    Tidak

    –

    Secara default, framework menentukan paralelisme berdasarkan operator hulu.

Keamanan dan otentikasi

Jika kluster Kafka memerlukan koneksi aman atau otentikasi, tambahkan prefiks konfigurasi keamanan dan otentikasi terkait dengan properties. dan atur dalam parameter WITH. Contoh berikut mengonfigurasi tabel Kafka untuk menggunakan PLAIN sebagai mekanisme SASL dengan konfigurasi JAAS.

CREATE TABLE KafkaTable (
  `user_id` BIGINT,
  `item_id` BIGINT,
  `behavior` STRING,
  `ts` TIMESTAMP_LTZ(3) METADATA FROM 'timestamp'
) WITH (
  'connector' = 'kafka',
  ...
  'properties.security.protocol' = 'SASL_PLAINTEXT',
  'properties.sasl.mechanism' = 'PLAIN',
  'properties.sasl.jaas.config' = 'org.apache.flink.kafka.shaded.org.apache.kafka.common.security.plain.PlainLoginModule required username="username" password="password";'
)

Contoh berikut menunjukkan cara menggunakan SASL_SSL sebagai protokol keamanan dan SCRAM-SHA-256 sebagai mekanisme SASL.

CREATE TABLE KafkaTable (
  `user_id` BIGINT,
  `item_id` BIGINT,
  `behavior` STRING,
  `ts` TIMESTAMP_LTZ(3) METADATA FROM 'timestamp'
) WITH (
  'connector' = 'kafka',
  ...
  'properties.security.protocol' = 'SASL_SSL',
  /* Konfigurasi SSL */
  /* Path ke truststore untuk sertifikat CA server. */
  /* File yang diunggah menggunakan Artifacts disimpan di direktori /flink/usrlib/. */
  'properties.ssl.truststore.location' = '/flink/usrlib/kafka.client.truststore.jks',
  'properties.ssl.truststore.password' = 'test1234',
  /* Jika otentikasi klien diperlukan, Anda juga harus mengonfigurasi path ke keystore (kunci privat). */
  'properties.ssl.keystore.location' = '/flink/usrlib/kafka.client.keystore.jks',
  'properties.ssl.keystore.password' = 'test1234',
  /* Algoritma yang digunakan untuk memverifikasi hostname server. String kosong menonaktifkan verifikasi hostname. */
  'properties.ssl.endpoint.identification.algorithm' = '',
  /* Konfigurasi SASL */
  /* Atur mekanisme SASL ke SCRAM-SHA-256. */
  'properties.sasl.mechanism' = 'SCRAM-SHA-256',
  /* Konfigurasi JAAS. */
  'properties.sasl.jaas.config' = 'org.apache.flink.kafka.shaded.org.apache.kafka.common.security.scram.ScramLoginModule required username="username" password="password";'
)

Anda dapat menggunakan fitur Artifacts di Konsol Realtime Compute for Apache Flink untuk mengunggah sertifikat CA dan kunci privat yang disebutkan dalam contoh. File yang diunggah disimpan di direktori /flink/usrlib. Untuk menggunakan file sertifikat CA bernama my-truststore.jks, Anda dapat mengatur properti 'properties.ssl.truststore.location' dalam klausa WITH dengan salah satu dari dua cara berikut:

  • Atur 'properties.ssl.truststore.location' = '/flink/usrlib/my-truststore.jks'. Metode ini menghindari pengunduhan file secara dinamis dari Object Storage Service (OSS) saat runtime, tetapi tidak mendukung Mode Debug.

  • Jika versi engine Realtime Compute adalah VVR 11.5 atau versi setelahnya, Anda dapat mengonfigurasi properties.ssl.truststore.location dan properties.ssl.keystore.location ke path OSS absolut. Format path file adalah oss://flink-fullymanaged-<ID Ruang Kerja>/artifacts/namespaces/<Nama Namespace>/<nama file>. Metode ini mengunduh file OSS secara dinamis selama runtime Flink dan mendukung Mode Debug.

Catatan
  • Verifikasi konfigurasi Anda: Contoh dalam topik ini menunjukkan konfigurasi umum. Sebelum mengonfigurasi Kafka connector, hubungi tim O&M Kafka Anda untuk mendapatkan pengaturan keamanan dan otentikasi yang benar.

  • Escape karakter: Berbeda dengan Apache Flink native, editor SQL Realtime Compute for Apache Flink secara default melakukan escape tanda kutip ganda (") . Oleh karena itu, Anda tidak perlu menambahkan backslash (\) untuk melakukan escape tanda kutip ganda yang digunakan untuk username dan password dalam opsi properties.sasl.jaas.config.

  • Kredensial host di KMS: Anda dapat mengatur username dan password dalam properties.sasl.jaas.config menjadi secret://kms.<nama-rahasia>.<kunci> untuk mereferensikan kredensial yang dikelola KMS alih-alih menggunakan teks biasa. Fitur ini didukung di engine Realtime Compute VVR 11.9 dan versi setelahnya. Untuk prosedur konfigurasi, lihat Integrasi manajemen kredensial KMS.

Offset awal tabel sumber

Mode startup

Anda dapat mengonfigurasi opsi scan.startup.mode untuk menentukan offset tempat tabel sumber Kafka mulai membaca data. Nilai yang valid meliputi:

  • earliest-offset: Mulai membaca dari offset paling awal.

  • latest-offset: Mulai membaca dari offset terbaru.

  • group-offsets: Mulai membaca dari offset yang telah dikomit untuk kelompok konsumen yang ditentukan dalam properties.group.id.

  • timestamp: Mulai membaca dari pesan pertama dengan timestamp lebih besar dari atau sama dengan nilai yang ditentukan dalam scan.startup.timestamp-millis.

  • specific-offsets: Mulai membaca dari offset partisi spesifik yang ditentukan dalam scan.startup.specific-offsets.

Catatan
  • Jika Anda tidak menentukan mode startup, default-nya adalah 'group-offsets'.

  • Opsi scan.startup.mode hanya berlaku untuk pekerjaan tanpa status. Saat pekerjaan stateful dimulai, pekerjaan selalu mengonsumsi dari offset yang disimpan dalam statusnya.

Contoh:

CREATE TEMPORARY TABLE kafka_source (
  ...
) WITH (
  'connector' = 'kafka',
  ...
  -- Konsumsi dari offset paling awal.
  'scan.startup.mode' = 'earliest-offset',
  -- Konsumsi dari offset terbaru.
  'scan.startup.mode' = 'latest-offset',
  -- Konsumsi dari offset yang telah dikomit oleh kelompok konsumen "my-group".
  'properties.group.id' = 'my-group',
  'scan.startup.mode' = 'group-offsets',
  'properties.auto.offset.reset' = 'earliest', -- Jika "my-group" digunakan pertama kali, konsumsi dimulai dari offset paling awal.
  'properties.auto.offset.reset' = 'latest', -- Jika "my-group" digunakan pertama kali, konsumsi dimulai dari offset terbaru.
  -- Konsumsi dari timestamp tertentu dalam milidetik: 1655395200000.
  'scan.startup.mode' = 'timestamp',
  'scan.startup.timestamp-millis' = '1655395200000',
  -- Konsumsi dari offset spesifik.
  'scan.startup.mode' = 'specific-offsets',
  'scan.startup.specific-offsets' = 'partition:0,offset:42;partition:1,offset:300'
);

Prioritas offset awal

Offset awal tabel sumber ditentukan oleh aturan berikut, berdasarkan prioritas:

Prioritas (tertinggi ke terendah)

Offset yang disimpan dalam checkpoint atau titik simpan (savepoint).

Waktu mulai yang dipilih di Konsol Realtime Compute for Apache Flink saat startup pekerjaan.

Offset awal yang ditentukan oleh scan.startup.mode dalam klausa WITH.

Jika scan.startup.mode tidak ditentukan, group-offsets digunakan untuk memulai konsumsi dari offset kelompok konsumen yang sesuai.

Jika offset yang ditentukan oleh langkah-langkah tersebut tidak valid, misalnya karena telah kedaluwarsa atau terjadi masalah di kluster Kafka, sistem mereset offset sesuai kebijakan yang ditentukan dalam properties.auto.offset.reset. Jika opsi ini tidak dikonfigurasi, sistem melemparkan pengecualian yang memerlukan intervensi pengguna.

Skenario umum melibatkan memulai konsumsi dengan ID kelompok konsumen baru. Tabel sumber pertama-tama menanyakan offset yang telah dikomit oleh kelompok tersebut ke kluster Kafka. Karena ID kelompok tersebut baru, tidak ditemukan offset yang valid. Akibatnya, sistem mereset offset sesuai kebijakan yang ditentukan dalam properties.auto.offset.reset. Oleh karena itu, saat mengonsumsi dengan ID kelompok baru, Anda harus mengonfigurasi opsi properties.auto.offset.reset.

Mengommit offset sumber

Tabel sumber Kafka hanya mengommit offset konsumennya ke kluster Kafka setelah checkpoint berhasil, sehingga interval checkpoint yang panjang menyebabkan keterlambatan offset yang dikomit. Tabel sumber menyimpan progres bacaan aktual dalam status checkpoint, yang digunakan sistem untuk pemulihan kesalahan. Offset yang dikomit hanya berfungsi sebagai monitor progres dan tidak digunakan untuk pemulihan, sehingga kegagalan komit tidak memengaruhi akurasi data.

Partitioner sink kustom

Jika strategi partisi bawaan Kafka tidak memenuhi kebutuhan Anda, Anda dapat mengimplementasikan partitioner kustom dengan memperluas kelas FlinkKafkaPartitioner. Setelah pengembangan selesai, kompilasi kode Anda menjadi paket JAR dan unggah menggunakan fitur Artifacts di Konsol Realtime Compute. Setelah paket JAR diunggah dan direferensikan, atur parameter sink.partitioner dalam klausa WITH ke nama kelas lengkap partitioner Anda, misalnya org.mycompany.MyPartitioner.

Kafka, Upsert Kafka, dan katalog Kafka JSON

Kafka adalah platform streaming event yang hanya menambah (append-only) dan tidak mendukung pembaruan atau penghapusan data. Dalam SQL streaming, tabel sink Kafka standar tidak dapat menangani data Change Data Capture (CDC) hulu atau logika penarikan kembali (retraction) dari operator seperti agregat dan join. Jika Anda perlu menulis data yang berisi perubahan atau penarikan kembali, gunakan tabel sink Upsert Kafka.

Untuk menyederhanakan sinkronisasi batch data Change Data Capture (CDC) dari satu atau beberapa tabel database hulu ke Kafka, Anda dapat menggunakan katalog Kafka JSON. Jika data yang disimpan di Kafka dalam format JSON, katalog Kafka JSON memungkinkan Anda melewati langkah mendefinisikan skema dan parameter WITH. Untuk detailnya, lihat Kelola katalog Kafka JSON.

Contoh

Contoh 1: Baca dari dan tulis ke Kafka

Contoh ini membaca data dari topik Kafka sumber dan menulisnya ke topik sink. Datanya dalam format CSV.

CREATE TEMPORARY TABLE kafka_source (
  id INT,
  name STRING,
  age INT
) WITH (
  'connector' = 'kafka',
  'topic' = 'source',
  'properties.bootstrap.servers' = '<yourKafkaBrokers>',
  'properties.group.id' = '<yourKafkaConsumerGroupId>',
  'format' = 'csv'
);

CREATE TEMPORARY TABLE kafka_sink (
  id INT,
  name STRING,
  age INT
) WITH (
  'connector' = 'kafka',
  'topic' = 'sink',
  'properties.bootstrap.servers' = '<yourKafkaBrokers>',
  'properties.group.id' = '<yourKafkaConsumerGroupId>',
  'format' = 'csv'
);

INSERT INTO kafka_sink SELECT id, name, age FROM kafka_source;

Contoh 2: Sinkronisasi skema tabel dan data

Anda dapat menggunakan Kafka connector untuk menyinkronkan pesan dari topik Kafka ke Hologres secara real time. Untuk mencegah pesan duplikat di Hologres selama failover, Anda dapat menggunakan offset dan ID partisi pesan Kafka sebagai kunci primer komposit.

CREATE TEMPORARY TABLE kafkaTable (
  `offset` INT NOT NULL METADATA,
  `part` BIGINT NOT NULL METADATA FROM 'partition',
  PRIMARY KEY (`part`, `offset`) NOT ENFORCED
) WITH (
  'connector' = 'kafka',
  'properties.bootstrap.servers' = '<yourKafkaBrokers>',
  'topic' = 'kafka_evolution_demo',
  'scan.startup.mode' = 'earliest-offset',
  'format' = 'json',
  'json.infer-schema.flatten-nested-columns.enable' = 'true'
    -- Opsional. Meratakan semua kolom bersarang.
);

CREATE TABLE IF NOT EXISTS hologres.kafka.`sync_kafka`
WITH (
  'connector' = 'hologres'
) AS TABLE vvp.`default`.kafkaTable;

Contoh 3: Sinkronisasi kunci dan nilai Kafka

Jika kunci pesan Kafka berisi informasi relevan, Anda dapat menyinkronkan kunci dan nilainya.

CREATE TEMPORARY TABLE kafkaTable (
  `key_id` INT NOT NULL,
  `val_name` VARCHAR(200)
) WITH (
  'connector' = 'kafka',
  'properties.bootstrap.servers' = '<yourKafkaBrokers>',
  'topic' = 'kafka_evolution_demo',
  'scan.startup.mode' = 'earliest-offset',
  'key.format' = 'json',
  'value.format' = 'json',
  'key.fields' = 'key_id',
  'key.fields-prefix' = 'key_',
  'value.fields-prefix' = 'val_',
  'value.fields-include' = 'EXCEPT_KEY'
);

CREATE TABLE IF NOT EXISTS hologres.kafka.`sync_kafka`(
WITH (
  'connector' = 'hologres'
) AS TABLE vvp.`default`.kafkaTable;
Catatan

Kunci pesan Kafka tidak mendukung Schema Evolution atau penguraian tipe otomatis. Anda harus mendeklarasikan skema secara manual.

Contoh 4: Sinkronisasi data dan lakukan komputasi

Saat menyinkronkan data dari Kafka ke Hologres, Anda mungkin memerlukan transformasi ringan.

CREATE TEMPORARY TABLE kafkaTable (
  `distinct_id` INT NOT NULL,
  `properties` STRING,
  `timestamp` TIMESTAMP_LTZ METADATA,
  `date` AS CAST(`timestamp` AS DATE)
) WITH (
  'connector' = 'kafka',
  'properties.bootstrap.servers' = '<yourKafkaBrokers>',
  'topic' = 'kafka_evolution_demo',
  'scan.startup.mode' = 'earliest-offset',
  'key.format' = 'json',
  'value.format' = 'json',
  'key.fields' = 'key_id',
  'key.fields-prefix' = 'key_'
);

CREATE TABLE IF NOT EXISTS hologres.kafka.`sync_kafka` WITH (
   'connector' = 'hologres'
) AS TABLE vvp.`default`.kafkaTable
ADD COLUMN
  `order_id` AS COALESCE(JSON_VALUE(`properties`, '$.order_id'), 'default');
--Gunakan COALESCE untuk menangani nilai null.

Contoh 5: Uraikan JSON bersarang

Berikut adalah contoh pesan JSON:

{
  "id": 101,
  "name": "VVP",
  "properties": {
    "owner": "Alibaba Cloud",
    "engine": "Flink"
  }
}

Untuk menghindari penggunaan fungsi seperti JSON_VALUE(payload, '$.properties.owner') untuk mengurai bidang, Anda dapat langsung mendefinisikan struktur dalam DDL Sumber:

CREATE TEMPORARY TABLE kafka_source (
  id          VARCHAR,
  `name`      VARCHAR,
  properties  ROW<`owner` STRING, engine STRING>
) WITH (
  'connector' = 'kafka',
  'topic' = 'xxx',
  'properties.bootstrap.servers' = 'xxx',
  'scan.startup.mode' = 'earliest-offset',
  'format' = 'json'
);

Dengan pendekatan ini, Flink mengurai JSON menjadi bidang terstruktur selama fase pembacaan. Kueri SQL selanjutnya dapat langsung mereferensikan properties.owner tanpa panggilan fungsi tambahan, yang meningkatkan kinerja secara keseluruhan.

Semantik tepat-sekali

  • Konfigurasi tingkat isolasi konsumen

    Semua aplikasi yang mengonsumsi data Kafka harus mengatur properti isolation.level:

    • read_committed: Hanya membaca data yang telah dikomit.

    • read_uncommitted (Default): Dapat membaca data yang belum dikomit.

    EXACTLY_ONCE bergantung pada read_committed. Jika tidak, konsumen mungkin melihat data yang belum dikomit, sehingga mengganggu konsistensi.

  • Timeout transaksi dan kehilangan data

    Saat memulihkan dari checkpoint, Realtime Compute for Apache Flink hanya mempertimbangkan transaksi yang telah dikomit sebelum checkpoint tersebut dimulai. Jika durasi antara kegagalan pekerjaan dan restart-nya melebihi timeout transaksi Kafka, Kafka secara otomatis membatalkan transaksi yang terbuka, yang dapat menyebabkan kehilangan data.

    • transaction.max.timeout.ms default untuk broker Kafka adalah 15 menit.

    • Secara default, Flink Kafka Sink mengatur parameter transaction.timeout.ms ke 1 jam.

    • Anda harus menaikkan transaction.max.timeout.ms pada broker agar lebih besar dari atau sama dengan pengaturan di Flink.

  • Pool produsen dan checkpoint konkuren

    Mode EXACTLY_ONCE menggunakan pool produsen Kafka berukuran tetap. Setiap checkpoint menggunakan satu produsen dari pool ini. Jika jumlah checkpoint konkuren melebihi ukuran pool, pekerjaan gagal.

    Konfigurasikan ukuran pool produsen berdasarkan jumlah maksimum checkpoint konkuren.

  • Batasan skala turun paralelisme

    Jika pekerjaan gagal sebelum checkpoint pertama selesai, informasi pool produsen asli hilang saat restart. Oleh karena itu, jangan melakukan skala turun paralelisme pekerjaan sebelum checkpoint pertama selesai. Jika skala turun diperlukan, paralelisme baru tidak boleh kurang dari FlinkKafkaProducer.SAFE_SCALE_DOWN_FACTOR.

  • Transaksi memblokir pembacaan

    Dalam mode read_committed, transaksi apa pun yang belum dikomit atau dibatalkan memblokir operasi baca pada seluruh topik.

    Contoh:

    • Transaksi 1 menulis data.

    • Transaksi 2 menulis lebih banyak data dan dikomit.

    • Selama Transaksi 1 tetap terbuka, data dari Transaksi 2 yang telah dikomit tidak terlihat oleh konsumen.

    Hal ini memiliki implikasi berikut:

    • Selama operasi normal, latensi visibilitas data kira-kira sama dengan interval checkpoint.

    • Jika pekerjaan gagal, topik apa pun yang sedang ditulisnya diblokir untuk konsumen sampai pekerjaan dijalankan ulang atau transaksi timeout. Dalam kasus ekstrem, proses timeout transaksi itu sendiri juga dapat memengaruhi operasi baca.

FAQ