Migra Extensiones de Firebase a un kit de funciones creado por ti

Selecciona la ruta de migración: Migra a kits de funciones en npm Migra a un kit de funciones creado por ti

Si un publicador no creó un kit de reemplazo oficial distribuido en npm, esta guía te indicará los pasos para bifurcar su extensión y configurarla como un kit de funciones local.

Verifica si hay limitaciones conocidas de la migración

Antes de comenzar a migrar una instancia de extensión, verifica si tu configuración usa alguna de las siguientes funciones que requieren una solución alternativa o que aún no se admiten en los kits de funciones:

  • Los repositorios de Docker personalizados y las claves de KMS requieren una solución alternativa manual Cloud Functions for Firebase no admite parámetros del sistema de reemplazo para configurar un repositorio de Docker personalizado o una clave de encriptación administrada por el cliente (clave de KMS). Si tu extensión configura alguno de estos parámetros, consulta la solución alternativa de las Preguntas frecuentes.

Antes de comenzar

Debes configurar la CLI de Firebase y, luego, inicializar un proyecto de Firebase. Cuando uses la CLI, asegúrate de usar la versión >= 15.32.0 de firebase-tools, que tiene los nuevos comandos de migración y del kit de funciones.

Roles y permisos de la cuenta obligatorios

Según lo que deba crear y configurar la CLI de Firebase durante la migración, la cuenta que uses para autenticarte con Firebase y Google Cloud debe tener los siguientes roles:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (si necesitas hacer setIamPermissions para los extremos públicos)
  • roles/secretmanager.admin (si se usan Secrets)
  • roles/serviceusage.serviceUsageAdmin (si necesitas habilitar APIs nuevas)

Te recomendamos que uses una cuenta que ya haya instalado extensiones y que haya implementado funciones, ya que la mayoría de estos permisos ya se habrán otorgado. Si tu cuenta de migración necesita más roles, sigue las instrucciones de IAM de Google Cloud para agregarlos.

Actualiza tu instancia de extensión a la versión más reciente

Debes actualizar tu extensión a la versión más reciente para minimizar la diferencia entre la instancia de la extensión y su kit de reemplazo. Si no actualizas la extensión, es posible que haya cambios rotundos significativos entre la instancia de la extensión y el kit que la reemplaza. Es posible que la configuración exportada no coincida con lo que espera el kit debido a los cambios de parámetros entre las versiones.

Usa una de las siguientes opciones para actualizar la extensión, según dónde se haya instalado:

  • Desde la consola deFirebase
  • Desde la CLI de Firebase con lo siguiente:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Si omites este paso, la CLI te solicitará que actualices cuando exportes la configuración si tu extensión no tiene la versión más reciente.

Bifurca la extensión en un kit de funciones local

Antes de comenzar a convertir una extensión en un kit de funciones locales, asegúrate de que el código fuente de la extensión esté dentro de tu proyecto de Firebase. Para ello, clona el repositorio de la extensión desde GitHub, crea un directorio dentro de la raíz del proyecto de Firebase y copia la carpeta functions/ y el archivo extension.yaml de la extensión en él:

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

Sigue los pasos del 1 al 8 de la guía de migración para publicadores para migrar el código fuente de tu extensión a una función de 2ª gen. Luego, continúa con los siguientes pasos.

Haz que tu kit local admita la región de la función exportada y los parámetros avanzados

En un kit de funciones locales, la CLI de Firebase no genera un archivo index.ts para configurar el paquete y usar los parámetros del sistema migrados. Para usar la región de la función y los parámetros avanzados que se configuraron para tu extensión, configura el archivo index.ts para que lea el formato que exportó firebase ext:export --mode functions en un archivo de variables de entorno.

Específicamente, en el archivo index.ts de nivel superior que exporta tus funciones, define un parámetro para FUNCTION_DEFAULT_REGION y llama a setGlobalOptions con variables de entorno de la forma EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>, similar a la plantilla index-kit-migration.ts que usa la 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";

Prueba tu kit antes de la migración

Ahora tienes un kit de funciones local que, cuando se implementa, se comporta de manera idéntica a una instalación nueva de tu extensión. El siguiente paso es verificar y corregir cualquier problema que se haya introducido de forma accidental antes de migrar las instancias de la extensión de producción a ella.

Primero, agrega tu bifurcación como un kit local, configúrala y, luego, impleméntala en un proyecto de prueba. Los kits de funciones locales deben estar dentro de tu proyecto de Firebase, por lo que, si el repositorio de extensiones clonado está fuera de tu proyecto de Firebase, muévelo al directorio del proyecto. Luego, ejecuta el siguiente comando de instalación del kit para instalarlo como un kit local:

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

Este comando te guiará para elegir un ID de kit, un ID de instancia y una configuración para tu primera instancia de prueba. Luego, modifica tu archivo firebase.json para registrar un kit local que apunte a tu directorio bifurcado, con parámetros de configuración para cada instancia almacenados en un archivo .env en function-kits/<kit-id>/config-<instance-id>.

