Migrasi ke format tabel tunggal untuk KCL 3.5.x +

Dimulai dengan KCL 3.5, Anda dapat mengkonsolidasikan semua metadata DynamoDB ke dalam tabel sewa tunggal menggunakan format tabel tunggal. Secara default, KCL 3.x membuat tiga tabel DynamoDB untuk setiap aplikasi: tabel sewa, tabel metrik pekerja, dan tabel status koordinator. Format tabel tunggal mengurangi ketiga tabel ini menjadi satu, yang membantu Anda menghindari batas tabel tingkat akun DynamoDB.

Cara kerja format tabel tunggal

Dalam format tabel tunggal, KCL menyimpan metrik pekerja dan entri status koordinator di tabel sewa bersama entri sewa. Setiap item menyertakan entityType atribut yang membedakan antara jenis rekaman yang berbeda.

Metrik pekerja dan item status koordinator menggunakan struktur kunci utama yang sama dengan tabel sewa tetapi menyertakan nilai yang berbeda. entityType Atribut ini memungkinkan KCL untuk mengidentifikasi tujuan setiap item selama pemindaian tabel.

Setiap komponen KCL menyaring entri yang diperlukan untuk logika bisnisnya berdasarkan atribut. entityType Misalnya, Manajer Penugasan Sewa (LAM) memfilter entri metrik sewa dan pekerja untuk melakukan penugasan sewa.

Konfigurasikan format tabel tunggal

Cara Anda mengaktifkan format tabel tunggal tergantung pada versi KCL Anda saat ini:

• Jika Anda menggunakan KCL 2.x: Ikuti panduan migrasi yang diperbarui untuk meningkatkan ke KCL 3.5. Format tabel tunggal digunakan secara default untuk migrasi baru dari 2.x ke 3.5.

• Jika Anda menggunakan KCL 3.0—3.4: Anda harus melakukan penerapan dua fase untuk bermigrasi ke format tabel tunggal. Lihat konfigurasi dan langkah migrasi berikut.

Untuk pelanggan KCL 3.x yang ada, atur opsi migrateAllEntitiesToLeaseTable konfigurasi di. CoordinatorConfig Opsi ini mengontrol apakah KCL menyimpan semua jenis entitas metadata dalam tabel sewa.

Nilai konfigurasi untuk migrasi AllEntitiesToLeaseTable

Nilai	Default	Efek
false	Ya	KCL menggunakan tabel terpisah untuk metrik pekerja dan status koordinator. Kode aplikasi mendukung format tabel tunggal tetapi tidak mengaktifkannya.
true	Tidak	KCL mulai menulis metrik pekerja dan data status koordinator ke dalam tabel sewa. Tetapkan nilai ini pada penerapan Fase 2 setelah TableMigrationStatus jangkauan DEPLOYED dan Anda telah memanggang tanpa regresi.

Migrasi dari KCL 3.x ke format tabel tunggal memerlukan penerapan dua fase:

1. Fase 1: Terapkan kode KCL 3.5 yang diperbarui dengan migrateAllEntitiesToLeaseTable disetel ke false (default). Ini menginstal kode baru yang mendukung format tabel tunggal tetapi tidak mengaktifkan migrasi.

2. Fase 2: Setelah semua pekerja menjalankan kode baru dan TableMigrationStatus jangkauanDEPLOYED, dan Anda telah memverifikasi bahwa tidak ada regresi, terapkan lagi dengan migrateAllEntitiesToLeaseTable set true untuk memulai migrasi.

Status migrasi

TableMigrationStateMachineMengelola transisi dari format multi-tabel ke format tabel tunggal. KCL melacak status migrasi saat ini dalam entri status koordinator terpisah yang disebut TableMigration3.5 dalam tabel status koordinator. Untuk daftar lengkap status, transisi, dan deskripsi, lihat status migrasi tabel tunggal KCL di situs web. GitHub

Status migrasi format tabel tunggal

