Memigrasikan Firebase Extensions ke kit fungsi yang dibuat sendiri

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

Jika penayang belum membuat kit pengganti resmi yang didistribusikan di npm, panduan ini akan memandu Anda melakukan langkah-langkah untuk membuat fork ekstensi mereka dan menyiapkannya sebagai kit fungsi lokal.

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.

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.

Membuat fork ekstensi ke kit fungsi lokal

Sebelum Anda mulai mengonversi ekstensi ke kit fungsi lokal, pastikan kode sumber ekstensi berada di dalam project Firebase Anda. Untuk melakukannya, clone repositori ekstensi dari GitHub, buat direktori di dalam root project Firebase, lalu salin folder functions/ dan extension.yaml ekstensi ke dalamnya:

mkdir -p path/to/kit
cp -r /path/to/extension-source/functions/* path/to/kit/
cp /path/to/extension-source/extension.yaml path/to/kit/.

Ikuti Langkah 1 hingga 8 dari panduan migrasi penayang untuk memigrasikan kode sumber ekstensi Anda ke fungsi generasi ke-2. Kemudian, lanjutkan dengan langkah-langkah berikut.

Membuat kit lokal Anda mendukung region fungsi yang diekspor dan parameter lanjutan

Di kit fungsi lokal, CLI Firebase tidak membuat file index.ts untuk menyiapkan paket dan mengonfigurasinya agar menggunakan parameter sistem yang dimigrasikan. Untuk menggunakan region fungsi dan parameter lanjutan yang dikonfigurasi untuk ekstensi Anda, siapkan file index.ts untuk membaca format yang diekspor oleh firebase ext:export --mode functions ke dalam file variabel lingkungan.

Secara khusus, dalam file index.ts tingkat teratas yang mengekspor fungsi Anda, tentukan parameter untuk FUNCTION_DEFAULT_REGION dan panggil setGlobalOptions dengan variabel lingkungan dalam bentuk EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>, mirip dengan template index-kit-migration.ts yang digunakan oleh CLI:

import { setGlobalOptions } from "firebase-functions";
import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options";
import { defineString } from "firebase-functions/params";

export const regionParam = defineString("FUNCTION_DEFAULT_REGION", {
  input: { text: { nonEmpty: true } },
  description: "Global default region where functions should be deployed. Can be overridden per-function.",
});

setGlobalOptions({
  region: regionParam,
  memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined,
  timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS
    ? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS)
    : undefined,
  vpcConnectorEgressSettings:
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS &&
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED"
      ? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting)
      : undefined,
  vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined,
  maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES)
    : undefined,
  minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES)
    : undefined,
  ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined,
  // Parses a comma-separated string of key:value pairs into a key-value object
  // (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }).
  labels: process.env.EXT_MIGRATED_SYSTEM_LABELS
    ? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce<Record<string, string> | undefined>(
        (acc, curr) => {
          const [key, value] = curr.split(":");
          const trimmedKey = key?.trim();
          const trimmedValue = value?.trim();
          if (!trimmedKey || !trimmedValue) {
            return acc;
          }
          acc = acc ?? {};
          acc[trimmedKey] = trimmedValue;
          return acc;
        },
        undefined,
      )
    : undefined,
});

// Re-export all functions so the Firebase CLI can deploy them
export * from "./your-functions";

Menguji kit sebelum migrasi

Sekarang Anda memiliki kit fungsi lokal yang, saat di-deploy, berperilaku sama dengan penginstalan baru ekstensi Anda. Langkah berikutnya adalah memverifikasi dan memperbaiki masalah yang tidak sengaja muncul selama proses sebelum memigrasikan instance ekstensi produksi Anda ke versi tersebut.

Pertama, tambahkan fork Anda sebagai kit lokal, konfigurasikan, dan deploy ke project pengujian. Kit fungsi lokal harus berada di dalam project Firebase Anda, jadi jika repositori ekstensi yang di-clone berada di luar project Firebase Anda, pindahkan ke dalam direktori project. Kemudian, jalankan perintah penginstalan kit berikut untuk menginstalnya sebagai kit lokal:

firebase functions:kits:install --directory <path-to-your-fork> --project <test-project-id>

Perintah ini akan memandu Anda memilih ID kit, ID instance, dan konfigurasi untuk instance pengujian pertama Anda. Kemudian, perintah ini akan mengubah file firebase.json Anda untuk mendaftarkan kit lokal yang mengarah ke direktori yang di-fork, dengan konfigurasi untuk setiap instance yang disimpan dalam file .env di function-kits/<kit-id>/config-<instance-id>.

Deploy kit lokal Anda ke project pengujian dengan resource yang sesuai untuk menguji perilakunya. Jika Anda sudah menyiapkan project pengujian dari pengujian ekstensi, jalankan perintah berikut:

firebase deploy --only functions:<kit-instance-id> --project <test-project-id>

Contoh penggunaan: Streaming Cloud Firestore ke BigQuery (firestore-bigquery-export)

Verifikasi sinkronisasi Cloud Firestore ke BigQuery end-to-end:

  1. Di halaman Cloud Firestore pada konsol Firebase, buat koleksi yang Anda tetapkan sebagai COLLECTION_PATH (users) jika belum ada.
  2. Buat dokumen bernama bigquery-mirror-test yang berisi kolom apa pun dengan nilai apa pun.

  3. Di halaman BigQuery pada konsol Google Cloud, kueri tabel log perubahan mentah. Tabel ini harus berisi satu baris yang mencatat pembuatan dokumen:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Kueri tampilan terbaru, yang akan menampilkan peristiwa perubahan terbaru untuk satu-satunya dokumen yang ada (bigquery-mirror-test):

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Hapus dokumen bigquery-mirror-test di Cloud Firestore. Perubahan ini akan hilang dari tampilan terbaru, dan peristiwa DELETE ditambahkan ke tabel log perubahan mentah.

    Anda dapat memeriksa histori lengkap satu dokumen dengan:

    SELECT *
   FROM `PROJECT_ID.analytics.users_raw_changelog`
   WHERE document_name = "bigquery-mirror-test"
   ORDER BY timestamp ASC

Perbedaan dari pengujian ekstensi:

  • Pemicu di-deploy sebagai kit-<kit-instance-id>-fsexportbigquery, bukan ext-<instanceId>-fsexportbigquery. Cari nama tersebut di dasbor dan log Cloud Functions.
  • Kode Anda berjalan di Firebase Local Emulator Suite sebagai fungsi standar. Anda dapat menetapkan nilai parameter untuk digunakan di emulator dengan .env.local. Anda juga dapat melakukan pengujian unit pada kode menggunakan SDK firebase-functions-test seperti yang dijelaskan dalam Pengujian unit Cloud Functions.
  • Penyediaan tidak lagi didorong oleh runtime Ekstensi. Jika tabel log perubahan tidak ada setelah deployment, jalankan ulang tugas penyiapan secara manual: firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>. Tugas ini bersifat idempoten, sehingga menjalankan ulang tugas ini akan merekonsiliasi set data, tabel, dan tampilan.
  • Nilai parameter berasal dari .env, bukan formulir penginstalan, sehingga firebase deploy yang dijalankan ulang tidak interaktif setelah .env selesai.

(Opsional) Membersihkan dari pengujian

Jika Anda ingin menghapus instance pengujian ini setelah pengujian, uninstal:

firebase functions:kits:uninstall --instance <kit-instance-id> --project <test-project-id>

Tindakan ini akan menghapus semua resource cloud yang dibuat dengan men-deploy kit dan menghapus konfigurasi instance-nya. Jika Anda hanya memiliki satu instance kit, tindakan ini juga akan menghapus entri kit dari firebase.json. Direktori kode sumber lokal Anda tidak akan dihapus. Saat menginstal kit untuk migrasi produksi, Anda dapat memilih ID kit lagi.

Bermigrasi dari ekstensi ke kit lokal Anda

Setelah kit lokal diuji, Anda dapat memigrasikan instance ekstensi yang di-deploy langsung.

1. Menginstal instance kit fungsi pengganti

Instal kit fungsi lokal Anda, teruskan --no-configure untuk melewati konfigurasi manual sehingga langkah berikutnya dapat mengekspor konfigurasi ekstensi yang ada langsung ke instance kit ini:

firebase functions:kits:install --no-configure --directory <path-to-your-fork> --project <project-id>

2. 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>

3. 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 penggunaan:

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 to 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.

4. 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 CLI Firebase 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 soal:

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.