Esegui la migrazione delle Firebase Extensions a un kit di funzioni creato autonomamente

Seleziona il percorso di migrazione: Eseguire la migrazione ai kit di funzioni su npm Eseguire la migrazione al kit di funzioni creato autonomamente

Se un publisher non ha creato un kit di sostituzione ufficiale distribuito su npm, questa guida ti illustra i passaggi per eseguire il fork della sua estensione e configurarla come kit di funzioni locale.

Controllare le limitazioni note della migrazione

Prima di iniziare la migrazione di un'istanza di estensione, verifica se la tua configurazione utilizza una delle seguenti funzionalità che richiedono una soluzione alternativa o non sono ancora supportate nei kit di funzioni:

  • I repository Docker personalizzati e le chiavi KMS richiedono una soluzione alternativa manuale Cloud Functions for Firebase non supporta i parametri di sistema di sostituzione per configurare un repository Docker personalizzato o una chiave di crittografia gestita dal cliente (chiave KMS). Se la tua estensione configura uno di questi parametri, consulta la soluzione alternativa riportata nelle domande frequenti.

Prima di iniziare

Devi configurare la CLI Firebase e inizializzare un progetto Firebase. Quando utilizzi la CLI, assicurati di utilizzare la versione firebase-tools >= 15.32.0, che include i nuovi comandi di migrazione e del kit di funzioni.

Ruoli e autorizzazioni dell'account richiesti

A seconda di ciò che deve essere creato e configurato dalla CLI Firebase durante la migrazione, l'account che utilizzi per l'autenticazione con Firebase e Google Cloud deve disporre dei seguenti ruoli:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (se devi eseguire setIamPermissions per gli endpoint pubblici)
  • roles/secretmanager.admin (se utilizzi i secret)
  • roles/serviceusage.serviceUsageAdmin (se devi abilitare nuove API)

Ti consigliamo di utilizzare un account in cui sono state installate estensioni e sono state implementate funzioni in precedenza, poiché la maggior parte di queste autorizzazioni sarà già stata concessa. Se l'account di migrazione ha bisogno di altri ruoli, segui le istruzioni IAM Google Cloud per aggiungerli.

Esegui l'upgrade dell'istanza dell'estensione all'ultima versione

Devi aggiornare l'estensione all'ultima versione per ridurre al minimo la differenza tra l'istanza dell'estensione e il relativo kit di sostituzione. Se l'estensione non viene aggiornata, potrebbero esserci modifiche significative e incompatibili tra l'istanza dell'estensione e la sostituzione del kit. La configurazione esportata potrebbe non corrispondere a quella prevista dal kit a causa delle modifiche dei parametri nelle varie versioni.

Utilizza una delle seguenti opzioni per aggiornare l'estensione, a seconda di dove è stata installata:

  • Dalla console Firebase
  • Da Firebase CLI utilizzando:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Se salti questo passaggio, la CLI ti chiede di eseguire l'upgrade durante l'esportazione della configurazione se l'estensione non è nell'ultima versione.

Esegui il fork dell'estensione in un kit di funzioni locale

Prima di iniziare a convertire un'estensione in un kit di funzioni locale, assicurati che il codice sorgente dell'estensione si trovi all'interno del tuo progetto Firebase. Per farlo, clona il repository dell'estensione da GitHub, crea una directory all'interno della directory principale del progetto Firebase e copia la cartella functions/ e il file extension.yaml dell'estensione:

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

Segui i passaggi da 1 a 8 della guida alla migrazione dei publisher per eseguire la migrazione del codice sorgente dell'estensione a una funzione di 2ª gen. Poi continua con i seguenti passaggi.

Fai in modo che il tuo kit locale supporti la regione della funzione esportata e i parametri avanzati

In un kit di funzioni locale, la CLI Firebase non genera un file index.ts per configurare il pacchetto e configurarlo in modo che utilizzi i parametri di sistema migrati. Per utilizzare la regione della funzione e i parametri avanzati configurati per l'estensione, configura il file index.ts in modo che legga il formato esportato da firebase ext:export --mode functions in un file di variabili di ambiente.

Nello specifico, nel file index.ts di primo livello che esporta le funzioni, definisci un parametro per FUNCTION_DEFAULT_REGION e chiama setGlobalOptions con variabili di ambiente del modulo EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>, in modo simile al modello index-kit-migration.ts utilizzato dalla 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";

Testare il kit prima della migrazione

Ora hai un kit di funzioni locale che, una volta eseguito il deployment, si comporta in modo identico a una nuova installazione dell'estensione. Il passaggio successivo consiste nel verificare e correggere eventuali problemi introdotti accidentalmente durante il processo prima di eseguire la migrazione delle istanze di estensione di produzione.

