Перенесите расширения Firebase на самостоятельно созданный набор функций.

Выберите путь миграции: Переход на наборы функций в npm Переход на самостоятельно созданный набор функций

Если издатель не создал официальный комплект для замены, распространяемый через npm, это руководство проведет вас через шаги по созданию форка его расширения и настройке его в качестве локального комплекта функций.

Проверьте наличие известных ограничений миграции.

Прежде чем начать миграцию экземпляра расширения, проверьте, не использует ли ваша конфигурация какие-либо из следующих функций, требующих обходного пути или еще не поддерживаемых в функциональных комплектах:

  • Для настройки пользовательских репозиториев Docker и ключей KMS требуется обходной путь вручную. Cloud Functions for Firebase не поддерживает замену системных параметров для настройки пользовательского репозитория Docker или ключа шифрования, управляемого клиентом (ключа KMS). Если ваше расширение настраивает какой-либо из этих параметров, обратитесь к обходному пути в разделе часто задаваемых вопросов .

Прежде чем начать

Вам необходимо настроить Firebase CLI и инициализировать проект Firebase . При использовании CLI убедитесь, что вы используете firebase-tools версии >= 15.32.0 , в которой есть новые команды миграции и набора функций.

Необходимые права доступа и роли учетной записи

В зависимости от того, что необходимо создать и настроить с помощью Firebase CLI во время миграции, учетная запись, используемая для аутентификации в Firebase и Google Cloud должна обладать следующими ролями:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (если вам нужно установить setIamPermissions ) для общедоступных конечных точек)
  • roles/secretmanager.admin (если используются секреты)
  • roles/serviceusage.serviceUsageAdmin (если вам нужно включить новые API)

Мы рекомендуем использовать учетную запись, в которой ранее устанавливались расширения и развертывались функции, поскольку большинство этих разрешений уже предоставлено. Если вашей мигрируемой учетной записи требуется больше ролей, следуйте инструкциям Google Cloud IAM, чтобы добавить их.

Обновите свой экземпляр расширения до последней версии.

Для минимизации различий между вашим экземпляром расширения и его заменяющим комплектом необходимо обновить расширение до последней версии. Если ваше расширение не будет обновлено, могут возникнуть существенные, критические изменения между вашим экземпляром расширения и его заменяющим комплектом. Экспортированная конфигурация может не соответствовать ожиданиям комплекта из-за изменений параметров в разных версиях.

Для обновления расширения воспользуйтесь одним из следующих способов, в зависимости от места его установки:

  • Из консоли Firebase
  • Из командной строки Firebase используйте:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Если вы пропустите этот шаг, CLI предложит вам обновить расширение при экспорте конфигурации, если оно не последней версии.

Создайте форк расширения в локальном наборе функций.

Прежде чем приступать к преобразованию расширения в локальный набор функций, убедитесь, что исходный код расширения находится внутри вашего проекта Firebase . Для этого клонируйте репозиторий расширения с GitHub, создайте каталог в корневой директории вашего проекта Firebase и скопируйте в него папку functions/ и файл extension.yaml расширения:

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

Выполните шаги с 1 по 8 из руководства по миграции издателя , чтобы перенести исходный код вашего расширения во вторую функцию. Затем перейдите к следующим шагам.

Настройте локальный комплект так, чтобы он поддерживал экспортируемые функциональные области и расширенные параметры.

В локальном наборе функций Firebase CLI не генерирует файл index.ts для настройки пакета и его конфигурации для использования перенесенных системных параметров. Чтобы использовать регионы функций и расширенные параметры, настроенные для вашего расширения, настройте файл index.ts так, чтобы он считывал формат, экспортируемый командой firebase ext:export --mode functions в файл переменных окружения.

В частности, в файле index.ts верхнего уровня, который экспортирует ваши функции, определите параметр FUNCTION_DEFAULT_REGION и вызовите setGlobalOptions с переменными окружения вида EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION> , аналогично шаблону index-kit-migration.ts используемому 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";

Проверьте свой комплект оборудования перед миграцией.

Теперь у вас есть локальный набор функций, который после развертывания ведет себя идентично новой установке вашего расширения. Следующий шаг — проверить и исправить любые случайно возникшие проблемы, прежде чем переносить на него экземпляры вашего рабочего расширения.

