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

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

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

Controlla 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 sostitutivi per la configurazione di un repository Docker personalizzato o di una chiave di crittografia gestita dal cliente (chiave KMS). Se l'estensione configura uno di questi parametri, consulta la soluzione alternativa nelle domande frequenti.

Prima di iniziare

Devi configurare l'interfaccia a riga di comando Firebase e inizializzare un progetto Firebase. Quando utilizzi l'interfaccia a riga di comando, assicurati di utilizzare la versione >= 15.32.0 di firebase-tools, che contiene i nuovi comandi del kit di migrazione e delle funzioni.

Autorizzazioni e ruoli dell'account richiesti

A seconda di ciò che deve essere creato e configurato dall'interfaccia a riga di comando Firebase durante la migrazione, l'account che utilizzi per l'autenticazione con Firebase e Google Cloud deve avere i 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 che abbia già installato estensioni ed eseguito il deployment di funzioni, poiché la maggior parte di queste autorizzazioni sarà già stata concessa. Se l'account di cui stai eseguendo la migrazione richiede più ruoli, segui le istruzioni IAM di 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 eseguito l'upgrade, potrebbero esserci modifiche significative che provocano un errore tra l'istanza dell'estensione e il kit sostitutivo. La configurazione esportata potrebbe non corrispondere a quella prevista dal kit a causa di modifiche ai parametri tra le versioni.

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

  • Dalla consoleFirebase
  • Dall'interfaccia a riga di comando Firebase utilizzando:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Se salti questo passaggio, l'interfaccia a riga di comando ti chiederà di eseguire l'upgrade durante l'esportazione della configurazione se l'estensione non è aggiornata all'ultima versione.

Crea un fork dell'estensione in un kit di funzioni locale

Prima di iniziare a convertire un'estensione in un kit di funzioni locali, 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 root del progetto Firebase e copia la cartella functions/ e il file extension.yaml dell'estensione al suo interno:

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 per i 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 locali, l'interfaccia a riga di comando Firebase non genera un file index.ts per configurare il pacchetto e impostarlo in modo che utilizzi i parametri di sistema di cui è stata eseguita la migrazione. 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.

In particolare, nel file index.ts di primo livello che esporta le tue funzioni, definisci un parametro per FUNCTION_DEFAULT_REGION e chiama setGlobalOptions con variabili di ambiente nel formato EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>, in modo simile al modello index-kit-migration.ts utilizzato dall'interfaccia a riga di comando:

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";

Testa 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 della tua estensione. Il passaggio successivo consiste nel verificare e correggere eventuali problemi introdotti accidentalmente lungo il percorso prima di eseguire la migrazione delle istanze dell'estensione di produzione.

Innanzitutto, aggiungi il fork come kit locale, configuralo ed eseguine il deployment in un progetto di test. I kit di funzioni locali devono trovarsi all'interno del progetto Firebase, quindi se il repository delle estensioni clonato si trova all'esterno del progetto Firebase, spostalo all'interno della directory del progetto. Poi 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 con fork, 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 l'estensione, esegui questo comando:

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

Esempio pratico: 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 qualsiasi valore.

  3. Nella pagina BigQuery della console Google Cloud, esegui una query sulla tabella del log delle modifiche non elaborato. Dovrebbe contenere una singola riga che registra la creazione del documento:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Esegui una query sulla vista più recente, che dovrebbe restituire l'evento di modifica più recente 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 un evento DELETE viene aggiunto alla tabella del log delle modifiche non elaborato.

    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 distribuito come kit-<kit-instance-id>-fsexportbigquery, non come ext-<instanceId>-fsexportbigquery. Cerca questo nome nella dashboard e nei log di Cloud Functions.
  • Il tuo 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 il test delle unità del tuo 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 nuova esecuzione riconcilia il set di dati, la tabella e le visualizzazioni.
  • I valori dei parametri provengono da .env anziché dal modulo di installazione, pertanto le esecuzioni ripetute di firebase deploy non sono interattive una volta completato .env.

(Facoltativo) Esegui la pulizia dopo i test

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

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

In questo modo vengono eliminate tutte le risorse cloud create eseguendo 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 di produzione, puoi scegliere di nuovo un ID kit.