Implementa tu kit local en un proyecto de prueba con los recursos adecuados para probar su comportamiento. Si ya tienes un proyecto de prueba configurado para probar tu extensión, ejecuta el siguiente comando:

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

Ejemplo práctico: Transmite Cloud Firestore a BigQuery (firestore-bigquery-export)

Verifica la sincronización de extremo a extremo de Cloud Firestore a BigQuery:

  1. En la página Cloud Firestore de Firebase console, crea la colección que configuraste como COLLECTION_PATH (users) si aún no existe.
  2. Crea un documento llamado bigquery-mirror-test que contenga cualquier campo con cualquier valor.

  3. En la página BigQuery de la consola de Google Cloud, consulta la tabla de registro de cambios sin procesar. Debería contener una sola fila que registre la creación del documento:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Consulta la vista más reciente, que debería mostrar el evento de cambio más reciente para el único documento presente (bigquery-mirror-test):

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Borra el documento bigquery-mirror-test en Cloud Firestore. Desaparece de la vista más reciente y se agrega un evento DELETE a la tabla de registro de cambios sin procesar.

    Puedes inspeccionar el historial completo de un solo documento con lo siguiente:

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

Diferencias con respecto a la prueba de la extensión:

  • El activador se implementa como kit-<kit-instance-id>-fsexportbigquery, no como ext-<instanceId>-fsexportbigquery. Busca ese nombre en el panel y los registros de Cloud Functions.
  • Tu código se ejecuta en Firebase Local Emulator Suite como funciones estándar. Puedes establecer valores de parámetros para usarlos en el emulador con .env.local. También puedes realizar pruebas de unidades en tu código con el SDK de firebase-functions-test, como se describe en Pruebas de unidades de Cloud Functions.
  • El entorno de ejecución de extensiones ya no controla el aprovisionamiento. Si falta la tabla de registro de cambios después de la implementación, vuelve a ejecutar la tarea de configuración de forma manual: firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>. La tarea es idempotente, por lo que volver a ejecutarla concilia el conjunto de datos, la tabla y las vistas.
  • Los valores de los parámetros provienen de .env, en lugar del formulario de instalación, por lo que las nuevas ejecuciones de firebase deploy no son interactivas una vez que se completa .env.

Limpia los recursos de prueba (opcional)

Si quieres quitar esta instancia de prueba después de realizar las pruebas, desinstálala:

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

Esto borra todos los recursos de la nube creados con la implementación del kit y quita su configuración de instancia. Si solo tienes una instancia del kit, también se quitará la entrada del kit de firebase.json. No borra el directorio de código fuente local. Cuando instales el kit para la migración de producción, podrás volver a elegir un ID de kit.

Migra de extensiones a tu kit local

Ahora que probaste tu kit local, puedes migrar la instancia de la extensión implementada en vivo.

1. Instala la instancia de reemplazo del kit de funciones

Instala tu kit de funciones locales y pasa --no-configure para omitir la configuración manual, de modo que el siguiente paso pueda exportar la configuración de la extensión existente directamente a esta instancia del kit:

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

2. Configura la instancia del kit de funciones de forma idéntica a la extensión

Debes personalizar esta instancia del kit con una configuración idéntica a la de la extensión que reemplaza. Puedes exportar la configuración de tu instancia de extensión a un archivo .env, que almacena los datos de configuración de parámetros, variables de entorno y referencias de secretos para todos los Cloud Functions, incluidos los kits. Para exportarla directamente al archivo de configuración de tu kit, ejecuta lo siguiente:

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

Al final de este paso, la información de configuración de esta instancia se almacena en un archivo .env específico del proyecto en el directorio de configuración de la instancia, como function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

3. Implementa y verifica el reemplazo del kit

Ahora que el kit está instalado y disponible como un conjunto de funciones, puedes implementar el reemplazo del kit. Los kits de funciones funcionan como las funciones estándar, en las que cada instancia de kit actúa como una base de código independiente para organizar tus funciones. Puedes elegir implementar todas tus funciones o solo una instancia de kit específica. Cuando migres una sola instancia de extensión, implementa solo esa instancia del kit.

Si tu kit usa parámetros nuevos que no estaban presentes en la instancia de la extensión desde la que migraste, la CLI de Firebase te los solicitará al comienzo del proceso de implementación. Esto no se espera en este ejemplo de trabajo de una extensión de firestore-bigquery-export actualizada, pero muchos kits solicitan un parámetro nuevo para cualquier fuente de activador de eventos que use el kit. Como parte de esta migración, los kits actualizados usan funciones de 2ª gen. en las que las extensiones antes usaban funciones de 1ª gen. En la 2ª gen., las funciones se ubican cerca de sus fuentes de eventos y se agregan como un parámetro adicional. En las actualizaciones futuras, si se agregan parámetros nuevos, la CLI te los solicitará en la próxima implementación.

