Часто задаваемые вопросы об устаревании расширений Firebase

Почему мы отказываемся от использования Firebase Extensions ?

В связи с предстоящими изменениями и устареванием функций в нашей базовой Google Cloud , мы прекращаем поддержку управляемого сервиса Firebase Extensions .

Перестанут ли работать уже развернутые расширения после 31 марта 2027 года?

Нет. Уже развернутые расширения работают непосредственно на стандартной инфраструктуре Google Cloud (такой как Cloud Functions , Eventarc , Cloud Run и Cloud Tasks ) и будут продолжать выполняться неограниченно долго.

Однако после 31 марта 2027 года вы потеряете возможность обновлять, перенастраивать или удалять эти расширения через консоль Firebase или CLI. Вы также потеряете возможность загружать существующие конфигурации расширений для облегчения миграции на функциональный набор. Мы настоятельно рекомендуем перенести или экспортировать конфигурации расширений до 31 марта 2027 года.

Что произойдет, если пользователь ничего не предпримет?

Если пользователь не предпримет никаких действий, его существующие развернутые функции будут продолжать работать как стандартные ресурсы. Однако после 31 марта 2027 года:

1. Они не могут изменять параметры конфигурации или обновлять переменные среды.
2. Они не могут устанавливать исправления ошибок, обновления безопасности или устанавливать зависимости.
3. Они не могут загрузить конфигурацию расширения, чтобы обеспечить идентичную настройку заменяющего функционального комплекта.
4. В настоящее время большинство расширений построены на основе устаревшего SDK Cloud Functions v1, который привязан к более старым средам выполнения Node.js. После полного вывода из эксплуатации этих устаревших сред выполнения Google Cloud функции могут перестать работать или быть отключены. См. раздел «Поддержка сред выполнения» .

Есть ли что-нибудь, что заменит Firebase Extensions?

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

Однако каждый издатель расширений сам решает, хочет ли он публиковать официальную замену комплекта функций на npm. Поскольку расширения являются открытым исходным кодом, если издатель не хочет создавать официальную замену, любой разработчик может создать форк, чтобы сделать неофициальную замену с использованием Cloud Functions и наших API второго поколения в Node SDK.

Издателям, желающим произвести замену, следует следовать инструкциям в руководстве по миграции для издателей .

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

Что мне следует делать как пользователю расширения?

Если вы являетесь пользователем расширений и больше не используете установленные расширения, удалите их до 31 марта 2027 года.

После вывода из эксплуатации кнопка «Удалить» в консоли Firebase и соответствующие команды CLI будут удалены. Вам необходимо вручную удалить все связанные ресурсы Google Cloud , включая отдельные Cloud Functions , секреты Secret Manager , очереди Cloud Tasks и пользовательские учетные записи служб IAM, используя консоль Google Cloud .

Однако, если вы активно используете установленные расширения, мы настоятельно рекомендуем перейти на функциональные наборы. Для перехода на функциональные наборы воспользуйтесь инструкциями в нашем руководстве по миграции для пользователей .

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

Что мне следует делать как издателю расширений?

Мы рекомендуем вам перевести ваши опубликованные расширения на наборы функций, публикуемые в npm. Вы можете начать с перевода вашего расширения на функции второго поколения, что является необходимым условием для создания набора функций. Это включает в себя упаковку логики вашего расширения с использованием SDK Cloud Functions v2. Мы обновили SDK Cloud Functions v2, добавив поддержку таких функций, как декларативная безопасность и события жизненного цикла. Теперь вы можете перевести существующий код вашего расширения на функцию второго поколения с минимальными изменениями в основной бизнес-логике. Эти функции можно опубликовать с помощью пакета npm. Подробности см. в нашем руководстве по миграции для издателей .

А что, если у меня возникнут другие вопросы?

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

Издатели, у которых возникли вопросы по миграции Firebase Extensions могут воспользоваться нашим руководством по миграции для издателей . Это руководство содержит инструкции о том, как оставаться в курсе обновлений и получать помощь в предоставлении альтернативы опубликованным расширениям.

Какие основные пути миграции доступны?

Начиная с сентября 2026 года, Firebase официально поддерживает два основных пути миграции:

1. Переход на NPM-Shared Function ("набор функций") : рекомендуется для Stream Firestore to BigQuery и любых других наборов функций, которые станут доступны в npm. Основная логика упакована как стандартная библиотека NPM с использованием SDK Cloud Functions v2. Пользователи инициализируют стандартную кодовую базу Cloud Functions , устанавливают пакет, повторно экспортируют функции и развертывают их независимо с помощью CLI.
2. Создание форка и самостоятельное управление : рекомендуется для всех расширений, для которых нет набора функций в npm. Пользователи копируют или создают форк исходного кода расширения с открытым исходным кодом, переписывают триггеры в стандартные функции Firebase v2, используя навыки миграции с помощью ИИ или руководства, и берут на себя полную ответственность за кодовую базу и ее текущее обслуживание.

Какие расширения переносятся в функциональные наборы?

Расширение Stream Firestore to BigQuery было перенесено в набор функций, доступный в виде npm-пакета @firebase-function-kits/firestore-bigquery-export .

Почему для миграции требуется обновление с Cloud Functions версии 1 до версии 2?

Стандартная поддержка Cloud Functions v1 прекращается с выходом среды выполнения Node.js 22. Чтобы предотвратить «двойную миграцию», когда разработчики переходят с Firebase Extensions , а затем вынуждены проводить вторую ручную рефакторизацию после прекращения поддержки устаревших сред выполнения, Firebase настоятельно рекомендует немедленно обновить все перенесенные функции до SDK v2 во время этого перехода, и это обязательно для наборов функций.

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

Изменит ли переход на самостоятельно управляемые Cloud Functions систему выставления счетов клиентам?

В целом, нет. Развернутые расширения уже взимают плату с клиентов за используемые ими базовые ресурсы Google Cloud , такие как вызовы Cloud Functions , Cloud Storage или хранилище и запросы BigQuery . Однако в период миграции клиенты могут понести небольшие временные дополнительные расходы, если они будут запускать одновременно устаревшие Firebase Extensions и новую развернутую функцию-заменитель для обеспечения безопасного перехода.

Как осуществляется выставление счетов для клиентов Mandiant или других специализированных корпоративных аккаунтов?

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

Каков риск потери данных или простоя сервиса во время миграции?

Переход от управляемых ресурсов к самостоятельно управляемым кодовым базам сопряжен с незначительным риском прерывания работы сервиса или потери событий.

• Сбой триггеров : Если старые триггеры удаляются до того, как активируются новые, возникает пробел, из-за которого события (например, запись документов Cloud Firestore ) пропускаются и безвозвратно теряются. Мы рекомендуем развернуть комплект для замены и проверить его перед удалением расширения, чтобы избежать потери данных.
• Проблемы с правами доступа : Если в недавно развернутом коде отсутствуют необходимые права доступа IAM, такие операции, как запись в BigQuery , будут завершаться с ошибкой или аварийно завершаться во время выполнения. Мы добавили декларативную безопасность для функций, поэтому первое развертывание комплекта, выполненное учетной записью, которая может запрашивать и устанавливать роли, а также создавать учетную запись службы, должно решить эту проблему.

Как предотвратить потерю данных для критически важного расширения экспорта из Cloud Firestore в BigQuery ?

Для обеспечения безопасного перехода без потери данных служба поддержки должна рекомендовать пользователям использовать метод перекрытия, а не метод разрывов. Это вариант по умолчанию при миграции на комплекты:

1. Разверните комплект заменяющих функций, пока расширение еще установлено и работает. Подождите несколько минут, пока Eventarc полностью выполнит инициализацию.
2. Создайте тестовый документ в отслеживаемой коллекции Cloud Firestore и убедитесь, что новая самоуправляемая функция успешно записывает соответствующую строку в таблицу журнала изменений BigQuery (с новым идентификатором события).
3. После подтверждения работоспособности новой системы немедленно удалите или отключите устаревшее расширение, чтобы прекратить двойную запись.
4. Старайтесь максимально сократить окно пересечения, чтобы минимизировать затраты на дублирование обработки каждой операции записи и вероятность появления дублирующихся строк в исходном журнале изменений BigQuery .
5. В большинстве случаев таблица Raw Changelog ( *_raw_changelog ) будет дедуплицирована по insertID , и даже в тех случаях, когда в журнале изменений обнаруживаются повторяющиеся строки, последнее представление таблицы ( *_raw_latest ) будет корректным.

