Memigrasikan Firebase Extensions ke kit fungsi

Panduan ini menunjukkan cara memigrasikan ekstensi dari lingkungan Firebase Extensions yang tidak digunakan lagi ke kit fungsi yang dapat Anda instal dan deploy di Cloud Functions Anda sendiri untuk codebase Firebase (generasi ke-2).

Firebase Extensions mengelola semua aspek pembuatan, pembaruan, dan penghapusan ekstensi. Kit fungsi mengemas kemampuan ekstensi sebagai Cloud Functions for Firebase generasi ke-2 yang umum. Karena kit fungsi adalah Cloud Functions standar, Anda membuat, mengupdate, menghapus, dan memecahkan masalahnya menggunakan Firebase CLI dalam project Firebase Anda. Panduan ini mempersiapkan Anda untuk mengelola fungsi sekarang dan menerapkan update saat tersedia.

Di seluruh panduan ini, ekstensi Stream Cloud Firestore ke BigQuery (firestore-bigquery-export) digunakan sebagai contoh yang menunjukkan perintah dan output perintah untuk setiap langkah migrasi.

Menentukan jalur migrasi Anda

Firebase mendorong semua penayang Firebase Extensions untuk membuat pengganti ekstensi mereka sebagai kit fungsi yang dipublikasikan di npm. Anda dapat memeriksa apakah penggantian kit fungsi tersedia untuk ekstensi Anda dengan beberapa cara:

  • Buka halaman Ekstensi di konsol Firebase untuk project Anda. Setiap ekstensi yang telah Anda instal menunjukkan apakah penggantian kit fungsi tersedia.

  • Jalankan firebase ext:list di dalam project Firebase Anda di terminal untuk menunjukkan ekstensi terinstal Anda yang memiliki pengganti resmi:

    firebase ext:list --project my-project

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
✔  extensions: required API firebaseextensions.googleapis.com is enabled
i  extensions: list of extensions installed in my-project:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.2   │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/storage-resize-images     │ firebase  │ storage-resize-images          │ ACTIVE │ 0.3.6   │ 2026-06-03 17:41:24 │                                                   │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

Jika penggantian kit fungsi resmi tersedia untuk ekstensi Anda, Anda dapat memigrasikannya menggunakan bagian Bermigrasi ke kit fungsi di npm.

Jika tidak dapat menemukan pengganti yang dipublikasikan, Anda dapat membuat cabang kode ekstensi dan membuat pengganti Anda sendiri karena semua ekstensi bersifat open source. Untuk melakukannya, ikuti panduan Bermigrasi ke kit fungsi buatan sendiri.

Pilih jalur migrasi: Bermigrasi ke kit fungsi di npm Bermigrasi ke kit fungsi yang dibuat sendiri

Bermigrasi ke kit fungsi di npm

Memeriksa batasan migrasi yang diketahui

Sebelum Anda mulai memigrasikan instance ekstensi, periksa apakah penyiapan Anda menggunakan salah satu fitur berikut yang memerlukan solusi atau belum didukung di kit fungsi:

  • Repositori Docker kustom dan kunci KMS memerlukan solusi manual Cloud Functions for Firebase tidak mendukung parameter sistem pengganti untuk mengonfigurasi repositori Docker kustom atau Kunci Enkripsi yang Dikelola Pelanggan (kunci KMS). Jika ekstensi Anda mengonfigurasi salah satu parameter ini, lihat solusi alternatif FAQ.

Sebelum memulai

Anda perlu menyiapkan Firebase CLI dan melakukan inisialisasi project Firebase. Saat menggunakan CLI, pastikan Anda menggunakan firebase-tools versi >= 15.32.0, yang memiliki perintah migrasi dan kit fungsi baru.

Izin dan peran akun yang diperlukan

Bergantung pada apa yang perlu dibuat dan dikonfigurasi oleh Firebase CLI selama migrasi, akun yang Anda gunakan untuk melakukan autentikasi dengan Firebase dan Google Cloud harus memiliki peran berikut:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (jika Anda perlu melakukan setIamPermissions untuk endpoint publik)
  • roles/secretmanager.admin (jika menggunakan secret)
  • roles/serviceusage.serviceUsageAdmin (jika Anda perlu mengaktifkan API baru)