Ejemplo práctico:

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

Resultado:

=== 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!

Para verificar que el firebase deploy del kit no haya tenido errores, revisa los registros de implementación para ver si se activó algún hook del ciclo de vida. Las extensiones populares, como Transmitir Cloud Firestore a BigQuery, usan hooks de ciclo de vida. A continuación, se muestra un ejemplo de cómo se ve un hook de ciclo de vida cuando se activa:

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

Estos mensajes de registro confirman lo siguiente:

  • Se encontró y ejecutó un hook de ciclo de vida.
  • Se puso en cola una tarea en la lista de tareas en cola asociada del hook del ciclo de vida.
  • Se proporcionó un vínculo a Cloud Logging para que puedas validar que la tarea se completó sin errores.

Sigue el vínculo de los registros a la consola de Google Cloud para validar que no haya errores en los registros y que el evento de la lista de tareas en cola se haya procesado correctamente. Si el evento de ciclo de vida no se ejecutó correctamente, puedes volver a activarlo con el siguiente comando:

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

Si es la primera vez que implementas una instancia de kit de funciones, ejecuta lo siguiente:

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

Si en cualquier momento durante la validación decides que quieres detener o deshacer esta migración, puedes desinstalar el kit con las instrucciones que se indican en Desinstala la extensión.

Una vez que hayas verificado que la implementación inicial de tu kit de funciones se completó correctamente, debes validar que la funcionalidad del kit esté funcionando como se espera. Como la extensión en sí sigue ejecutándose, debes tener cuidado de que lo que estás verificando no sea solo que una de las dos haya funcionado, ya que la extensión ha estado funcionando y seguirá haciéndolo.

En el caso de que el procesamiento no cambie y no veas resultados duplicados de la extensión y el kit, la mejor opción es examinar directamente los registros del kit después de activar su funcionalidad.

Ejemplo práctico: Transmite Cloud Firestore a BigQuery

Con la extensión Stream Cloud Firestore to BigQuery, las escrituras en la tabla de registro de cambios sin procesar (*_raw_changelog) y en la tabla de vista más reciente (*_raw_latest) se desduplicarán si se entrega el mismo evento al kit y a la extensión. Por lo tanto, no puedes usar la presencia de filas o filas duplicadas en BigQuery para validar que el kit funcione.

Puedes ver los registros de las funciones poco después de escribir en tu colección de Firestore con firebase functions:logs y buscar una entrada de registro que indique que se procesó correctamente una escritura. Para este kit con el ID de instancia predeterminado de firestore-bigquery-export, se vería de la siguiente manera:

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

Si tienes muchos registros, puedes filtrarlos para ver una función específica del kit con el siguiente comando:

firebase functions:log --only <function name>

Para encontrar los nombres de las funciones específicas de una instancia de kit, puedes usar el siguiente comando:

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

En este ejemplo, sucede lo siguiente:

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. Desinstala la extensión

Cuando hayas verificado el kit de funciones implementado, puedes desinstalar la extensión para no duplicar su comportamiento, una vez para el kit y otra para la extensión. Puedes desinstalar todas las extensiones desde la CLI de Firebase, sin importar cómo las instalaste, si pasas la marca --immediate:

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

Ejemplo práctico:

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

Resultado:

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

Migraciones avanzadas

Puedes tener extensiones en varios proyectos de Firebase que quieras administrar con una sola base de código. Por ejemplo, si implementas la misma infraestructura en un entorno de testing y un entorno de production, cada uno de los cuales tiene una instancia de documents Cloud Firestore que exportas a BigQuery, es posible que tengas instaladas dos instancias de la extensión firestore-bigquery-export:

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

Si migraste estas dos instancias de extensión a dos instancias de kit de funciones en una sola base de código cuando trabajabas con la CLI de Firebase y las implementaste con firebase deploy --project testing y firebase deploy --project production, cada implementación crearía dos instancias en los entornos de testing y production.

En su lugar, reemplaza las dos instancias de extensión por una instancia de kit de funciones de firestore-bigquery-export implementada en varios proyectos, en los que cada proyecto tiene su propia configuración. El directorio de configuración de la instancia debería verse de la siguiente manera:

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

Cada implementación en testing y production crea una instancia de tu kit con la configuración correspondiente. Los comandos de la CLI existentes crean esta configuración siempre que pases la marca --project en cada invocación de ext:migrate o functions:kits:install.

Ejemplo práctico:

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

Ahora tienes una sola instancia de kit configurada para implementarla en tus proyectos testing y production con sus respectivas configuraciones. Si creas una instancia en el proyecto testing y ejecutas el comando functions:kits:install para el mismo paquete en el proyecto production, se te solicitará la opción de reutilizar la instancia configurada para testing o instalar una segunda instancia.