Menghubungkan Pub/Sub Lite ke Apache Kafka

Dokumen ini menjelaskan cara mengintegrasikan Apache Kafka dan Pub/Sub Lite menggunakan Pub/Sub Group Kafka Connector.

Catatan: Anda juga dapat menggunakan konektor ini dengan Pub/Sub. Lihat Menghubungkan Pub/Sub ke Apache Kafka.

Tentang Konektor Kafka Pub/Sub Group

Apache Kafka adalah platform open source untuk streaming acara. Ini biasanya digunakan dalam arsitektur terdistribusi untuk memungkinkan komunikasi antara komponen yang dikaitkan secara longgar. Pub/Sub Lite adalah layanan terkelola untuk mengirim dan menerima pesan secara asinkron. Seperti Kafka, Anda dapat menggunakan Pub/Sub Lite untuk berkomunikasi antar-komponen dalam arsitektur cloud Anda.

Konektor Kafka Pub/Sub Group memungkinkan Anda mengintegrasikan kedua sistem ini. Konektor berikut dikemas dalam JAR Konektor:

• Konektor sink membaca kumpulan data dari satu atau beberapa topik Kafka dan memublikasikannya ke Pub/Sub Lite.
• Konektor sumber membaca pesan dari topik Pub/Sub Lite dan memublikasikannya ke Kafka.

Berikut adalah beberapa skenario yang mungkin membuat Anda menggunakan Pub/Sub Group Kafka Connector:

• Anda akan memigrasikan arsitektur berbasis Kafka ke Google Cloud.
• Anda memiliki sistem frontend yang menyimpan peristiwa di Kafka di luar Google Cloud, tetapi Anda juga menggunakan Google Cloud untuk menjalankan beberapa layanan backend yang perlu menerima peristiwa Kafka.
• Anda mengumpulkan log dari solusi Kafka lokal dan mengirimkannya ke Google Cloud untuk analisis data.
• Anda memiliki sistem frontend yang menggunakan Google Cloud, tetapi juga menyimpan data secara lokal menggunakan Kafka.

Konektor memerlukan Kafka Connect, yang merupakan framework untuk streaming data antara Kafka dan sistem lain. Untuk menggunakan konektor, Anda harus menjalankan Kafka Connect bersama cluster Kafka.

Dokumen ini mengasumsikan bahwa Anda telah memahami Kafka dan Pub/Sub Lite. Untuk mulai menggunakan Pub/Sub Lite, lihat Memublikasikan dan menerima pesan di Pub/Sub Lite menggunakan Konsol Google Cloud.

Memulai dengan Konektor Kafka Pub/Sub Group

Bagian ini akan memandu Anda melakukan tugas-tugas berikut:

1. Konfigurasikan Konektor Kafka Pub/Sub Group.
2. Mengirim peristiwa dari Kafka ke Pub/Sub Lite.
3. Mengirim pesan dari Pub/Sub Lite ke Kafka.

Catatan: Bagian ini menggunakan Kafka Connect dalam mode mandiri, yang cocok untuk pengujian. Untuk sistem produksi, mode terdistribusi direkomendasikan. Untuk mengetahui informasi cara menjalankan Kafka Connect dalam mode terdistribusi, lihat Menjalankan Kafka Connect dalam dokumentasi Apache Kafka.

Prasyarat

Instal Kafka

Ikuti panduan memulai Apache Kafka untuk menginstal Kafka node tunggal di komputer lokal Anda. Selesaikan langkah-langkah ini di panduan memulai:

1. Download rilis Kafka terbaru, lalu ekstrak.
2. Mulai lingkungan Kafka.
3. Membuat topik Kafka.

Autentikasikan

Konektor Kafka Pub/Sub Group harus melakukan autentikasi dengan Pub/Sub agar dapat mengirim dan menerima pesan Pub/Sub. Untuk menyiapkan autentikasi, lakukan langkah-langkah berikut:

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Buat atau pilih project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   • Membuat project Google Cloud:

     gcloud projects create PROJECT_ID

     Ganti PROJECT_ID dengan nama untuk project Google Cloud yang Anda buat.

   • Pilih project Google Cloud yang Anda buat:

     gcloud config set project PROJECT_ID

     Ganti PROJECT_ID dengan nama project Google Cloud Anda.

5. Buat kredensial autentikasi lokal untuk Akun Google Anda:

   gcloud auth application-default login

6. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/pubsublite.admin

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

   • Replace PROJECT_ID with your project ID.

   • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

   • Replace ROLE with each individual role.
7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Buat atau pilih project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   • Membuat project Google Cloud:

     gcloud projects create PROJECT_ID

     Ganti PROJECT_ID dengan nama untuk project Google Cloud yang Anda buat.

   • Pilih project Google Cloud yang Anda buat:

     gcloud config set project PROJECT_ID

     Ganti PROJECT_ID dengan nama project Google Cloud Anda.

10. Buat kredensial autentikasi lokal untuk Akun Google Anda:

    gcloud auth application-default login

11. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/pubsublite.admin

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

    • Replace ROLE with each individual role.

Catatan: Untuk beban kerja produksi, sebaiknya gunakan Workload identity federation untuk melakukan autentikasi.

Download JAR konektor

Download file JAR konektor ke komputer lokal Anda. Untuk mengetahui informasi selengkapnya, baca artikel Mendapatkan konektor di readme GitHub.

Salin file konfigurasi konektor

1. Clone atau download repositori GitHub untuk konektor.

   git clone https://github.com/googleapis/java-pubsub-group-kafka-connector.git
   cd java-pubsub-group-kafka-connector
   

2. Salin konten direktori config ke subdirektori config dari penginstalan Kafka Anda.

   cp config/* [path to Kafka installation]/config/
   

File ini berisi setelan konfigurasi untuk konektor.

Memperbarui konfigurasi Kafka Connect

1. Buka direktori yang berisi biner Kafka Connect yang telah Anda download.
2. Di direktori biner Kafka Connect, buka file bernama config/connect-standalone.properties dalam editor teks.
3. Jika plugin.path property diberi komentar, hapus tanda komentar.

4. Update plugin.path property untuk menyertakan jalur ke JAR konektor.

   Contoh:

   plugin.path=/home/PubSubKafkaConnector/pubsub-group-kafka-connector-1.0.0.jar
   

5. Tetapkan properti offset.storage.file.filename ke nama file lokal. Dalam mode mandiri, Kafka menggunakan file ini untuk menyimpan data offset.

   Contoh:

   offset.storage.file.filename=/tmp/connect.offsets
   

Meneruskan peristiwa dari Kafka ke Pub/Sub Lite

Bagian ini menjelaskan cara memulai konektor sink, memublikasikan peristiwa ke Kafka, lalu membaca pesan yang diteruskan dari Pub/Sub Lite.

1. Gunakan Google Cloud CLI untuk membuat reservasi Pub/Sub Lite.

   gcloud pubsub lite-reservations create RESERVATION_NAME \
   --location=LOCATION \
   --throughput-capacity=4

   Ganti kode berikut:

   • RESERVATION_NAME: Nama reservasi Pub/Sub Lite.
   • LOCATION: Lokasi reservasi.

2. Gunakan Google Cloud CLI untuk membuat topik Pub/Sub Lite dengan langganan.

   gcloud pubsub lite-topics create LITE_TOPIC \
   --location=LOCATION \
   --partitions=2 \
   --per-partition-bytes=30GiB \
   --throughput-reservation=RESERVATION_NAME
   
   gcloud pubsub lite-subscriptions create LITE_SUBSCRIPTION \
   --location=LOCATION \
   --topic=LITE_TOPIC

   Ganti kode berikut:

   • LITE_TOPIC: Nama topik Pub/Sub Lite untuk menerima pesan dari Kafka.
   • LOCATION: Lokasi topik. Nilai harus cocok dengan lokasi reservasi.
   • RESERVATION_NAME: Nama reservasi Pub/Sub Lite.
   • LITE_SUBSCRIPTION: Nama langganan Pub/Sub Lite untuk topik.

3. Buka file /config/pubsub-lite-sink-connector.properties di editor teks. Tambahkan nilai untuk properti berikut, yang ditandai "TODO" dalam komentar:

   topics=KAFKA_TOPICS
   pubsublite.project=PROJECT_ID
   pubsublite.location=LOCATION
   pubsublite.topic=LITE_TOPIC

   Ganti kode berikut:

   • KAFKA_TOPICS: Daftar yang dipisahkan koma untuk topik Kafka yang akan dibaca.
   • PROJECT_ID: Project Google Cloud yang berisi topik Pub/Sub Lite Anda.
   • LOCATION: Lokasi topik Pub/Sub Lite.
   • LITE_TOPIC: Topik Pub/Sub Lite untuk menerima pesan dari Kafka.

4. Dari direktori Kafka, jalankan perintah berikut:

   bin/connect-standalone.sh \
     config/connect-standalone.properties \
     config/pubsub-lite-sink-connector.properties
   

5. Ikuti langkah-langkah di panduan memulai Apache Kafka untuk menulis beberapa peristiwa ke topik Kafka.

6. Berlanggananlah ke langganan Pub/Sub Lite menggunakan salah satu metode yang ditunjukkan dalam Menerima pesan dari langganan Lite.

Meneruskan pesan dari Pub/Sub Lite ke Kafka

Bagian ini menjelaskan cara memulai konektor sumber, memublikasikan pesan ke Pub/Sub Lite, dan membaca pesan yang diteruskan dari Kafka.

1. Gunakan Google Cloud CLI untuk membuat reservasi Pub/Sub Lite.

   gcloud pubsub lite-reservations create RESERVATION_NAME \
   --location=LOCATION \
   --throughput-capacity=4

   Ganti kode berikut:

   • RESERVATION_NAME: Nama reservasi Pub/Sub Lite.
   • LOCATION: Lokasi reservasi.

2. Gunakan Google Cloud CLI untuk membuat topik Pub/Sub Lite dengan langganan.

   gcloud pubsub lite-topics create LITE_TOPIC \
   --location=LOCATION \
   --partitions=2 \
   --per-partition-bytes=30GiB \
   --throughput-reservation=RESERVATION_NAME
   
   gcloud pubsub lite-subscriptions create LITE_SUBSCRIPTION \
   --location=LOCATION \
   --topic=LITE_TOPIC

   Ganti kode berikut:

   • LITE_TOPIC: Nama topik Pub/Sub Lite.
   • LOCATION: Lokasi topik. Nilai harus cocok dengan lokasi reservasi.
   • RESERVATION_NAME: Nama reservasi Pub/Sub Lite.
   • LITE_SUBSCRIPTION: Nama langganan Pub/Sub Lite untuk topik.

3. Buka file bernama /config/pubsub-lite-source-connector.properties di editor teks. Tambahkan nilai untuk properti berikut, yang ditandai "TODO" dalam komentar:

   topic=KAFKA_TOPIC
   pubsublite.project=PROJECT_ID
   pubsublite.location=LOCATION
   pubsublite.subscription=LITE_SUBSCRIPTION

   Ganti kode berikut:

   • KAFKA_TOPIC: Topik Kafka untuk menerima pesan Pub/Sub.
   • PROJECT_ID: Project Google Cloud yang berisi topik Pub/Sub Anda.
   • LOCATION: Lokasi topik Pub/Sub Lite.
   • LITE_SUBSCRIPTION: Topik Pub/Sub Lite.

4. Dari direktori Kafka, jalankan perintah berikut:

   bin/connect-standalone.sh \
     config/connect-standalone.properties \
     config/pubsub-lite-source-connector.properties
   

5. Publikasikan pesan ke topik Pub/Sub Lite menggunakan salah satu metode yang ditampilkan dalam Memublikasikan pesan ke topik Lite.

6. Baca pesan dari Kafka. Ikuti langkah-langkah pada panduan memulai Apache Kafka untuk membaca pesan dari topik Kafka.

Konversi pesan

Data Kafka berisi kunci dan nilai, yang merupakan array byte panjang variabel. Secara opsional, data Kafka juga dapat memiliki header, yang merupakan pasangan nilai kunci. Pesan Pub/Sub Lite memiliki kolom berikut:

• key: Kunci pesan (bytes)
• data: Data pesan (bytes)
• attributes: Nol atau beberapa atribut. Setiap atribut adalah peta (key,values[]). Satu atribut dapat memiliki beberapa nilai.
• event_time: Stempel waktu peristiwa opsional yang disediakan pengguna.

Kafka Connect menggunakan pengonversi untuk membuat serialisasi kunci dan nilai ke dan dari Kafka. Untuk mengontrol serialisasi, tetapkan properti berikut dalam file konfigurasi konektor:

• key.converter: Konverter yang digunakan untuk membuat serialisasi kunci kumpulan data.
• value.converter: Konverter yang digunakan untuk membuat serialisasi nilai data.

Konversi dari Kafka ke Pub/Sub Lite

Konektor sink mengonversi data Kafka menjadi pesan Pub/Sub Lite seperti berikut.

Data Kafka (SinkRecord)	Pesan Pub/Sub Lite
Kunci	key
Nilai	data
Header	attributes
Stempel waktu	eventTime
Jenis stempel waktu	attributes["x-goog-pubsublite-source-kafka-event-time-type"]
Topik	attributes["x-goog-pubsublite-source-kafka-topic"]
Partisi	attributes["x-goog-pubsublite-source-kafka-offset"]
Offset	attributes["x-goog-pubsublite-source-kafka-partition"]

Kunci, nilai, dan header dienkode sebagai berikut:

• Skema null diperlakukan sebagai skema string.
• Payload byte ditulis langsung tanpa konversi.
• Payload string, bilangan bulat, dan floating point dienkode ke dalam urutan byte UTF-8.
• Semua payload lainnya dienkode ke dalam jenis Value Buffering Protokol, lalu dikonversi menjadi string byte.
  • Kolom string bertingkat dienkode ke dalam Value protobuf.
  • Kolom byte bertingkat dienkode ke Value protobuf yang menyimpan byte berenkode base64.
  • Kolom numerik bertingkat dienkode sebagai double ke dalam protobuf Value.
  • Peta dengan kunci array, peta, atau struct tidak didukung.

Konversi dari Pub/Sub Lite ke Kafka

Konektor sumber mengonversi pesan Pub/Sub Lite ke data Kafka sebagai berikut:

Pesan Pub/Sub Lite	Data Kafka (SourceRecord)
key	Kunci
data	Nilai
attributes	Header
event_time	Stempel waktu. Jika event_time tidak ada, waktu publikasi akan digunakan.

Opsi konfigurasi

Selain konfigurasi yang disediakan oleh Kafka Connect API, konektor mendukung konfigurasi Pub/Sub Lite berikut.

Opsi konfigurasi konektor sink

Konektor sink mendukung opsi konfigurasi berikut.

Setelan	Jenis data	Deskripsi
connector.class	String	Wajib. Class Java untuk konektor. Untuk konektor sink Pub/Sub Lite, nilainya harus com.google.pubsublite.kafka.sink.PubSubLiteSinkConnector.
gcp.credentials.file.path	String	Opsional. Jalur ke file yang menyimpan kredensial Google Cloud untuk mengautentikasi Pub/Sub Lite.
gcp.credentials.json	String	Opsional. Blob JSON yang berisi Google Cloud untuk mengautentikasi Pub/Sub Lite.
pubsublite.location	String	Wajib diisi. Lokasi topik Pub/Sub Lite.
pubsublite.project	String	Wajib diisi. Google Cloud yang berisi topik Pub/Sub Lite.
pubsublite.topic	String	Wajib diisi. Topik Pub/Sub Lite sebagai tujuan publikasi data Kafka.
topics	String	Wajib diisi. Daftar topik Kafka yang dipisahkan koma untuk dibaca.

Opsi konfigurasi konektor sumber

Konektor sumber mendukung opsi konfigurasi berikut.

Setelan	Jenis data	Deskripsi
connector.class	String	Wajib. Class Java untuk konektor. Untuk konektor sumber Pub/Sub Lite, nilainya harus com.google.pubsublite.kafka.source.PubSubLiteSourceConnector.
gcp.credentials.file.path	String	Opsional. Jalur ke file yang menyimpan kredensial Google Cloud untuk mengautentikasi Pub/Sub Lite.
gcp.credentials.json	String	Opsional. Blob JSON yang berisi Google Cloud untuk mengautentikasi Pub/Sub Lite.
kafka.topic	String	Wajib diisi. Topik Kafka yang menerima pesan dari Pub/Sub Lite.
pubsublite.location	String	Wajib diisi. Lokasi topik Pub/Sub Lite.
pubsublite.partition_flow_control.bytes	Long	Jumlah maksimum byte yang belum diproses per partisi Pub/Sub Lite. Default: 20.000.000
pubsublite.partition_flow_control.messages	Long	Jumlah maksimum pesan yang belum terselesaikan per partisi Pub/Sub Lite. Default: Long.MAX_VALUE
pubsublite.project	String	Wajib. Project Google Cloud yang berisi topik Pub/Sub Lite.
pubsublite.subscription	String	Wajib diisi. Nama langganan Pub/Sub Lite yang akan mengambil pesan.

Langkah selanjutnya

• Pahami perbedaan antara Kafka dan Pub/Sub.
• Pelajari lebih lanjut Konektor Kafka Pub/Sub Group.
• Lihat repositori GitHub Pub/Sub Group Kafka Connector.