Migrer les extensions Firebase vers des kits de fonctions

Ce guide vous explique comment migrer vos extensions de l'environnement Firebase Extensions obsolète vers un kit de fonctions que vous pouvez installer et déployer dans votre propre codebase Cloud Functions pour Firebase (2e génération).

Firebase Extensions gérait tous les aspects de la création, de la mise à jour et de la suppression des extensions. Les kits de fonctions regroupent les fonctionnalités des extensions sous la forme de Cloud Functions for Firebase de deuxième génération classiques. Étant donné que les kits de fonctions sont des Cloud Functions standards, vous pouvez les créer, les mettre à jour, les supprimer et résoudre les problèmes associés à l'aide de la CLI Firebase dans votre projet Firebase. Ce guide vous prépare à gérer vos fonctions dès maintenant et à adopter les mises à jour à mesure qu'elles sont disponibles.

Dans ce guide, l'extension Stream Cloud Firestore to BigQuery (firestore-bigquery-export) est utilisée comme exemple pour vous montrer les commandes et les résultats de la commande pour chaque étape de la migration.

Déterminer votre chemin de migration

Firebase encourage tous les éditeurs Firebase Extensions à créer des remplacements pour leurs extensions sous forme de kits de fonctions publiés sur npm. Vous pouvez vérifier si un kit de fonctions de remplacement est disponible pour vos extensions de plusieurs manières :

  • Accédez à la page "Extensions" de la console Firebase pour votre projet. Chaque extension installée indique si un kit de remplacement de fonction est disponible.

  • Exécutez firebase ext:list dans votre projet Firebase dans un terminal pour afficher les extensions installées qui ont des remplacements officiels :

    firebase ext:list --project my-project

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

Si un kit de fonctions de remplacement officiel est disponible pour votre extension, vous pouvez la migrer à l'aide de la section Migrer vers des kits de fonctions sur npm.

Si vous ne trouvez pas de remplacement publié, vous pouvez dupliquer le code de l'extension et créer votre propre remplacement, car toutes les extensions sont Open Source. Pour ce faire, suivez le guide Migrer vers un kit de fonctions créé par vos soins.

Sélectionnez le chemin de migration : Migrer vers les kits de fonctions sur npm Migrer vers un kit de fonctions créé par vos soins

Migrer vers des kits de fonctions sur npm

Vérifier les limites de migration connues

Avant de commencer à migrer une instance d'extension, vérifiez si votre configuration utilise l'une des fonctionnalités suivantes qui nécessitent une solution de contournement ou ne sont pas encore compatibles avec les kits de fonctions :

  • Les dépôts Docker personnalisés et les clés KMS nécessitent une solution de contournement manuelle Cloud Functions for Firebase n'est pas compatible avec les paramètres système de remplacement pour configurer un dépôt Docker personnalisé ou une clé de chiffrement gérée par le client (clé KMS). Si votre extension configure l'un de ces paramètres, consultez la solution de contournement de la FAQ.

Avant de commencer

Vous devez configurer la CLI Firebase et initialiser un projet Firebase. Lorsque vous utilisez la CLI, assurez-vous d'utiliser la version >= 15.32.0 de firebase-tools, qui inclut les nouvelles commandes de migration et de kit de fonctions.

Autorisations et rôles requis pour le compte

Selon ce qui doit être créé et configuré par la CLI Firebase lors de la migration, le compte que vous utilisez pour vous authentifier auprès de Firebase et Google Cloud doit disposer des rôles suivants :

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (si vous devez effectuer setIamPermissions pour les points de terminaison publics)
  • roles/secretmanager.admin (si vous utilisez des secrets)
  • roles/serviceusage.serviceUsageAdmin (si vous devez activer de nouvelles API)

Nous vous recommandons d'utiliser un compte qui a déjà installé des extensions et déployé des fonctions, car la plupart de ces autorisations auront déjà été accordées. Si votre compte de migration a besoin de rôles supplémentaires, suivez les instructions Google Cloud IAM pour les ajouter.

Choisir un workflow CLI

Pour migrer d'une instance d'extension vers un kit de fonctions disponible sur npm, choisissez l'une des options suivantes :

  • (Recommandé) Migrez à l'aide de la commande CLI ext:migrate. Cette commande déploie le remplacement de votre kit de fonctions avant de désinstaller l'extension qu'il remplace.
  • Migrez à l'aide des commandes CLI des kits de fonctions. Vous pouvez utiliser des commandes distinctes pour mettre à jour votre extension, installer un kit de fonctions, le configurer comme l'extension, déployer le kit et désinstaller l'extension. Cela offre plus de flexibilité pour réorganiser les commandes ou effectuer des tâches supplémentaires entre les étapes.

Migrer à l'aide de ext:migrate

Démarrez une migration une fois par instance d'extension en exécutant la commande suivante :

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