Status	Deskripsi	Kondisi transisi
INIT	Keadaan awal. Semua pekerja memancarkan kode dukungan minimum dalam statistik metrik pekerja. Pekerja terus memancarkan metrik pekerja ke dalam tabel lama dan membaca metrik pekerja dan status koordinator dari tabel lama dan sewa. Secara fungsional, tidak ada perbedaan antara INIT dan DEPLOYED.	Semua pekerja memancarkan kode dukungan minimum dengan mantap untuk waktu pemanggangan. Aplikasi siap untuk pindah ke penyebaran Fase 2.
DEPLOYED	Semua pekerja telah dikerahkan dengan kode baru (Fase 1 selesai). Aplikasi ini mendukung format tabel tunggal tetapi belum mengaktifkannya.	Penerapan fase 2 dimulai dengan migrateAllEntitiesToLeaseTable set ketrue.
PENDING	Semua pekerja menjalankan kode baru. KCL memigrasikan data dari metrik pekerja dan tabel status koordinator ke dalam tabel sewa.	Waktu pemanggangan default 24 jam berlalu setelah migrasi selesai.
COMPLETE	Migrasi selesai. KCL menggunakan tabel sewa khusus untuk semua membaca dan menulis. Metrik pekerja lama dan tabel status koordinator tidak lagi digunakan.	Status terminal. Tidak ada transisi lebih lanjut yang terjadi.

Untuk informasi rinci tentang setiap status, kondisi transisi, dan perilaku mesin status lengkap, lihat mesin status migrasi tabel tunggal KCL di GitHub situs web.

catatan

Waktu pemanggangan default antara status PENDING dan COMPLETE adalah 24 jam, tetapi Anda dapat mengonfigurasinya hingga satu minggu. Selama periode ini, KCL menggunakan tabel sewa untuk semua membaca dan menulis tetapi tidak menghapus tabel lama. Anda harus secara manual menghapus metrik pekerja lama dan tabel status koordinator setelah Anda mengonfirmasi migrasi berhasil. KCL tidak menghapus tabel ini secara otomatis.

Metrik migrasi

Dengan KCL, Anda dapat memantau kemajuan dan kesehatan migrasi tabel tunggal menggunakan CloudWatch metrik. Gunakan metrik ini untuk mengonfirmasi bahwa pekerja telah mengadopsi kode baru dan melacak migrasi saat bergerak melalui statusnya. Anda juga dapat mendeteksi DynamoDB membaca, menulis, atau menghapus kesalahan selama migrasi. Tabel berikut mengelompokkan metrik berdasarkan operasi KCL (dimensi metrik) yang memancarkannya dan kapan setiap metrik dipancarkan.

Pekerja pemimpin terpilih terus memancarkan metrik berikut, terlepas dari apakah migrasi sedang berlangsung:

Metrik yang dipancarkan oleh pemimpin setiap saat

Operasi	Metrik	Unit	Deskripsi
TableMigration	StatusOrdinal	Tidak ada	Ordinal status migrasi DynamoDB saat ini0: = UNKNOWN1, = INIT, = DEPLOYED2, = PENDING3, = SELESAI. 4
WorkerMetrics	FleetMinSupportCode	Tidak ada	Kode dukungan minimum di semua pekerja yang memiliki sewa di armada.

Pekerja pemimpin terpilih memancarkan metrik berikut hanya saat migrasi sedang berlangsung:

Metrik yang dipancarkan oleh pemimpin selama migrasi

Operasi	Metrik	Unit	Deskripsi
TableMigration	Phase1Worker	Hitungan	Jumlah pekerja yang mendukung operasi dengan tabel DynamoDB tunggal tetapi belum bermigrasi untuk menggunakan tabel tunggal.
TableMigration	Phase2Worker	Hitungan	Jumlah pekerja yang telah bermigrasi untuk menulis ke tabel tunggal. Pekerja ini mungkin masih membaca dari beberapa tabel hingga migrasi tabel selesai.
TableMigration	PrePhase1Worker	Hitungan	Jumlah pekerja pada versi sebelum 3.5 yang tidak dapat mendukung operasi pada tabel DynamoDB tunggal.
TableMigration	WriteFault	Hitungan	1pada kegagalan 0 penulisan DynamoDB, pada kesuksesan.
TableMigration	DeleteFault	Hitungan	1pada kegagalan 0 penghapusan DynamoDB, pada keberhasilan.
TableMigration	CompletionFault	Hitungan	1ketika penulisan transaksional COMPLETE status gagal, 0 pada keberhasilan.
TableMigrationAsyncMove	Success	Hitungan	1pada langkah transaksional yang sukses dari CoordinatorState entri, 0 pada kegagalan.
TableMigrationAsyncMove	Time	Milidetik	Durasi operasi pemindahan asinkron.
TableMigrationAsyncMove	BatchCount	Hitungan	Jumlah batch yang berhasil dipindahkan.