Более подробная информация о миграции этого расширения, а также о способах восстановления данных в случае их потери, содержится в файле README.md комплекта .

Что делать, если этап инициализации жизненного цикла завершился неудачей?

В рамках управляемого сервиса задачи настройки (такие как создание наборов данных BigQuery , таблиц и представлений) обрабатывались автоматически. В модели самоуправляемого NPM они запускаются с помощью функции очереди задач жизненного цикла; например, в firestore-bigquery-export она называется initBigQuerySync .

Если этот шаг не удастся или он не выполнится автоматически:

1. Убедитесь, что учетной записи службы выполнения Cloud Functions предоставлены необходимые роли IAM. Например, для firestore-bigquery-export это включает в себя:

   • Для создания ресурсов и вставки строк: roles/bigquery.dataEditor
   • Для запуска заданий и создания представлений: roles/bigquery.user
   • Чтобы поставить задачу подготовки в очередь: roles/cloudtasks.enqueuer

2. Убедитесь, что у вызывающего абонента есть права доступа roles/cloudtasks.enqueuer .

3. Повторно запустите команду инициализации жизненного цикла вручную с помощью интерфейса командной строки:

   firebase functions:lifecycle:run afterInstall KIT_INSTANCE_ID
   

4. Проверьте журналы Cloud Logging как для функции запуска, так и для выполнения очереди задач, чтобы выявить любые ошибки разрешений или конфигурации.

Как осуществляется перенос учетных данных Secret Manager ?

В рамках управляемой модели ресурсы Secret Manager автоматически привязывались к экземплярам расширений. При использовании команд ext:migrate или ext:export --mode functions для экспорта конфигурации расширений в набор функций мы блокируем управление этими секретами расширениями, поэтому они остаются в вашем проекте после удаления расширения. Если вы захотите удалить эти секреты в будущем, вам необходимо будет сделать это вручную в консоли Google Cloud .

Что произойдет, если пользователь захочет запустить несколько экземпляров перенесенного расширения?

Мы ввели наборы функций как способ поддержки нескольких экземпляров функции, аналогично тому, как можно иметь несколько версий расширения. Каждому набору будет присвоен уникальный идентификатор экземпляра набора, который аналогичен кодовой базе и может использоваться взаимозаменяемо с кодовыми базами в командах CLI. При развертывании все функции в экземпляре набора будут иметь префикс kit-<instance-id>- чтобы гарантировать уникальное имя каждой функции, аналогично префиксу ext-<extension-instance-id>- в расширениях. Чтобы узнать больше о том, как использовать наборы функций в процессе миграции, см. наше руководство по миграции пользователей .

При установке комплекта используется npm; а что, если я хочу использовать Yarn или другой менеджер пакетов, совместимый с Node?

В настоящее время у нас нет планов по поддержке Yarn или других менеджеров пакетов. Установка комплекта осуществляется путем непосредственного выполнения команд npm при настройке исходного кода комплекта при первой установке.

В качестве альтернативы вы можете создать исходный каталог, самостоятельно установить пакет npm kit и настроить его с соответствующими сборками и экспортами. Обратитесь к нашим шаблонам index-kit для TypeScript в firebase-tools или посмотрите пример установленного npm kit. После этого вы можете установить его как локальный kit, используя --directory вместо --package . В дальнейшем вам потребуется идентифицировать kit по каталогу или ID, но вы можете использовать команды kit для добавления и удаления экземпляров.

Моё расширение использует расширенные системные параметры репозитория Docker или ключа KMS; как это можно настроить в функциональных наборах?

В настоящее время мы не поддерживаем настройку репозитория Docker или ключа KMS в Cloud Functions for Firebase . Если вы переходите с расширения, в котором эти системные параметры уже настроены, и хотите сохранить эту функциональность, вы можете применить эти параметры к функциям вашего нового комплекта с помощью gcloud CLI .

Предварительные требования

1. Первоначально разверните свой набор функций, следуя инструкциям по миграции, чтобы функции существовали в Google Cloud .