Cette commande vous guide à travers les étapes suivantes :

  1. Sélection d'une extension à migrer pour laquelle un kit de fonctions officiel de remplacement est disponible.
  2. Sélectionner une instance spécifique de cette extension.
  3. Mettre à jour l'extension vers sa dernière version si nécessaire.
  4. Installez le kit de fonctions et configurez une instance de la même manière que l'instance d'extension.
  5. Déployez le kit de fonctions.
  6. Vérifiez que le kit de fonctions a été déployé correctement et que tous les hooks de cycle de vie, le cas échéant, ont été exécutés.
  7. Désinstallez l'instance d'extension.

Si vous connaissez l'extension ou l'instance d'extension spécifique que vous souhaitez migrer, spécifiez-la à l'aide des options de ligne de commande suivantes :

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

# or

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

Si vous connaissez le package spécifique vers lequel vous souhaitez migrer, en particulier s'il ne s'agit pas d'un package de remplacement officiel listé par Google, spécifiez-le à l'aide du flag --package :

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

Vérifier le déploiement d'un kit de fonctions

Pour vérifier que le firebase deploy du kit ne comporte aucune erreur, consultez les journaux de déploiement pour voir si des hooks de cycle de vie ont été déclenchés. Les extensions populaires, telles que Stream Cloud Firestore à BigQuery, utilisent des hooks de cycle de vie. Voici un exemple de hook de cycle de vie lorsqu'il est déclenché :

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

Ces messages de journal confirment les points suivants :

  • Un hook de cycle de vie a été trouvé et exécuté.
  • Une tâche a été mise en file d'attente dans la file d'attente des tâches associée au hook de cycle de vie.
  • Un lien vers Cloud Logging vous a été fourni pour vous permettre de vérifier que la tâche s'est terminée sans erreur.

Suivez le lien vers les journaux de la console Google Cloud pour vérifier qu'il n'y a pas d'erreurs dans les journaux et que l'événement de votre file d'attente de tâches a bien été traité. Si l'événement de cycle de vie ne s'est pas exécuté correctement, vous pouvez le redéclencher en exécutant la commande suivante :

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

Si vous déployez une instance de kit de fonctions pour la première fois, exécutez la commande suivante :

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

Si, à un moment donné de la validation, vous décidez d'arrêter ou d'annuler cette migration, vous pouvez désinstaller le kit en suivant les instructions de la section Désinstaller l'extension.

Examiner le fichier README du kit de fonctions

Certains kits peuvent nécessiter des tâches supplémentaires au-delà de celles gérées automatiquement par les kits de fonctions. Consultez la README du kit que vous installez et suivez les instructions supplémentaires.

Migrer à l'aide de la CLI des kits de fonctions

Avant de commencer, identifiez et notez l'ID d'instance de l'extension que vous souhaitez migrer vers un kit, ainsi que le nom du package npm de son kit de remplacement. Vous pouvez trouver ces deux éléments à l'aide de la sortie de firebase ext:list. Pour obtenir un exemple d'utilisation de ext:list, consultez Déterminer votre chemin de migration.

1. Mettre à niveau l'instance de votre extension vers la dernière version

Vous devez mettre à jour votre extension vers la dernière version pour minimiser la différence entre votre instance d'extension et son kit de remplacement. Si votre extension n'est pas mise à niveau, il peut y avoir des changements majeurs et incompatibles entre votre instance d'extension et son kit de remplacement. La configuration exportée peut ne pas correspondre à ce que le kit attend en raison de modifications de paramètres entre les versions.

Utilisez l'une des options suivantes pour mettre à jour votre extension, selon l'endroit où elle a été installée :

  • Depuis la console Firebase
  • Depuis la CLI Firebase à l'aide de :
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Si vous ignorez cette étape, la CLI vous invite à effectuer la mise à niveau lors de l'exportation de la configuration si votre extension n'est pas à la dernière version.

2. Examiner et installer l'instance du kit de fonctions de remplacement

Vous pouvez installer le kit de fonctions à l'aide de la commande CLI suivante :

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

Lorsque vous choisissez un ID d'instance pour votre kit lors de l'installation, veillez à le noter pour l'utiliser plus tard dans les instructions de migration.

Une fois le kit installé, un nouveau répertoire est créé dans votre projet Firebase, avec un emplacement tel que function-kits/<kit-name>/source. Il contient le package npm avec le kit remplaçant votre extension et un fichier index.ts de base qui exporte ces fonctions pour que Firebase puisse les déployer et définir une configuration personnalisée.

Consultez le README du kit et suivez les instructions supplémentaires qui y sont indiquées.

Si vous avez plusieurs instances du kit dans le même projet, vous pouvez répéter cette commande pour créer d'autres instances du même kit. Vous pouvez également déployer une seule instance de kit sur deux projets Firebase différents avec des configurations différentes (par exemple, un projet de staging et un projet de production). Pour en savoir plus sur ces configurations avancées, consultez Migrations avancées.

Exemple :

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

3. Configurer l'instance du kit de fonctions de la même manière que l'extension

Vous devez personnaliser cette instance de kit avec une configuration identique à celle de l'extension qu'elle remplace. Vous pouvez exporter la configuration de votre instance d'extension dans un fichier .env, qui stocke les données de configuration des paramètres, des variables d'environnement et des références secrètes pour tous les Cloud Functions, y compris les kits. Pour l'exporter directement dans le fichier de configuration de votre kit, exécutez la commande suivante :

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