Semua pekerja memancarkan metrik berikut saat migrasi sedang berlangsung:

Metrik yang dipancarkan oleh semua pekerja selama migrasi

Operasi	Metrik	Unit	Deskripsi
TableMigration	ReadFault	Hitungan	1pada kegagalan untuk membaca TableMigrationState dari DynamoDB, pada kesuksesan0.
TableMigration	Time	Milidetik	Durasi mesin negara berjalan.
TableMigrationInitialize	Success	Hitungan	1pada inisialisasi yang berhasil, 0 pada kegagalan.
TableMigrationInitialize	Time	Milidetik	Durasi operasi inisialisasi.

Gunakan metrik ini untuk memutuskan kapan harus memajukan migrasi. StatusOrdinalKapan konsisten 2 (DEPLOYED) dan PrePhase1Worker sedang0, semua pekerja mendukung format tabel tunggal, dan Anda dapat pindah ke fase 2 dari penerapan migrasi tabel. Setelah StatusOrdinal mencapai 4 (LENGKAP), Anda dapat menghapus tabel lama dengan aman.

Pertimbangan rollback

Dukungan rollback tergantung pada saat ini: TableMigrationStatus

• Selama Fase 1 (TableMigrationStatussudah DEPLOYED atau belum disetel): Anda dapat memutar kembali ke versi sebelumnya dengan aman. Kode baru berjalan dalam mode yang kompatibel ke belakang dan tidak ada data yang ditulis ke entri non-sewa di tabel sewa.

• Selama Fase 2 (TableMigrationStatusadalah DEPLOYED atauPENDING): Anda dapat memutar kembali ke Fase 1. Pekerja kembali menggunakan tabel lama (format multi-tabel) untuk metrik pekerja dan status koordinator. Migrasi dibatalkan.

• Setelah status LENGKAP: Rollback tidak didukung. KCL hanya menggunakan tabel sewa untuk semua entitas. Bahkan jika kode berputar kembali ke Fase 1, pekerja terus menggunakan tabel sewa untuk semua entitas dan konfigurasi diabaikan.

Awas

Setelah migrasi mencapai status LENGKAP, aplikasi beroperasi secara eksklusif dalam mode tabel tunggal. migrateAllEntitiesToLeaseTableKonfigurasi diabaikan, dan KCL tidak kembali menggunakan tabel terpisah. Pastikan waktu memanggang sebelum pindah ke COMPLETE sudah cukup, karena setelah itu bahkan rollback kode tidak beralih kembali ke beberapa tabel.

Praktik terbaik

Ikuti praktik terbaik ini saat Anda mengadopsi format tabel tunggal:

• Setelah penerapan Fase 1, verifikasi bahwa entri status koordinator TableMigration3.5 mencapai DEPLOYED status. Pastikan tidak ada regresi sebelum melanjutkan ke Fase 2.

• Pantau entri status TableMigration3.5 koordinator untuk melacak kemajuan melalui status DEPLOYED, PENDING, dan COMPLETE. TableMigrationStatus Status disimpan dalam tabel status koordinator sebagai entri terpisah (bukan dalam tabel sewa) sampai migrasi mencapai LENGKAP.

• Pastikan waktu memanggang sebelum pindah ke COMPLETE sudah cukup, karena setelah itu bahkan rollback kode tidak beralih kembali ke beberapa tabel. Aplikasi hanya berfungsi dalam mode tabel tunggal.

• Setelah migrasi mencapai LENGKAP, hapus metrik pekerja lama dan tabel status koordinator secara manual. KCL tidak menghapus tabel ini secara otomatis—hanya berhenti menggunakannya.

• Jika Anda telah mengonfigurasi CoordinatorConfig.coordinatorStateTableConfig atauLeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig, Anda dapat menghapus konfigurasi ini setelah migrasi selesai. Konfigurasi ini tidak digunakan lagi di KCL 3.5 dan yang lebih baru.