Сначала добавьте свой форк в качестве локального набора, настройте его и разверните в тестовом проекте. Локальные наборы функций должны находиться внутри вашего проекта Firebase , поэтому, если клонированный репозиторий расширения находится вне вашего проекта Firebase , переместите его в каталог проекта. Затем выполните следующую команду установки набора, чтобы установить его как локальный набор:

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

Эта команда поможет вам выбрать идентификатор набора (kit ID), идентификатор экземпляра (instance ID) и конфигурацию для вашего первого тестового экземпляра. Затем она изменит ваш файл firebase.json , чтобы зарегистрировать локальный набор, указывающий на вашу форкнутую директорию, а конфигурации для каждого экземпляра будут храниться в файле .env по адресу function-kits/<kit-id>/config-<instance-id> .

Разверните локальный комплект в тестовом проекте с необходимыми ресурсами для проверки его работы. Если у вас уже есть тестовый проект, созданный во время тестирования расширения, выполните следующую команду:

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

Пример работы: потоковая передача данных из Cloud Firestore в BigQuery ( firestore-bigquery-export )

Проверьте сквозную синхронизацию Cloud Firestore и BigQuery :

  1. На странице Cloud Firestore в консоли Firebase создайте коллекцию, указанную в переменной COLLECTION_PATH ( users ), если она еще не существует.
  2. Создайте документ с именем bigquery-mirror-test , содержащий любые поля с любыми значениями.

  3. На странице BigQuery в консоли Google Cloud выполните запрос к исходной таблице changelog. Она должна содержать одну строку, регистрирующую создание документа:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Запросите последнюю версию представления , которая должна вернуть последнее событие изменения для единственного присутствующего документа ( bigquery-mirror-test ):

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Удалите документ bigquery-mirror-test в Cloud Firestore . Он исчезнет из списка последних изменений, и в таблицу исходного журнала изменений будет добавлено событие DELETE .

    Вы можете просмотреть полную историю отдельного документа с помощью:

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

Отличия от результатов тестирования расширения:

  • Триггер развертывается как kit-<kit-instance-id>-fsexportbigquery , а не ext-<instanceId>-fsexportbigquery . Найдите это имя на панели мониторинга и в журналах Cloud Functions .
  • Ваш код выполняется в Firebase Local Emulator Suite как стандартные функции. Вы можете задать значения параметров для использования в эмуляторе с помощью .env.local . Вы также можете протестировать свой код с помощью SDK firebase-functions-test как описано в разделе «Модульное тестирование Cloud Functions .
  • Процесс подготовки ресурсов больше не управляется средой выполнения расширений. Если после развертывания отсутствует таблица журнала изменений, повторно запустите задачу настройки вручную: firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id> . Задача является идемпотентной, поэтому ее повторный запуск согласует набор данных, таблицу и представления.
  • Значения параметров берутся из .env , а не из формы установки, поэтому повторный запуск команды firebase deploy становится неинтерактивным после завершения обработки файла .env .

(Необязательно) Очистка после тестирования

Если вы хотите удалить этот тестовый экземпляр после завершения тестирования, выполните его деинсталляцию:

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

Это удалит все облачные ресурсы, созданные при развертывании комплекта, и удалит конфигурацию его экземпляра. Если у вас только один экземпляр комплекта, это также удалит запись о комплекте из файла firebase.json . При этом локальный каталог с исходным кодом не удаляется. При установке комплекта для миграции в продакшн вы сможете снова выбрать идентификатор комплекта.

Перейдите с расширений на локальный набор инструментов.

Теперь, когда ваш локальный комплект протестирован, вы можете перенести развернутый в рабочем режиме экземпляр расширения.

1. Установите экземпляр комплекта заменяющих функций.

Установите локальный набор функций, передав --no-configure , чтобы пропустить ручную настройку, и на следующем шаге можно будет экспортировать существующую конфигурацию расширения непосредственно в этот экземпляр набора:

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

2. Настройте экземпляр функционального набора точно так же, как и расширение.

Вам необходимо настроить этот экземпляр комплекта, присвоив ему конфигурацию, идентичную конфигурации заменяемого им расширения. Вы можете экспортировать конфигурацию экземпляра расширения в файл .env , который хранит данные конфигурации параметров, переменных среды и секретных ссылок для всех Cloud Functions , включая комплекты. Чтобы экспортировать ее непосредственно в файл конфигурации вашего комплекта, выполните: 

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

