Pengelolaan siklus proses skema

Saat aplikasi dan persyaratan datanya berubah, struktur pesan Kafka Anda juga perlu disesuaikan. Pengelolaan siklus proses skema yang efektif sangat penting untuk menangani perubahan ini dengan lancar dan menjaga integritas data. Proses ini tidak hanya melibatkan perubahan skema, tetapi juga secara sistematis mengontrol jenis perubahan yang aman, atau cukup kompatibel, untuk aplikasi yang bergantung padanya.

Registry skema Managed Service for Apache Kafka mendukung siklus proses lengkap pengelolaan skema dan mencakup fitur berikut:

  • Tentukan dan terapkan aturan kompatibilitas (jenis kompatibilitas) untuk mengelola evolusi skema saat versi skema baru diperkenalkan. Aturan ini memastikan produsen dan konsumen terus beroperasi dengan benar.

  • Konfigurasi kontrol operasional (mode skema) untuk mengelola kemampuan berubah skema di berbagai tingkat, sehingga mengamankan pipeline pemrosesan data Anda.

  • Kelola referensi skema untuk meningkatkan penggunaan ulang dan konsistensi di seluruh skema Anda.

Cara kerja evolusi skema

  1. Anda mengubah definisi skema. Misalnya—tambahkan kolom opsional ke file .proto atau .avsc Anda.

  2. Produsen yang dikonfigurasi dengan auto.register.schemas=true mengirim pesan menggunakan skema baru, atau Anda secara eksplisit mencoba mendaftarkan skema baru menggunakan API atau library klien.

  3. Saat permintaan pendaftaran untuk versi baru mencapai registry skema, permintaan tersebut akan mengambil aturan kompatibilitas yang dikonfigurasi untuk subjek target. Hal ini membandingkan skema baru yang diusulkan dengan versi sebelumnya yang diperlukan sesuai dengan aturan tersebut.

  4. Jika versi skema kompatibel, skema baru berhasil didaftarkan sebagai versi berikutnya di bawah subjek, diberi nomor versi baru, dan berpotensi memiliki schema_id baru jika definisinya unik.

  5. Produser (jika ada) menerima schema_id untuk disertakan dengan pesan.

  6. Jika versi skema tidak kompatibel, upaya pendaftaran akan gagal, dan error akan ditampilkan.

Tentang jenis kompatibilitas

Kompatibilitas skema memungkinkan Anda menentukan cara registry skema menangani pemeriksaan kompatibilitas antara versi skema yang berbeda. Anda dapat menerapkan konfigurasi ini di berbagai tingkat dalam hierarki registry skema, seperti yang ditunjukkan oleh opsi pola resource berikut:

  • Tingkat registry: Menetapkan konfigurasi default untuk seluruh registry skema.

    • Jalur: projects/project/locations/location/schemaRegistries/schema_registry/config

  • Tingkat subjek dalam konteks default: Menetapkan konfigurasi spesifik untuk subjek dalam konteks default registri.

    • Jalur: projects/project/locations/location/schemaRegistries/schema_registry/config/subject

  • Tingkat subjek dalam konteks tertentu: Menetapkan konfigurasi tertentu untuk subjek dalam konteks bernama.

    • Jalur: projects/project/locations/location/schemaRegistries/schema_registry/contexts/context/config/subject

Konfigurasi yang ditetapkan di tingkat subjek akan menggantikan konfigurasi yang ditetapkan di tingkat registri. Jika setelan tidak ditentukan di tingkat subjek, setelan akan mewarisi nilai dari tingkat registri. Jika tidak ditetapkan secara eksplisit di tingkat registri, defaultnya adalah Backward.