À la fin de cette étape, les informations de configuration de cette instance sont stockées dans un fichier .env spécifique au projet, dans le répertoire de configuration de votre instance, par exemple : function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

4. Déployer et vérifier le remplacement du kit

Maintenant que le kit est installé et disponible en tant qu'ensemble de fonctions, vous pouvez déployer le kit de remplacement. Les kits de fonctions fonctionnent comme des fonctions standards, où chaque instance de kit agit comme une base de code distincte pour organiser vos fonctions. Vous pouvez choisir de déployer toutes vos fonctions ou seulement une instance de kit spécifique. Lorsque vous migrez une seule instance d'extension, ne déployez que cette instance de kit.

Si votre kit utilise de nouveaux paramètres qui n'étaient pas présents dans l'instance d'extension à partir de laquelle vous avez migré, la CLI Firebase vous les demande au début du processus de déploiement. Ce n'est pas prévu dans cet exemple pratique à partir d'une extension firestore-bigquery-export à jour, mais de nombreux kits demandent un nouveau paramètre pour toute source de déclencheur d'événement utilisée par le kit. Dans le cadre de cette migration, les kits mis à jour utilisent des fonctions de 2e génération, alors que les extensions utilisaient auparavant des fonctions de 1re génération. Dans la 2e génération, les fonctions sont situées à proximité de leurs sources d'événements et ajoutées en tant que paramètre supplémentaire. Dans les prochaines mises à jour, si de nouveaux paramètres sont ajoutés, la CLI vous y invite lors du prochain déploiement.

Exemple :

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

Résultat :

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

Pour vérifier que le firebase deploy du kit ne comporte aucune erreur, consultez les journaux de déploiement pour voir si des hooks de cycle de vie ont été déclenchés. Les extensions populaires, telles que Stream Cloud Firestore à BigQuery, utilisent des hooks de cycle de vie. Voici un exemple de hook de cycle de vie lorsqu'il est déclenché :

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

Ces messages de journal confirment les points suivants :

  • Un hook de cycle de vie a été trouvé et exécuté.
  • Une tâche a été mise en file d'attente dans la file d'attente des tâches associée au hook de cycle de vie.
  • Un lien vers Cloud Logging vous a été fourni pour vous permettre de vérifier que la tâche s'est terminée sans erreur.

Suivez le lien vers les journaux de la console Google Cloud pour vérifier qu'il n'y a pas d'erreurs dans les journaux et que l'événement de votre file d'attente de tâches a bien été traité. Si l'événement de cycle de vie ne s'est pas exécuté correctement, vous pouvez le redéclencher en exécutant la commande suivante :

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

Si vous déployez une instance de kit de fonctions pour la première fois, exécutez la commande suivante :

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

Si, à un moment donné de la validation, vous décidez d'arrêter ou d'annuler cette migration, vous pouvez désinstaller le kit en suivant les instructions de la section Désinstaller l'extension.

5. Désinstaller l'extension

Une fois que vous avez vérifié votre kit de fonctions déployé, vous pouvez désinstaller votre extension afin de ne pas dupliquer son comportement une fois pour le kit et une fois pour l'extension. Vous pouvez désinstaller toutes les extensions de la CLI Firebase, quelle que soit la méthode d'installation, si vous transmettez l'indicateur --immediate :

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

Exemple :

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

Résultat :

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

Migrations avancées

Vous pouvez avoir des extensions dans plusieurs projets Firebase que vous souhaitez gérer avec une seule base de code. Par exemple, si vous déployez la même infrastructure dans un environnement testing et un environnement production, chacun disposant d'une instance documents Cloud Firestore que vous exportez vers BigQuery, vous pouvez avoir deux instances de l'extension firestore-bigquery-export installées :

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

Si vous avez migré ces deux instances d'extension vers deux instances de kit de fonctions dans un même code source lorsque vous travailliez avec la CLI Firebase et que vous avez déployé à l'aide de firebase deploy --project testing et firebase deploy --project production, chaque déploiement créera deux instances dans les environnements testing et production.

Remplacez plutôt les deux instances d'extension par une instance de kit de fonctions firestore-bigquery-export déployée dans plusieurs projets, où chaque projet possède sa propre configuration. Le répertoire de configuration de l'instance doit se présenter comme suit :

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

Chaque déploiement sur testing et production crée une instance de votre kit avec la configuration correspondante. Les commandes CLI existantes créent cette configuration à condition que vous transmettiez l'indicateur --project dans chaque appel de ext:migrate ou functions:kits:install.

Exemple :

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

Vous disposez désormais d'une seule instance de kit configurée pour le déploiement dans vos projets testing et production avec leurs configurations respectives. Si vous créez une instance dans le projet testing et exécutez la commande functions:kits:install pour le même package dans le projet production, vous êtes invité à réutiliser l'instance configurée pour testing ou à installer une deuxième instance.