По завершении этого шага информация о конфигурации данного экземпляра сохраняется в файле .env , специфичном для проекта, в каталоге конфигурации вашего экземпляра, например: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

3. Развернуть и проверить замену комплекта.

Теперь, когда комплект установлен и доступен в виде набора функций, вы можете развернуть замену комплекта. Функциональные комплекты работают как стандартные функции, где каждый экземпляр комплекта выступает в качестве отдельной кодовой базы для организации ваших функций. Вы можете развернуть все свои функции или только определенный экземпляр комплекта. При миграции отдельного экземпляра расширения разверните только этот экземпляр комплекта.

Если ваш комплект использует какие-либо новые параметры, которых не было в экземпляре расширения, с которого вы перешли, Firebase CLI запросит их в начале процесса развертывания. В этом примере с обновленным расширением firestore-bigquery-export это не ожидается, но многие комплекты запрашивают новый параметр для любого источника событий, используемого комплектом. В рамках этой миграции обновленные комплекты используют функции второго поколения там, где ранее расширения использовали функции первого поколения. Во втором поколении функции расположены рядом с источниками событий и добавляются в качестве дополнительного параметра. В будущих обновлениях, если будут добавлены новые параметры, CLI запросит их при следующем развертывании.

Пример решения задачи: 

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

Выход: 

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

Чтобы убедиться в отсутствии ошибок firebase deploy , проверьте журналы развертывания на предмет срабатывания каких-либо хуков жизненного цикла. Популярные расширения, такие как Stream Cloud Firestore to BigQuery , используют хуки жизненного цикла. Ниже приведен пример того, как выглядит срабатывающий хук жизненного цикла: 

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

Эти сообщения в журнале подтверждают следующее:

  • Был найден и реализован механизм жизненного цикла.
  • Задача была поставлена ​​в очередь задач, связанную с хуком жизненного цикла.
  • Предоставлена ​​ссылка на Cloud Logging, чтобы вы могли убедиться, что задача выполнена без ошибок.

Перейдите по ссылке «Журналы» в консоль Google Cloud , чтобы убедиться в отсутствии ошибок в журналах и успешной обработке события в очереди задач. Если событие жизненного цикла не выполнилось успешно, вы можете повторно запустить его, выполнив следующую команду: 

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

Если вы развертываете экземпляр комплекта функций впервые, выполните следующую команду: 

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

Если в любой момент во время проверки вы решите остановить или отменить миграцию, вы можете удалить комплект, следуя инструкциям в разделе «Удаление расширения» .

4. Удалите расширение.

После проверки развернутого набора функций вы можете удалить расширение, чтобы избежать дублирования его поведения для набора функций и для расширения. Вы можете удалить все расширения из Firebase CLI независимо от способа их установки, если передадите флаг --immediate : 

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

Пример решения задачи: 

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

Выход: 

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

Расширенные миграции

В нескольких проектах Firebase можно использовать расширения, которыми нужно управлять с помощью одной кодовой базы. Например, если вы развернете одну и ту же инфраструктуру в testing и production средах, в каждой из которых есть экземпляр Cloud Firestore для documents , экспортируемый в BigQuery , у вас может быть установлено два экземпляра расширения firestore-bigquery-export :

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

Если вы перенесли эти два экземпляра расширений в два экземпляра функционального набора в рамках одной кодовой базы при работе с Firebase CLI и развернули их с помощью firebase deploy --project testing и firebase deploy --project production , то каждое развертывание создаст два экземпляра как в testing , так и в production среде.

Вместо этого замените два экземпляра расширения одним экземпляром функционального набора firestore-bigquery-export развернутым в нескольких проектах, причем каждый проект будет иметь свою собственную конфигурацию. Каталог конфигурации для этого экземпляра должен выглядеть следующим образом:

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

Каждое развертывание в testing и production создает один экземпляр вашего комплекта с соответствующей конфигурацией. Существующие команды CLI создают эту конфигурацию, если вы передаете флаг --project в каждом вызове ext:migrate или functions:kits:install .

Пример решения задачи: 

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

Теперь у вас есть единый экземпляр комплекта, настроенный для развертывания в testing и production проектах с соответствующими конфигурациями. Если вы создадите экземпляр в testing проекте и запустите команду functions:kits:install для того же пакета в production проекте, вам будет предложено либо повторно использовать экземпляр, настроенный для testing , либо установить второй экземпляр.