Sebaiknya gunakan akun yang telah menginstal ekstensi dan men-deploy fungsi sebelumnya, karena sebagian besar izin ini sudah diberikan. Jika akun yang Anda migrasikan memerlukan lebih banyak peran, ikuti petunjuk IAM Google Cloud untuk menambahkannya.

Memilih alur kerja CLI

Untuk bermigrasi dari instance ekstensi ke kit fungsi yang tersedia di npm, pilih salah satu opsi berikut:

  • (Direkomendasikan) Lakukan migrasi menggunakan perintah CLI ext:migrate. Perintah ini men-deploy penggantian kit fungsi Anda sebelum meng-uninstal ekstensi yang digantikannya.
  • Lakukan migrasi menggunakan perintah CLI kit fungsi. Anda dapat menggunakan perintah terpisah untuk mengupdate ekstensi, menginstal kit fungsi, mengonfigurasinya seperti ekstensi, men-deploy kit, dan meng-uninstal ekstensi. Hal ini memberikan fleksibilitas yang lebih besar untuk mengurutkan ulang perintah atau melakukan pekerjaan tambahan di antara langkah-langkah.

Bermigrasi menggunakan ext:migrate

Mulai migrasi sekali per instance ekstensi dengan menjalankan:

firebase ext:migrate --project <project-id>

Perintah ini akan memandu Anda:

  1. Memilih ekstensi yang akan dimigrasikan yang memiliki penggantian kit fungsi resmi yang tersedia.
  2. Memilih instance tertentu dari ekstensi tersebut.
  3. Mengupdate ekstensi ke versi terbarunya jika perlu.
  4. Menginstal kit fungsi, mengonfigurasi instance secara identik dengan cara instance ekstensi dikonfigurasi.
  5. Men-deploy kit fungsi.
  6. Memverifikasi bahwa kit fungsi berhasil di-deploy dan semua hook siklus proses, jika ada, berjalan.
  7. Meng-uninstal instance ekstensi.

Jika Anda mengetahui ekstensi atau instance ekstensi tertentu yang ingin dimigrasikan, tentukan menggunakan tanda command line berikut:

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

Jika Anda mengetahui paket tertentu yang ingin dimigrasikan, terutama jika paket tersebut bukan paket pengganti resmi yang tercantum oleh Google, tentukan paket tersebut menggunakan flag --package:

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

Memverifikasi deployment kit fungsi

Untuk memverifikasi bahwa firebase deploy kit tidak mengalami error, periksa log deployment untuk melihat apakah ada hook siklus proses yang dipicu. Ekstensi populer, seperti Stream Cloud Firestore ke BigQuery, menggunakan hook siklus proses. Berikut adalah contoh tampilan hook siklus proses saat dipicu:

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

Pesan log ini mengonfirmasi hal berikut:

  • Hook siklus proses ditemukan dan dieksekusi.
  • Tugas dimasukkan dalam antrean tugas yang terkait dengan hook siklus proses.
  • Link ke Cloud Logging telah diberikan sehingga Anda dapat memvalidasi bahwa tugas telah selesai tanpa error.

Ikuti link log ke konsol Google Cloud untuk memvalidasi bahwa tidak ada error dalam log dan peristiwa task queue Anda berhasil diproses. Jika peristiwa siklus proses tidak berhasil dieksekusi, Anda dapat memicunya kembali dengan menjalankan:

firebase functions:lifecycle:run <hook-name> <codebase>

Jika Anda men-deploy instance kit fungsi untuk pertama kalinya, jalankan:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Jika kapan saja selama validasi Anda memutuskan ingin menghentikan atau mengurungkan migrasi ini, Anda dapat meng-uninstal kit menggunakan petunjuk di Meng-uninstal ekstensi.

Meninjau README kit fungsi

Beberapa kit mungkin memerlukan pekerjaan tambahan di luar yang ditangani secara otomatis oleh kit fungsi. Tinjau README untuk kit yang Anda instal dan ikuti petunjuk tambahan.

Melakukan migrasi menggunakan CLI kit fungsi