Per prima cosa, aggiungi il fork come kit locale, configuralo e implementalo in un progetto di test. I kit di funzioni locali devono trovarsi all'interno del progetto Firebase, quindi se il repository dell'estensione clonato si trova all'esterno del progetto Firebase, spostalo all'interno della directory del progetto. Quindi, esegui il seguente comando di installazione del kit per installarlo come kit locale:

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

Questo comando ti guida nella scelta di un ID kit, un ID istanza e una configurazione per la tua prima istanza di test. Quindi, modifica il file firebase.json per registrare un kit locale che punta alla directory forked, con le configurazioni per ogni istanza archiviate in un file .env in function-kits/<kit-id>/config-<instance-id>.

Esegui il deployment del kit locale in un progetto di test con le risorse appropriate per testarne il comportamento. Se hai già configurato un progetto di test per testare la tua estensione, esegui il seguente comando:

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

Esempio svolto: trasmetti in streaming Cloud Firestore su BigQuery (firestore-bigquery-export)

Verifica la sincronizzazione end-to-end da Cloud Firestore a BigQuery:

  1. Nella pagina Cloud Firestore della console Firebase, crea la raccolta che hai impostato come COLLECTION_PATH (users) se non esiste già.
  2. Crea un documento denominato bigquery-mirror-test contenente campi con valori.

  3. Nella pagina BigQuery della console Google Cloud, esegui una query sulla tabella raw_changelog. Deve contenere una singola riga che registra la creazione del documento:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Esegui una query sulla visualizzazione più recente, che dovrebbe restituire l'ultimo evento di modifica per l'unico documento presente (bigquery-mirror-test):

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Elimina il documento bigquery-mirror-test in Cloud Firestore. Scompare dalla visualizzazione più recente e alla tabella del changelog non elaborato viene aggiunto un evento DELETE.

    Puoi esaminare la cronologia completa di un singolo documento con:

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

Differenze rispetto al test dell'estensione:

  • Il trigger viene implementato come kit-<kit-instance-id>-fsexportbigquery, non ext-<instanceId>-fsexportbigquery. Cerca questo nome nel dashboard e nei log Cloud Functions.
  • Il codice viene eseguito in Firebase Local Emulator Suite come funzioni standard. Puoi impostare i valori dei parametri da utilizzare nell'emulatore con .env.local. Puoi anche eseguire test delle unità del codice utilizzando l'SDK firebase-functions-test, come descritto in Test delle unità di Cloud Functions.
  • Il provisioning non è più gestito dal runtime delle estensioni. Se la tabella del log delle modifiche non è presente dopo il deployment, esegui nuovamente l'attività di configurazione manualmente: firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>. L'attività è idempotente, quindi la sua esecuzione riconcilia il set di dati, la tabella e le viste.
  • I valori dei parametri provengono da .env anziché dal modulo di installazione, pertanto le nuove esecuzioni di firebase deploy non sono interattive una volta completata l'esecuzione di .env.

(Facoltativo) Liberare spazio dopo il test

Se vuoi rimuovere questa istanza di test dopo il test, disinstallala:

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

Vengono eliminate tutte le risorse cloud create con il deployment del kit e viene rimossa la configurazione dell'istanza. Se hai una sola istanza del kit, questa operazione rimuove anche la voce del kit da firebase.json. Non elimina la directory del codice sorgente locale. Quando installi il kit per la migrazione della produzione, puoi scegliere di nuovo un ID kit.

Eseguire la migrazione dalle estensioni al kit locale

Ora che il kit locale è stato testato, puoi eseguire la migrazione dell'istanza dell'estensione di cui è stato eseguito il deployment.

1. Installa l'istanza del kit di funzioni sostitutivo

Installa il kit di funzioni locale, passando --no-configure per saltare la configurazione manuale in modo che il passaggio successivo possa esportare la configurazione dell'estensione esistente direttamente in questa istanza del kit:

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

2. Configura l'istanza del kit di funzioni in modo identico all'estensione

Devi personalizzare questa istanza del kit con una configurazione identica all'estensione che sta sostituendo. Puoi esportare la configurazione dell'istanza dell'estensione in un file .env, che memorizza i dati di configurazione di parametri, variabili di ambiente e riferimenti ai secret per tutti i Cloud Functions, inclusi i kit. Per esportarlo direttamente nel file di configurazione del kit, esegui:

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

Al termine di questo passaggio, le informazioni di configurazione per questa istanza vengono memorizzate in un file .env specifico del progetto nella directory di configurazione dell'istanza, ad esempio: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