Esegui 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 locali, 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 a quella dell'estensione che sta sostituendo. Puoi esportare la configurazione dell'istanza dell'estensione in un file .env, che memorizza i dati di configurazione dei parametri, delle variabili di ambiente e dei 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 archiviate 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 codebase separata per organizzare le funzioni. Puoi scegliere di eseguire il deployment di tutte le funzioni o solo di un'istanza del kit specifica. Durante la migrazione di una singola istanza di estensione, esegui il deployment solo di quell'istanza del kit.

Se il kit utilizza nuovi parametri che non erano presenti nell'istanza dell'estensione da cui hai eseguito la migrazione, l'interfaccia a riga di comando Firebase li richiede all'inizio del processo 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 di trigger di eventi utilizzata dal kit. Nell'ambito di questa migrazione, i kit aggiornati utilizzano funzioni di 2ª gen. dove in precedenza le estensioni utilizzavano 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, l'interfaccia a riga di comando ti chiederà di eseguire il deployment successivo.

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'operazione 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ù utilizzate, come Stream Cloud Firestore to BigQuery, utilizzano gli 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.
  • È stata inserita un'attività 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 dei log alla console Google Cloud per verificare che non ci siano 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 attivarlo nuovamente eseguendo:

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

Se stai eseguendo il deployment di un'istanza del kit di funzioni 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 Disinstalla l'estensione.

Dopo aver verificato che il deployment iniziale del kit di funzioni è stato completato correttamente, devi convalidare che la funzionalità del kit funzioni effettivamente come previsto. Poiché l'estensione stessa è ancora in esecuzione, devi assicurarti che ciò che stai controllando non sia solo che una delle due abbia funzionato, poiché l'estensione è stata e continuerà a funzionare.

Se l'elaborazione non viene modificata e non vedi risultati duplicati dall'estensione e dal kit, l'opzione migliore è esaminare direttamente i log del kit dopo aver attivato la funzionalità del kit.

Esempio elaborato: esegui lo streaming da Cloud Firestore a BigQuery

Con l'estensione Stream da Cloud Firestore a BigQuery, le scritture sia nella tabella Raw Changelog (*_raw_changelog) sia nella tabella della visualizzazione più recente (*_raw_latest) verranno deduplicate se lo stesso evento viene inviato al kit e all'estensione. Pertanto, non puoi utilizzare la presenza di righe o righe duplicate in BigQuery per verificare che il kit funzioni.

Puoi visualizzare i log delle funzioni poco dopo aver scritto nella raccolta Firestore utilizzando firebase functions:logs e cercare una voce di log che indichi che la scrittura è stata elaborata correttamente. Per questo kit con l'ID istanza predefinito di firestore-bigquery-export, l'aspetto sarà il seguente:

2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2

Se hai molti log, puoi filtrarli in base a una funzione specifica del kit utilizzando il seguente comando:

firebase functions:log --only <function name>

Per trovare i nomi delle funzioni specifiche per un'istanza del kit, puoi utilizzare il seguente comando:

firebase functions:list | grep kit-<kit instance id>

Per questo esempio:

firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery  │ v2      │ google.cloud.firestore.document.v1.written                    │
│ kit-firestore-bigquery-export-initBigQuerySync  │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-syncBigQuery      │ v2      │ taskQueue                                                     │

4. Disinstalla l'estensione

Dopo aver verificato il kit di funzioni di cui hai eseguito il deployment, puoi disinstallare l'estensione in modo da non duplicarne il comportamento una volta per il kit e una volta per l'estensione. Puoi disinstallare tutte le estensioni dall'interfaccia a riga di comando 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 Cloud Firestore documents 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 di Function Kit in un'unica codebase quando lavori con l'interfaccia a riga di comando Firebase e hai eseguito 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 di estensione con un'istanza del kit di funzioni di firestore-bigquery-export di cui è stato eseguito il deployment in più progetti, in cui ogni progetto ha la propria configurazione. La directory di configurazione dell'istanza dovrebbe essere simile alla seguente:

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

Ogni deployment in testing e production crea un'istanza del tuo kit con la configurazione corrispondente. I comandi CLI esistenti creano questa configurazione, a condizione che tu passi 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 un'unica istanza del kit configurata per il deployment nei tuoi 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.