Sebelum memulai, identifikasi dan catat ID instance ekstensi yang ingin Anda migrasikan ke kit dan nama paket npm kit penggantinya. Anda dapat menemukan keduanya menggunakan output firebase ext:list. Lihat Menentukan jalur migrasi Anda untuk contoh penggunaan ext:list.

1. Mengupgrade instance ekstensi Anda ke versi terbaru

Anda harus mengupdate ekstensi ke versi terbaru untuk meminimalkan perbedaan antara instance ekstensi dan kit penggantinya. Jika ekstensi Anda tidak diupgrade, mungkin ada perubahan signifikan yang dapat menyebabkan gangguan antara instance ekstensi Anda dan penggantian kit-nya. Konfigurasi yang diekspor mungkin tidak sesuai dengan yang diharapkan kit karena perubahan parameter di berbagai versi.

Gunakan salah satu opsi berikut untuk mengupdate ekstensi, bergantung pada tempat ekstensi diinstal:

  • Dari Firebase console
  • Dari Firebase CLI menggunakan:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Jika Anda melewati langkah ini, CLI akan meminta Anda mengupgrade saat mengekspor konfigurasi jika ekstensi Anda belum menggunakan versi terbaru.

2. Meninjau dan menginstal instance kit fungsi pengganti

Anda dapat menginstal kit fungsi menggunakan perintah CLI berikut:

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

Saat Anda memilih ID instance untuk kit selama penginstalan, pastikan untuk mencatatnya untuk digunakan nanti dalam petunjuk migrasi.

Setelah kit diinstal, direktori baru akan dibuat di dalam project Firebase dengan lokasi seperti function-kits/<kit-name>/source yang berisi paket npm dengan kit yang menggantikan ekstensi Anda dan file index.ts dasar yang mengekspor fungsi tersebut agar Firebase dapat men-deploy dan menetapkan konfigurasi kustom.

Tinjau README untuk kit dan ikuti petunjuk tambahan yang tercantum di sana.

Jika memiliki beberapa instance kit dalam project yang sama, Anda dapat mengulangi perintah ini untuk membuat instance baru dari kit yang sama. Anda juga dapat men-deploy satu instance kit ke dua project Firebase yang berbeda dengan konfigurasi yang berbeda (misalnya, project staging dan project produksi). Untuk mempelajari lebih lanjut penyiapan lanjutan ini, lihat Migrasi lanjutan.

Contoh soal:

firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project

3. Konfigurasi instance kit fungsi secara identik dengan ekstensi

Anda harus menyesuaikan instance kit ini dengan konfigurasi yang identik dengan ekstensi yang digantikannya. Anda dapat mengekspor konfigurasi instance ekstensi ke dalam file .env, yang menyimpan data konfigurasi parameter, variabel lingkungan, dan referensi rahasia untuk semua Cloud Functions, termasuk kit. Untuk mengekspornya langsung ke file konfigurasi kit Anda, jalankan:

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

Di akhir langkah ini, informasi konfigurasi untuk instance ini disimpan dalam file .env khusus project di direktori konfigurasi instance Anda, seperti: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

4. Men-deploy dan memverifikasi penggantian kit

Setelah kit diinstal dan tersedia sebagai serangkaian fungsi, Anda dapat men-deploy penggantian kit. Kit fungsi berfungsi seperti fungsi standar, dengan setiap instance kit bertindak sebagai codebase terpisah untuk mengatur fungsi Anda. Anda dapat memilih untuk men-deploy semua fungsi atau hanya instance kit tertentu. Saat memigrasikan satu instance ekstensi, deploy hanya instance kit tersebut.

Jika kit Anda menggunakan parameter baru yang tidak ada di instance ekstensi yang Anda migrasikan, CLI Firebase akan meminta Anda untuk memasukkannya di awal proses deployment. Hal ini tidak diharapkan dalam contoh yang sudah dikerjakan ini dari ekstensi firestore-bigquery-export yang terbaru, tetapi banyak kit meminta parameter baru untuk setiap sumber pemicu peristiwa yang digunakan oleh kit. Sebagai bagian dari migrasi ini, kit yang diupdate menggunakan fungsi generasi ke-2, sedangkan sebelumnya ekstensi menggunakan fungsi generasi ke-1. Di generasi ke-2, fungsi terletak di dekat sumber peristiwanya dan ditambahkan sebagai parameter tambahan. Pada update mendatang, jika parameter baru ditambahkan, CLI akan meminta Anda untuk melakukan deployment berikutnya.