Jenis yang tersedia berikut menentukan cara registry skema membandingkan versi skema baru dengan versi sebelumnya:

  • None: Tidak ada pemeriksaan kompatibilitas yang dilakukan. Mengizinkan perubahan apa pun, tetapi membawa risiko tinggi merusak klien.

  • Backward (Default): Aplikasi konsumen yang menggunakan skema baru dapat mendekode data yang dihasilkan hanya dengan skema yang terdaftar sebelumnya. Hal ini memungkinkan penambahan kolom opsional dan penghapusan kolom. Konsumen harus diupgrade sebelum produsen.

  • Backward_transitive: Aplikasi konsumen yang menggunakan skema baru dapat mendekode data yang dihasilkan dengan semua versi skema sebelumnya dalam subjek tersebut. Setelan ini lebih ketat daripada Backward.

  • Forward: Data yang dihasilkan menggunakan skema baru harus dapat dibaca oleh klien yang menggunakan skema terdaftar sebelumnya. Produsen harus diupgrade terlebih dahulu, tetapi konsumen yang menggunakan skema baru mungkin tidak dapat membaca data yang dihasilkan dengan skema yang lebih lama. Setelan ini memungkinkan penghapusan kolom opsional dan penambahan kolom.

  • Forward_transitive: Data yang dihasilkan menggunakan skema baru harus dapat dibaca menggunakan semua versi skema sebelumnya. Setelan ini lebih ketat daripada Forward.

  • Full: Skema baru kompatibel dengan versi skema yang terdaftar sebelumnya, baik secara mundur maupun maju. Klien dapat diupgrade dalam urutan apa pun relatif terhadap produser menggunakan skema baru. Memungkinkan penambahan atau penghapusan kolom opsional.

  • Full_transitive: Skema baru ini kompatibel dengan semua versi skema sebelumnya dalam subjek tersebut. Setelan ini lebih ketat daripada Full.

Contoh jenis kompatibilitas

Asumsikan Anda memiliki registry skema dengan jenis kompatibilitas Backward. Anda juga membuat beberapa subjek dalam registry ini, dan subjek tersebut mewarisi kompatibilitas Backward registry.

Untuk subjek tertentu bernama user-events, Anda memerlukan aturan kompatibilitas yang lebih ketat. Anda memperbarui tingkat kompatibilitas skema untuk user-events tunduk pada Full.

Dalam situasi ini, aturan berikut berlaku:

  • Setiap versi skema baru yang terdaftar dalam subjek user-events harus kompatibel mundur dan maju dengan versi skema yang terdaftar sebelumnya untuk subjek tersebut.

  • Subjek lain dalam registry skema tetap mematuhi setelan kompatibilitas Backward tingkat registry kecuali jika kompatibilitasnya telah dikonfigurasi secara eksplisit.

Jika Anda kemudian mengubah tingkat kompatibilitas registry skema menjadi Forward, perubahan ini akan memengaruhi kompatibilitas default untuk subjek baru yang dibuat dalam registry. Namun, subjek user-events akan mempertahankan kompatibilitas Full yang ditetapkan secara eksplisit, karena konfigurasi tingkat subjek menggantikan konfigurasi tingkat registri.

Hal ini menunjukkan cara Anda dapat memiliki tingkat kompatibilitas default untuk seluruh registri sekaligus memiliki fleksibilitas untuk menentukan persyaratan kompatibilitas tertentu untuk setiap subjek berdasarkan kebutuhan aplikasi Anda.

Untuk mengetahui informasi selengkapnya, lihat Jenis kompatibilitas update.

Praktik Terbaik Mode Kompatibilitas

  • Jangan gunakan None sebagai strategi jenis kompatibilitas karena Anda berisiko merusak klien dengan perubahan skema.

  • Pilih strategi berbasis penerusan seperti Forward atau Forward-transitive jika Anda ingin memperbarui produsen terlebih dahulu. Pilih strategi berbasis mundur seperti Backward atau Backward-transitive jika Anda ingin memperbarui konsumen terlebih dahulu.

  • Pilih strategi transitif jika Anda ingin mempertahankan kompatibilitas dengan beberapa versi skema sebelumnya. Jika Anda ingin memaksimalkan kompatibilitas dan meminimalkan risiko merusak klien saat memperbarui versi skema, gunakan strategi Full-transitive.

Tentang referensi skema

Referensi skema memungkinkan Anda menentukan struktur umum satu kali dan merujuknya dari beberapa skema. Misalnya, skema Address dapat digunakan sebagai bagian dari skema Customer dan Supplier.

Pendekatan ini meningkatkan penggunaan kembali dan konsistensi di seluruh skema Anda. Selain itu, penggunaan referensi skema menciptakan dependensi yang jelas, yang secara eksplisit melacak skema mana yang bergantung pada skema lain. Hal ini meningkatkan kemudahan pemeliharaan arsitektur skema Anda.

Jika satu skema perlu menggunakan skema umum lain, skema tersebut menyertakan referensi ke skema umum tersebut. Hubungan ini secara formal ditentukan oleh SchemaReference struktur.