2. Настройте переменные окружения в терминале:

   export PROJECT_ID="YOUR_PROJECT_ID"
   export FUNCTION_REGION="YOUR_REGION"          # e.g. us-east1
   export KIT_NAME="YOUR_KIT_NAME"                # e.g. firestore-bigquery-export
   export SOURCE_DIR="YOUR_KIT_SOURCE_DIR"       # e.g. "./function-kits/${KIT_NAME}/source"
   export REPO_NAME="YOUR_DOCKER_REPO_NAME"
   export KEY_RING="YOUR_KMS_KEY_RING"
   export KEY_NAME="YOUR_KMS_KEY_NAME"
   
   # Retrieve Project Number automatically
   export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
   

3. Создайте файл .gcloudignore в корневом каталоге исходного кода комплекта, чтобы скомпилированные файлы сборки не игнорировались файлом .gitignore :

   cat << 'EOF' > "${SOURCE_DIR}/.gcloudignore"
   .gcloudignore
   .git
   .gitignore
   
   node_modules
   #!include:.gitignore
   !lib/**
   EOF
   

4. Предоставьте необходимые разрешения IAM:

   • Для ключей KMS (предоставляют агентам службы доступ к расшифровке):

     for SERVICE_ACCOUNT in \
       "service-${PROJECT_NUMBER}@serverless-robot-prod.iam.gserviceaccount.com" \
       "service-${PROJECT_NUMBER}@gcf-admin-robot.iam.gserviceaccount.com" \
       "service-${PROJECT_NUMBER}@gcp-sa-artifactregistry.iam.gserviceaccount.com"
     do
       gcloud kms keys add-iam-policy-binding "$KEY_NAME" \
         --keyring="$KEY_RING" \
         --location="$FUNCTION_REGION" \
         --project="$PROJECT_ID" \
         --member="serviceAccount:${SERVICE_ACCOUNT}" \
         --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"
     done
     

   • Для Artifact Registry (предоставляет доступ на запись в Cloud Build и доступ на чтение в Cloud Run ):

     # Grant the Cloud Build / Compute Service Account permission to write images to the repository
     gcloud artifacts repositories add-iam-policy-binding "$REPO_NAME" \
       --location="$FUNCTION_REGION" \
       --project="$PROJECT_ID" \
       --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
       --role="roles/artifactregistry.writer"
     
     # Grant Cloud Run permission to pull images from the repository
     gcloud artifacts repositories add-iam-policy-binding "$REPO_NAME" \
       --location="$FUNCTION_REGION" \
       --project="$PROJECT_ID" \
       --member="serviceAccount:service-${PROJECT_NUMBER}@serverless-robot-prod.iam.gserviceaccount.com" \
       --role="roles/artifactregistry.reader"
     

Применение настроек с помощью gcloud CLI

Для каждой функции в вашем комплекте выполните gcloud functions deploy :

gcloud functions deploy FUNCTION_NAME \
  --project="$PROJECT_ID" \
  --region="$FUNCTION_REGION" \
  --source="./function-kits/${KIT_NAME}/source" \
  --docker-repository="projects/${PROJECT_ID}/locations/${FUNCTION_REGION}/repositories/${REPO_NAME}" \
  --kms-key="projects/${PROJECT_ID}/locations/${FUNCTION_REGION}/keyRings/${KEY_RING}/cryptoKeys/${KEY_NAME}"

Обратите внимание, что это обходное решение перестаёт работать при следующих условиях:

1. Новые экземпляры комплекта : добавление экземпляра в firebase.json создает новый ресурс Cloud Functions v2, который по умолчанию использует ключи, управляемые Google, и gcf-artifacts . Для каждого нового экземпляра необходимо запустить gcloud .
2. Пересоздание функции : изменение типа триггера (например, с HTTPS на триггер Cloud Firestore ), изменение точки входа или переименование приводят к тому, что Firebase CLI удаляет старую функцию и создает новую. Новая функция теряет эти настройки до тех пор, пока вы снова не запустите gcloud .
3. Разница в конфигурации : Firebase CLI не отображает статус репозиториев KMS или Docker в логах firebase functions:list или diff, что затрудняет аудит инфраструктуры.

Проверка успеха

Для подтверждения применения репозитория и ключа шифрования выполните следующую команду:

gcloud functions describe FUNCTION_NAME \
  --region="$FUNCTION_REGION" \
  --project="$PROJECT_ID" \
  --format="yaml(state, buildConfig.dockerRepository, kmsKeyName)"