Contoh soal:

firebase deploy --only functions:firestore-bigquery-export --project my-project

Output:

=== Deploying to 'my-project'...
i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔  Deploy complete!

Untuk memverifikasi bahwa firebase deploy kit tidak mengalami error, periksa log deployment untuk melihat apakah ada hook siklus proses yang dipicu. Ekstensi populer, seperti Stream Cloud Firestore ke BigQuery, menggunakan hook siklus proses. Berikut adalah contoh tampilan hook siklus proses saat dipicu:

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

Pesan log ini mengonfirmasi hal berikut:

  • Hook siklus proses ditemukan dan dieksekusi.
  • Tugas dimasukkan dalam antrean tugas yang terkait dengan hook siklus proses.
  • Link ke Cloud Logging telah diberikan sehingga Anda dapat memvalidasi bahwa tugas telah selesai tanpa error.

Ikuti link log ke konsol Google Cloud untuk memvalidasi bahwa tidak ada error dalam log dan peristiwa task queue Anda berhasil diproses. Jika peristiwa siklus proses tidak berhasil dieksekusi, Anda dapat memicunya kembali dengan menjalankan:

firebase functions:lifecycle:run <hook-name> <codebase>

Jika Anda men-deploy instance kit fungsi untuk pertama kalinya, jalankan:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Jika kapan saja selama validasi Anda memutuskan ingin menghentikan atau mengurungkan migrasi ini, Anda dapat meng-uninstal kit menggunakan petunjuk di Meng-uninstal ekstensi.

5. Meng-uninstal ekstensi

Setelah memverifikasi kit fungsi yang di-deploy, Anda dapat meng-uninstal ekstensi agar tidak menduplikasi perilakunya sekali untuk kit dan sekali untuk ekstensi. Anda dapat meng-uninstal semua ekstensi dari CLI Firebase terlepas dari cara Anda menginstalnya jika Anda meneruskan flag --immediate:

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

Contoh penggunaan:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

Output:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

Migrasi lanjutan

Anda dapat memiliki ekstensi di beberapa project Firebase yang ingin Anda kelola dengan satu codebase. Misalnya, jika Anda men-deploy infrastruktur yang sama ke lingkungan testing dan lingkungan production, yang masing-masing memiliki instance documents Cloud Firestore yang Anda ekspor ke BigQuery, Anda mungkin menginstal dua instance ekstensi firestore-bigquery-export:

  • export-documents-testing
  • export-documents-production

Jika Anda memigrasikan kedua instance ekstensi ini ke dua instance kit fungsi dalam satu codebase saat bekerja dengan Firebase CLI dan men-deploy menggunakan firebase deploy --project testing dan firebase deploy --project production, setiap deployment akan membuat dua instance di lingkungan testing dan production.

Sebagai gantinya, ganti dua instance ekstensi dengan satu instance kit fungsi firestore-bigquery-export yang di-deploy ke beberapa project, dengan setiap project memiliki konfigurasinya sendiri. Direktori konfigurasi untuk instance Anda akan terlihat seperti berikut:

  • config-export-documents/
    • .env.testing
    • .env.production

Setiap deployment ke testing dan production akan membuat satu instance kit Anda dengan konfigurasi yang sesuai. Perintah CLI yang ada akan membuat penyiapan ini selama Anda meneruskan flag --project di setiap pemanggilan ext:migrate atau functions:kits:install.

Contoh penggunaan:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

Sekarang Anda memiliki satu instance kit yang dikonfigurasi untuk di-deploy ke project testing dan production dengan konfigurasi masing-masing. Jika Anda membuat instance di project testing dan menjalankan perintah functions:kits:install untuk paket yang sama di project production, Anda akan diminta untuk menggunakan kembali instance yang dikonfigurasi untuk testing atau menginstal instance kedua.