Pengelolaan siklus proses skema

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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 mempertahankan integritas data. Proses ini tidak hanya mengubah skema, tetapi juga mengontrol secara sistematis jenis perubahan yang aman, atau cukup kompatibel, untuk aplikasi yang bergantung padanya.

Managed Service untuk Apache Kafka schema registry mendukung siklus proses pengelolaan skema lengkap dan mencakup fitur berikut:

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

• Mengonfigurasi kontrol operasional (mode skema) untuk mengelola mutabilitas skema di berbagai tingkat, sehingga melindungi pipeline pemrosesan data Anda.

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

Cara kerja evolusi skema

1. Anda mengubah definisi skema. Misalnya, menambahkan kolom opsional ke file .proto atau .avsc.

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 schema registry, permintaan tersebut akan mengambil aturan kompatibilitas yang dikonfigurasi untuk subjek target. Skema tersebut membandingkan skema baru yang diusulkan dengan versi sebelumnya yang diperlukan sesuai dengan aturan tersebut.

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

5. Produsen (jika berlaku) 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 schema registry menangani pemeriksaan kompatibilitas antara versi skema yang berbeda. Anda dapat menerapkan konfigurasi ini di berbagai tingkat dalam hierarki schema registry, seperti yang ditunjukkan oleh opsi pola resource berikut:

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

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

• Tingkat subjek dalam konteks default: Menetapkan konfigurasi tertentu untuk subjek dalam konteks default registry.

  • 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 mengganti konfigurasi yang ditetapkan di tingkat registry. Jika setelan tidak ditentukan di tingkat subjek, setelan tersebut akan mewarisi nilai dari tingkat registry. Jika tidak ditetapkan secara eksplisit di tingkat registry, nilai defaultnya adalah Backward.

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

• None: Tidak ada pemeriksaan kompatibilitas yang dilakukan. Memungkinkan perubahan apa pun, tetapi memiliki risiko tinggi untuk merusak klien.

• Backward (Default): Aplikasi konsumen yang menggunakan skema baru dapat mendekode data yang dihasilkan hanya dengan skema yang sebelumnya terdaftar. 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 sebelumnya terdaftar, baik mundur maupun maju. Klien dapat diupgrade dalam urutan apa pun yang relatif terhadap produsen yang menggunakan skema baru. Memungkinkan penambahan atau penghapusan kolom opsional.

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

Contoh jenis kompatibilitas

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

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

Dalam situasi ini, aturan berikut berlaku:

• Setiap versi skema baru yang terdaftar di bawah subjek user-events harus kompatibel dengan versi skema yang sebelumnya terdaftar untuk subjek tersebut, baik mundur maupun maju.

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

Jika Anda kemudian mengubah tingkat kompatibilitas schema registry 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 mengganti konfigurasi tingkat registry.

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

Untuk mengetahui informasi selengkapnya, lihat Mengupdate jenis kompatibilitas.

Praktik Terbaik Mode Kompatibilitas

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

• Pilih strategi berbasis maju seperti Forward atau Forward-transitive jika Anda ingin mengupdate produsen terlebih dahulu. Pilih strategi berbasis mundur seperti Backward atau Backward-transitive jika Anda ingin mengupdate 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 mengupdate versi skema, gunakan strategi Full-transitive.

Tentang referensi skema

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

Pendekatan ini meningkatkan penggunaan ulang dan konsistensi di seluruh skema Anda. Selain itu, penggunaan referensi skema akan membuat dependensi yang jelas, yang secara eksplisit melacak skema mana yang bergantung pada skema lainnya. Hal ini meningkatkan kemampuan pemeliharaan arsitektur skema Anda.

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

SchemaReference memiliki komponen berikut:

• name (string): nama lengkap 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 tempat skema yang direferensikan terdaftar di schema registry.

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

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

Contoh referensi skema

Misalnya, 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 mereferensikan 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 schema registry atau subjek tertentu, dan mengontrol jenis modifikasi yang diizinkan. Mode skema dapat diterapkan ke registry atau subjek tertentu dalam schema registry. Berikut adalah jalur untuk resource mode skema:

• Mode tingkat registry: berlaku untuk seluruh schema registry.

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

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

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

Mode berikut didukung:

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

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

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

Misalnya, jika schema registry 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 registry.

Contoh mode skema

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

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

• Anda tidak dapat menambahkan versi skema baru ke subjek.

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

• Subjek lain dalam registry yang tidak memiliki mode sendiri yang ditetapkan secara eksplisit tetap berada dalam mode Readwrite, sehingga Anda masih dapat mengubahnya.

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

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

• Schema registry kini Readonly. Anda tidak dapat membuat subjek baru.

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

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

• Subjek staging-config tetap dalam mode Readwrite karena setelan tingkat subjeknya mengganti mode Readonly tingkat registry. 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 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 menetapkan mode=READONLY untuk seluruh schema registry 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, konfigurasikan setelan ini untuk serializer kunci dan nilai sesuai kebutuhan:

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

• (Opsional) Untuk memaksa 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

• Membuat schema registry

• Membuat subjek

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