SchemaReference memiliki komponen berikut:

  • name (string): nama yang sepenuhnya memenuhi syarat dari skema yang direferensikan untuk format Avro atau nama file jenis yang diimpor untuk format Protobuf, seperti yang digunakan dalam definisi skema itu sendiri.

  • subject (string): nama subjek yang digunakan untuk mendaftarkan skema yang dirujuk dalam registry skema.

  • version (int32): nomor versi tertentu dari skema yang dirujuk.

Skema yang menggunakan skema lain mendeklarasikan dependensi ini di kolom references. Kolom ini menyimpan daftar objek SchemaReference.

Contoh untuk referensi skema

Anggaplah Anda perlu menentukan skema untuk data Customer dan data Supplier, dan keduanya harus menyertakan alamat. Dengan referensi skema, Anda dapat menentukan struktur alamat sekali dan menggunakannya kembali.

Untuk mengikuti contoh ini, lihat Membuat subjek.

  1. Buat subjek bernama address_schema, dan daftarkan definisi untuk alamat standar. Saat membuat subjek untuk pertama kalinya, Anda juga membuat skema versi 1 untuk subjek tersebut.

    Avro

    Buat dan simpan ini sebagai subjek address_schema_avro versi 1.

    {
  "type": "record",
  "name": "Address",
  "namespace": "com.example.common",
  "fields": [
    {"name": "street", "type": "string"},
    {"name": "city", "type": "string"},
    {"name": "zipCode", "type": "string"},
    {"name": "country", "type": "string", "default": "USA"}
  ]
}

    Protobuf

    Buat dan simpan ini sebagai subjek address_schema_proto versi 1.

    syntax = "proto3";

package com.example.common;

message Address {
  string street = 1;
  string city = 2;
  string zip_code = 3;
  string country = 4;
}

  2. Buat skema customer_schema. Daripada mengulangi kolom alamat, Anda merujuk ke skema address_schema.

    Avro

    Jenis kolom billingAddress com.example.common.Address merujuk ke skema Address yang ditentukan pada langkah sebelumnya.

    {
  "type": "record",
  "name": "Customer",
  "namespace": "com.example.crm",
  "fields": [
    {"name": "customerId", "type": "long"},
    {"name": "customerName", "type": "string"},
    // This field's type refers to the Address schema
    {"name": "billingAddress", "type": "com.example.common.Address"}
  ]
}

    Saat mendaftarkan customer_schema_avro, metadatanya akan menyertakan referensi skema:

    // Conceptual metadata for customer_schema_avro
"references": [
  {
    "name": "com.example.common.Address",
    "subject": "address_schema_avro",
    "version": 1
  }
]

    Protobuf

    File customer.proto mengimpor address.proto dan menggunakan com.example.common.Address untuk kolom billing_address.

    syntax = "proto3";
package com.example.crm;
import "address.proto";

message Customer {
  int64 customer_id = 1;
  string customer_name = 2;
  // This field's type refers to the imported Address message
  com.example.common.Address billing_address = 3;
}

    Saat mendaftarkan customer_schema_proto, metadatanya akan menyertakan referensi skema:

    // Conceptual metadata for customer_schema_proto
"references": [
  {
    "name": "address.proto",
    "subject": "address_schema_proto",
    "version": 1
  }
]

  3. Demikian pula, untuk skema Supplier, Anda akan menambahkan referensi skema yang mengarah ke skema Address umum yang sama.

Tentang mode skema

Mode skema menentukan status operasional registry skema atau subjek tertentu, dan mengontrol jenis modifikasi yang diizinkan. Mode skema dapat diterapkan ke registri atau subjek tertentu dalam registri skema. Berikut adalah jalur untuk resource mode skema:

  • Mode tingkat registri: berlaku untuk seluruh registri skema.

    • Jalur: projects/project/locations/location/schemaRegistry/schema_registry/mode

  • Mode subjek tingkat registry: berlaku untuk subjek tertentu dalam seluruh registry skema.

    • Jalur: projects/project/locations/location/schemaRegistries/schema_registry/mode/subject

Mode berikut didukung:

  • Readonly: dalam mode ini, schema registry atau subjek yang ditentukan tidak dapat diperbarui. Modifikasi, seperti memperbarui konfigurasi atau menambahkan versi skema baru, dicegah.

  • Readwrite: mode ini memungkinkan operasi penulisan terbatas pada registry skema atau subjek yang ditentukan. Hal ini memungkinkan modifikasi seperti mengupdate konfigurasi dan menambahkan versi skema baru. Ini adalah mode default untuk pendaftaran skema baru dan subjek baru.