3. Esegui il deployment e verifica la sostituzione del kit

Ora che il kit è installato e disponibile come insieme di funzioni, puoi eseguire il deployment della sostituzione del kit. I kit di funzioni funzionano come le funzioni standard, in cui ogni istanza del kit funge da base di codice separata per organizzare le funzioni. Puoi scegliere di eseguire il deployment di tutte le funzioni o solo di un'istanza specifica del kit. Durante la migrazione di una singola istanza di estensione, esegui il deployment solo di questa istanza del kit.

Se il tuo kit utilizza nuovi parametri non presenti nell'istanza dell'estensione da cui hai eseguito la migrazione, la CLI Firebase ti chiede di inserirli all'inizio della procedura di deployment. Questo non è previsto in questo esempio pratico di un'estensione firestore-bigquery-export aggiornata, ma molti kit richiedono un nuovo parametro per qualsiasi origine trigger evento utilizzata dal kit. Nell'ambito di questa migrazione, i kit aggiornati utilizzano le funzioni di 2ª gen. laddove le estensioni utilizzavano in precedenza le funzioni di 1ª gen. Nella 2ª gen., le funzioni si trovano vicino alle origini eventi e vengono aggiunte come parametro aggiuntivo. Negli aggiornamenti futuri, se vengono aggiunti nuovi parametri, la CLI ti chiederà di inserirli nella prossima implementazione.

Esempio elaborato:

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!

Per verificare che l'firebase deploy del kit non abbia generato errori, controlla i log di deployment per vedere se sono stati attivati hook del ciclo di vita. Le estensioni più diffuse, come Stream Cloud Firestore to BigQuery, utilizzano hook del ciclo di vita. Di seguito è riportato un esempio di come appare un hook del ciclo di vita quando viene attivato:

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

Questi messaggi di log confermano quanto segue:

  • È stato trovato ed eseguito un hook del ciclo di vita.
  • Un'attività è stata messa in coda nella coda di attività associata all'hook del ciclo di vita.
  • È stato fornito un link a Cloud Logging per consentirti di verificare che l'attività sia stata completata senza errori.

Segui il link ai log nella console Google Cloud per verificare che non siano presenti errori nei log e che l'evento della coda di attività sia stato elaborato correttamente. Se l'evento del ciclo di vita non è stato eseguito correttamente, puoi riattivarlo eseguendo:

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

Se stai eseguendo il deployment di un'istanza di Function Kit per la prima volta, esegui:

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

Se in qualsiasi momento durante la convalida decidi di interrompere o annullare questa migrazione, puoi disinstallare il kit seguendo le istruzioni riportate in Disinstallare l'estensione.

4. Disinstallare l'estensione

Dopo aver verificato il kit di funzioni di cui è stato eseguito il deployment, puoi disinstallare l'estensione in modo da non duplicare il suo comportamento una volta per il kit e una volta per l'estensione. Puoi disinstallare tutte le estensioni dalla CLI Firebase indipendentemente da come le hai installate se passi il flag --immediate:

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

Esempio elaborato:

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

Migrazioni avanzate

Puoi avere estensioni in più progetti Firebase che vuoi gestire con un unico codebase. Ad esempio, se esegui il deployment della stessa infrastruttura in un ambiente testing e in un ambiente production, ognuno dei quali ha un'istanza documents Cloud Firestore che esporti in BigQuery, potresti avere due istanze dell'estensione firestore-bigquery-export installate:

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

Se hai eseguito la migrazione di queste due istanze di estensione a due istanze del kit di funzioni in un unico codebase quando utilizzi la CLI Firebase ed esegui il deployment utilizzando firebase deploy --project testing e firebase deploy --project production, ogni deployment creerebbe due istanze negli ambienti testing e production.

Sostituisci invece le due istanze dell'estensione con un'istanza del kit di funzioni di firestore-bigquery-export di cui è stato eseguito il deployment in più progetti, dove ogni progetto ha una propria configurazione. La directory di configurazione per l'istanza dovrebbe essere simile alla seguente:

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

Ogni deployment in testing e production crea un'istanza del kit con la configurazione corrispondente. I comandi CLI esistenti creano questa configurazione a condizione che tu trasmetta il flag --project in ogni chiamata di ext:migrate o functions:kits:install.

Esempio elaborato:

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

Ora hai una singola istanza del kit configurata per il deployment nei progetti testing e production con le rispettive configurazioni. Se crei un'istanza nel progetto testing ed esegui il comando functions:kits:install per lo stesso pacchetto nel progetto production, ti viene chiesto se vuoi riutilizzare l'istanza configurata per testing o installare una seconda istanza.