Saat menentukan apakah modifikasi diizinkan untuk subjek tertentu, mode yang ditetapkan di tingkat subjek lebih diutamakan daripada mode yang ditetapkan di tingkat registry skema.

Misalnya, jika registry skema berada dalam mode Readonly, tetapi subjek tertentu di dalamnya berada dalam mode Readwrite, modifikasi pada subjek tertentu tersebut diizinkan. Namun, pembuatan subjek baru dibatasi oleh mode Readonly tingkat registri.

Contoh untuk mode skema

Pertimbangkan registry skema dengan mode yang ditetapkan ke Readwrite. Konfigurasi ini berarti Anda dapat menambahkan subjek baru ke registri dan versi skema baru ke subjek yang ada.

Asumsikan bahwa Anda memiliki subjek bernama production-config yang ingin Anda lindungi dari perubahan yang tidak disengaja. Anda menetapkan mode untuk production-config subjek ke Readonly. Akibatnya, kondisi berikut berlaku untuk subjek production-config:

  • Anda tidak dapat menambahkan versi skema baru ke subjek.

  • Anda tidak dapat memperbarui konfigurasi (seperti jenis kompatibilitas) untuk subjek.

  • Subjek lain dalam registri yang tidak memiliki modenya sendiri yang ditetapkan secara eksplisit akan tetap dalam mode Readwrite, sehingga Anda tetap dapat mengubahnya.

  • Anda dapat terus membuat subjek di registri karena registri itu sendiri masih dalam mode Readwrite.

Selanjutnya, Anda dapat memutuskan untuk menempatkan seluruh registry skema ke dalam status pemeliharaan dengan menyetel mode tingkat registry ke Readonly. Namun, Anda memiliki subjek lain, staging-config, yang harus tetap dapat dimodifikasi untuk pengujian berkelanjutan. Anda secara eksplisit menetapkan mode untuk subjek staging-config ke Readwrite. Akibatnya, kondisi berikut berlaku untuk subjek:staging-config

  • Registry skema kini Readonly. Anda tidak dapat membuat subjek baru.

  • Sebagian besar subjek yang ada seperti yang tanpa penggantian mode tertentu juga menjadi Readonly karena pewarisan. Anda tidak dapat menambahkan versi skema baru ke dalamnya atau mengupdate konfigurasinya.

  • Subjek production-config tetap Readonly seperti yang ditetapkan secara eksplisit.

  • Subjek staging-config tetap dalam mode Readwrite karena setelan tingkat subjeknya menggantikan mode Readonly tingkat registri. Anda dapat terus menambahkan versi skema dan mengupdate konfigurasi untuk staging-config.

Pendekatan hierarkis ini memberikan fleksibilitas dalam mengelola modifikasi skema pada berbagai tingkat perincian.

Untuk mengetahui informasi selengkapnya tentang cara mengupdate mode skema, lihat bagian Mengupdate mode skema.

Konfigurasi yang direkomendasikan untuk menggunakan schema registry dalam produksi

Untuk mengamankan skema Anda di lingkungan produksi, terapkan konfigurasi berikut:

  • Mencegah pendaftaran skema baru dengan menyetel mode=READONLY untuk seluruh registry skema atau untuk topik produksi tertentu.

  • Mencegah klien Kafka membuat versi skema baru dengan memastikan bahwa klien tersebut tidak memiliki izin create version.

  • Di serializer klien Kafka, tetapkan auto.register.schemas=false. Untuk Kafka Connect, konfigurasi setelan ini untuk serializer kunci dan nilai sesuai kebutuhan:

    • key.serializer.auto.register.schemas=false
    • value.serializer.auto.register.schemas=false

  • (Opsional) Untuk mewajibkan klien menggunakan skema terbaru untuk subjek, tetapkan use.latest.version=true di serializer atau deserializer. Setelan ini mengarahkan klien untuk menggunakan versi skema terbaru yang terdaftar untuk subjek, bukan versi yang cocok dengan pesan tertentu.

Langkah berikutnya

Apache Kafka® adalah merek dagang terdaftar milik The Apache Software Foundation atau afiliasinya di Amerika Serikat dan/atau negara lain.