Как настраивать серверные части App Hosting и управлять ими

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

Как задавать и обновлять переменные среды и секреты

App Hosting позволяет использовать переменные среды для неконфиденциальных значений конфигурации и секреты для конфиденциальных параметров, таких как ключи API, учетные данные базы данных и токены сервисов.

  • Стандартные переменные среды. Используются для неконфиденциальных конфигураций в виде обычного текста, например общедоступных URL API, флагов функций или целей сборки. Значения видны всем участникам проекта.
  • Секреты. Используются для конфиденциальных параметров, таких как секретные коды клиентов OAuth, токены API или пароли баз данных. Секреты поддерживаются Cloud Secret Manager. Значения секретов защищены и никогда не отображаются в виде обычного текста в консоли Firebase. Вместо этого в консоли предоставляются ссылки на контент для просмотра значений секретов и управления ими непосредственно в Cloud Secret Manager.

Определять параметры среды и управлять ими можно двумя способами:

  • Консоль Firebase. Быстро добавляйте, редактируйте и прикрепляйте секреты или переменные динамически во время первоначального создания бэкенда или после развертывания в настройках бэкенда.

  • Сначала код (apphosting.yaml). Объявите переменные среды и ссылки на секреты в файле конфигурации репозитория для развертываний с контролем версий или используйте apphosting.<env>.yaml, чтобы задать разные значения для разных сред.

Консоль Firebase

Скриншот диалогового окна консоли Firebase для добавления переменных среды

apphosting.yaml 

env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
  - variable: API_KEY
    secret: myApiKeySecret

Управление переменными и секретами в консоли Firebase

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

Как настроить переменные и секреты при создании бэкенда

При создании нового бэкенда App Hosting в консоли Firebase вы можете настроить стандартные переменные среды и секреты на шаге Настройка бэкенда мастера настройки:

  1. В консоли Firebase перейдите в раздел Hosting & Serverless (Хостинг и бессерверная архитектура) > App Hosting (Хостинг приложений) и нажмите Create backend (Создать серверную часть).
  2. Выполните начальные шаги мастера, чтобы выбрать основной регион и репозиторий кода.
  3. В разделе Настройка серверной части найдите сворачиваемые карточки Переменные среды и Секреты, где можно добавить стандартные переменные и прикрепить секреты.
  4. Завершите работу с мастером создания серверной части и нажмите Finish & deploy (Завершить и развернуть).

Управление переменными и секретами в настройках бэкенда

Вы можете просматривать, добавлять, изменять и удалять переменные среды и секреты для активных бэкендов на панели настроек бэкенда.

  1. В консоли Firebase выберите серверную часть App Hosting и откройте Settings (Настройки) > Environment (Среда).
  2. Проверьте существующие конфигурации в таблице Переменные среды:
    • Стандартные переменные. Значения отображаются в виде обычного текста в блоках кода, которые можно скопировать.
    • Секреты. Отображаются в виде кликабельной ссылки с названием секрета (открывает Cloud Secret Manager в консоли Google Cloud) и его целевой версией (например, latest или определенным номером версии, таким как 2).
  3. Чтобы добавить переменную или секрет:
    1. Нажмите Добавить.
    2. На шаге 1 выберите Стандартная переменная среды (для неконфиденциальных данных, видимых всем участникам проекта) или Секрет (для ключей API и конфиденциальных учетных данных с ограниченным доступом), а затем нажмите Далее.
    3. На шаге 2 введите название ключа и либо значение в виде обычного текста (для стандартных переменных), либо идентификатор и версию секрета (для секретов).
    4. Сохраните изменения, выбрав один из следующих вариантов:
      • Сохранить и развернуть. Конфигурация серверной части будет немедленно обновлена, а также будет запущена новая сборка и развертывание.
      • Просто сохранить (в значке раскрывающегося списка рядом с кнопкой Сохранить и развернуть). Изменения конфигурации будут сохранены, но немедленного развертывания не произойдет. Обновленные настройки вступят в силу при следующем развертывании.
  4. Чтобы изменить или удалить существующую запись, нажмите на меню Дополнительные действия (...) в конце строки.
    • Выберите Изменить, чтобы изменить ключ, значение, сопоставление секретов или версию, а затем нажмите Сохранить и развернуть или Сохранить.
    • Нажмите Удалить и подтвердите действие в диалоговом окне.

Перенос переменных из файлов dotenv

Для приложений Next.js файлы dotenv, содержащие переменные среды, работают с App Hosting.

При создании или обновлении бэкенда вы можете перенести переменные среды из файла dotenv в консоль Firebase. Для этого скопируйте все содержимое файла dotenv и вставьте его в первое поле Ключ в форме Добавить в разделе Настройки > Среда.

Все переменные среды, скопированные таким образом, автоматически форматируются в форму без необходимости вводить каждую из них по отдельности, если входные данные используют стандартное форматирование KEY=value:

KEY1=value1
KEY2=value2
KEY3=value3

Для сложного или детального управления переменными среды в любом фреймворке рекомендуем использовать apphosting.yaml.

Управление переменными и секретами в apphosting.yaml

Для рабочих процессов, ориентированных на код, объявите стандартные переменные среды и ссылки на секреты в ключе env: в файле конфигурации apphosting.yaml репозитория проекта (см. раздел Создание и редактирование apphosting.yaml).

env:
  # Standard environment variables
  - variable: PUBLIC_API_URL
    value: https://api.example.com
    availability:
      - BUILD
      - RUNTIME
  - variable: FEATURE_FLAG_NEW_UI
    value: "true"

  # Secret references backed by Cloud Secret Manager
  - variable: DATABASE_URL
    secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
  - variable: GEMINI_API_KEY
    secret: myGeminiApiKeySecret@1

Каждая запись в env: поддерживает следующие поля:

  • variable – имя переменной среды, доступной процессу приложения.
  • value – строковое значение в виде обычного текста (для стандартных переменных среды).
  • secret – ссылка на секрет Cloud Secret Manager (для секретов). Вы можете использовать короткое название секрета (например, myGeminiApiKeySecret или закрепленное myGeminiApiKeySecret@1) или полный путь к ресурсу (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION). Подробнее о том, как хранить секретные параметры и получать к ним доступ…
  • availability определяет, доступна ли переменная или секрет на этапе BUILD, RUNTIME или на обоих.

Как настроить доступность переменных

Переменные среды и секреты, настроенные в консоли Firebase, доступны как во время сборки, так и во время выполнения. Это также режим работы по умолчанию для записей, определенных в apphosting.yaml, если вы не сузите область действия с помощью свойства availability. В apphosting.yaml (но не в консоли) вы можете ограничить переменную или секрет только средой сборки (BUILD) или только средой выполнения (RUNTIME).

Как получить доступ к переменным и секретам в коде приложения

Независимо от того, где вы настраиваете переменные среды и секреты – в консоли Firebase или apphosting.yaml, они доступны среде выполнения приложения как стандартные переменные среды (например, process.env в Node.js).

// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;

// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;

export async function fetchData() {
  const response = await fetch(`${apiUrl}/data`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  return response.json();
}
  • Доступ на стороне сервера. Все переменные среды и секреты доступны в контекстах выполнения на стороне сервера (например, в компонентах сервера Next.js, маршрутах API или обработчиках серверной части Node.js).

  • Доступ на стороне клиента. Чтобы стандартные переменные среды были доступны браузеру в таких фреймворках, как Next.js, убедитесь, что ключ переменной соответствует соглашениям фреймворка (например, имеет префикс NEXT_PUBLIC_).

    env:
  - variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

Иерархия переменных

Firebase App Hosting применяет переменные среды и секреты в порядке приоритета, основанном на их источнике. Конфигурации, заданные в консоли Firebase, всегда переопределяют параметры, объявленные в файлах apphosting.yaml и dotenv. Если переменная среды или секретный ключ с одним и тем же названием существует и в apphosting.yaml, и в консоли Firebase, то во время сборки и выполнения приоритет будет иметь значение из консоли.

Ниже приведен полный порядок приоритета.

  1. Консоль Firebase – переменные и секреты, заданные в консоли.
  2. apphosting.<env>.yaml – переменные и секреты, указанные в YAML-файле для конкретной среды, например apphosting.staging.yaml (см. раздел Развертывание нескольких сред).
  3. apphosting.yaml – переменные и секреты, указанные в файле apphosting.yaml.
  4. Система Firebase – переменные, заданные Firebase и содержащие значения для FIREBASE_CONFIG или FIREBASE_WEBAPP_CONFIG, а также переменные среды, которые задают имена хостов и порты для приложений SSR (задаются адаптерами App Hosting в bundle.yaml).

Автоматически заполняемые переменные среды

Переменные среды автоматически заполняются App Hosting. К ним относятся переменные, заполняемые Google Cloud, а также переменные среды, относящиеся к Firebase, если во время настройки на сервере задана переменная appId.

  • FIREBASE_CONFIG (доступно в средах сборки и выполнения) – предоставляет следующую информацию о конфигурации проекта Firebase:

    {
  "databaseURL": "https://DATABASE_NAME.firebaseio.com",
  "storageBucket": "PROJECT_ID.firebasestorage.app",
  "projectId": "PROJECT_ID"
}

    Эта конфигурация применяется автоматически, когда вы инициализируете Firebase Admin SDK без аргументов.

  • FIREBASE_WEBAPP_CONFIG (доступно только в среде сборки) – предоставляет следующую информацию о конфигурации проекта Firebase:

    {
  "apiKey": "API_KEY",
  "appId": "APP_ID",
  "authDomain": "AUTH_DOMAIN.firebaseapp.com",
  "databaseURL": "https://DATABASE_NAME.firebaseio.com",
  "messagingSenderId": "PROJECT_NUMBER",
  "projectId": "PROJECT_ID",
  "storageBucket": "PROJECT_ID.firebasestorage.app"
}</span>

    Firebase JS SDK автоматически проверяет эту FIREBASE_WEBAPP_CONFIG переменную среды в скрипте postinstall во время сборки, что позволяет инициализировать клиентский SDK без аргументов.

Подробнее о том, как использовать эти переменные среды для инициализации SDK, рассказывается в статье Автоматическая инициализация Firebase Admin SDK и веб-SDK.

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

Иерархия переменных

Firebase App Hosting применяет переменные в порядке приоритета в зависимости от их источника. Например, значения, заданные в консоли Firebase, всегда переопределяют значения, заданные в файлах apphosting.yaml и dotenv.

Ниже приведен полный порядок приоритета.

  1. Firebase console – переменные, заданные в консоли.
  2. apphosting.<env>.yaml – переменные, указанные в YAML-файле для конкретной среды, например apphosting.staging.yaml (см. раздел Развертывание нескольких сред).
  3. apphosting.yaml – переменные, указанные в файле apphosting.yaml.
  4. Система Firebase – переменные, заданные Firebase, которые содержат значения для firebase_config json или firebase_webapp_config, а также переменные среды, которые задают имена хостов и порты для приложений SSR (задаются адаптерами App Hosting в bundle.yaml).

Зарезервированные названия и ограничения

Переменные среды, определенные в контракте среды выполнения контейнера Cloud Run, зарезервированы и не могут быть заданы.

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

Некоторые ключи переменных среды зарезервированы для внутреннего использования. Не используйте в файлах конфигурации следующие ключи:

  • Пустые строки ("")
  • Ключи, содержащие символ "="
  • Ключи, начинающиеся с X_FIREBASE_, X_GOOGLE_ или CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Повторяющиеся ключи

Создание и редактирование apphosting.yaml

Для расширенной настройки, например секретов или параметров среды выполнения, таких как параллелизм, ЦП и ограничения памяти, вам нужно будет создать и отредактировать файл apphosting.yaml в корневом каталоге вашего приложения. Этот файл поддерживает ссылки на секреты, управляемые с помощью Cloud Secret Manager, что делает его безопасным для проверки в системе контроля версий.

Чтобы создать apphosting.yaml, выполните следующую команду:

firebase init apphosting

Будет создан базовый файл apphosting.yaml с примером конфигурации (закомментированным). После редактирования типичный файл apphosting.yaml может выглядеть следующим образом, с настройками для сервиса Cloud Run бэкенда, некоторыми переменными среды и некоторыми ссылками на секреты, управляемые Cloud Secret Manager:

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

В этом руководстве вы найдете подробную информацию и контекст для этих примеров настроек.

Настройте параметры сервиса "Cloud Run"

С помощью настроек apphosting.yaml вы можете задать параметры инициализации сервиса Cloud Run. Доступные настройки для сервиса Cloud Run указаны в объекте runConfig:

Обратите внимание, что параметры cpu, memoryMiB и concurrency имеют взаимозависимые ограничения (например, для конфигураций с большим объемом памяти требуются более высокие минимальные ограничения ЦП, а для дробных ЦП требуется параллелизм 1). Допустимые диапазоны и необходимые комбинации приведены в документации Cloud Run по ограничениям ЦП и ограничениям памяти.

Переопределить скрипты сборки и запуска

App Hosting определяет команды сборки и запуска приложения на основе обнаруженного фреймворка. Если вы хотите использовать собственную команду сборки или запуска, вы можете переопределить значения по умолчанию для App Hosting в apphosting.yaml.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

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

Используйте переопределение команды запуска, если вы хотите запустить приложение с помощью определенной команды, отличной от команды, выведенной App Hosting.

Настроить выходные данные сборки

По умолчанию App Hosting оптимизирует развертывание приложения, удаляя неиспользуемые выходные файлы, указанные фреймворком. Если вы хотите дополнительно оптимизировать размер приложения или игнорировать оптимизацию по умолчанию, вы можете переопределить ее в apphosting.yaml.

outputFiles:
  serverApp:
    include: [dist, server.js]

Параметр include принимает список каталогов и файлов, связанных с корневым каталогом приложения, которые необходимы для развертывания приложения. Если вы хотите сохранить все файлы, задайте для параметра include значение [.], и все файлы будут развернуты.

Хранение секретных параметров и доступ к ним

Конфиденциальная информация, например ключи API, должна храниться в секретах. Вы можете прикрепить секреты к серверной части в консоли Firebase или сослаться на них в apphosting.yaml, чтобы не добавлять конфиденциальную информацию в систему управления исходным кодом.

Параметры типа secret представляют собой строковые параметры, значение которых хранится в Cloud Secret Manager. Вместо того чтобы получать значение напрямую, секретные параметры проверяют наличие в Cloud Secret Manager и загружают значения во время развертывания.

env:
  - variable: API_KEY
    secret: myApiKeySecret

У секретов в Cloud Secret Manager может быть несколько версий. По умолчанию значение секретного параметра, доступного вашему работающему бэкенду, привязано к последней доступной версии секрета на момент создания бэкенда. Если у вас есть требования к управлению версиями и жизненным циклом параметров, вы можете закрепить определенные версии в консоли Firebase или в apphosting.yaml. Например, чтобы закрепить версию 5 в apphosting.yaml:

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Вы можете создать секреты с помощью команды CLI Firebase firebase apphosting:secrets:set. Вам будет предложено добавить необходимые разрешения. В этом случае вы сможете автоматически добавить ссылку на секрет в apphosting.yaml.

Предоставьте доступ к Cloud Secret Manager

Чтобы App Hosting мог получать секретные значения во время сборки и развертывания среды выполнения, у сервисного аккаунта бэкенда App Hosting должно быть разрешение на доступ к Cloud Secret Manager.

Если вы создаете секреты с помощью консоли Cloud Secret Manager или интерфейса командной строки gcloud, а не firebase apphosting:secrets:set, предоставьте доступ к серверной части с помощью интерфейса командной строки Firebase:

firebase apphosting:secrets:grantaccess SECRET_NAME

Вы также можете назначить роль Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) агенту сервиса App Hosting (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) или сервисному аккаунту среды выполнения бэкенда с помощью CLI gcloud:

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

Доступ к консоли и разрешения на основе ролей

Консоль Firebase динамически ограничивает функции управления средой и Secret Manager в зависимости от разрешений IAM пользователя:

  • Роль наблюдателя. Пользователи с разрешением на чтение могут просматривать существующие настройки конфигурации, но не могут вносить изменения.
    • Во время создания серверной части кнопка Create backend (Создать серверную часть) отключена.
    • В разделе Settings (Настройки) > Environment (Среда) кнопка Add new (Добавить) отключена, а меню строк More actions (Ещё) (...) скрыты.
  • Отсутствие разрешений Secret Manager. Пользователи, у которых нет разрешений IAM на взаимодействие с Cloud Secret Manager, увидят в консоли предупреждение Запросите у владельца проекта разрешение на добавление секретов.
    • При создании бэкенда карточка Секреты отключена.
    • В разделе Settings (Настройки) > Environment (Среда) параметр Secret (Секрет) отключен, если нажать Add new (Добавить), а некоторые параметры в меню More actions (Дополнительные действия) (...) скрыты для существующих секретных записей.

Настройте доступ к VPC

Бэкенд App Hosting может подключаться к сети виртуального частного облака (VPC). Подробную информацию и пример можно найти в статье Как подключить Firebase App Hosting к сети VPC.

Чтобы настроить доступ, используйте сопоставление vpcAccess в файле apphosting.yaml. Укажите полное название сети или коннектора или идентификатор. Использование идентификаторов позволяет переносить данные между тестовой и рабочей средами с разными коннекторами и сетями.

Конфигурация прямого исходящего трафика VPC (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

Конфигурация бессерверного коннектора (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Управление бэкендами

Команды для базового управления бэкендами App Hosting доступны в консоли Firebase и CLI Firebase. В этом разделе описаны некоторые из наиболее распространенных задач управления, включая создание и удаление бэкендов.

Создание серверной ВМ

Бэкенд App Hosting – это набор управляемых ресурсов, которые App Hosting создает для сборки и запуска веб-приложения.

Консоль Firebase. Перейдите в раздел Hosting & Serverless (Хостинг и бессерверная архитектура) > App Hosting (Хостинг приложений) и нажмите Create backend (Создать серверную часть). Если это первая серверная часть в вашем проекте Firebase, нажмите Get started (Начать).

Firebase CLI (версии 13.15.4 или более поздней). Чтобы создать серверную часть, выполните следующую команду из корневого каталога локального проекта, указав идентификатор проекта в качестве аргумента:

firebase apphosting:backends:create --project PROJECT_ID

В консоли или CLI следуйте инструкциям, чтобы выбрать регион, настроить подключение к GitHub и задать следующие базовые настройки развертывания:

  • Укажите корневой каталог приложения (по умолчанию – /).

    Обычно именно там находится файл package.json.

  • Как настроить активную ветку

    Это ветвь хранилища GitHub, которая развертывается на URL опубликованной страницы. Часто это ветка, в которую объединяются ветки функций или ветки разработки.

  • Принять или отклонить автоматическое развертывание.

    Автоматическое развертывание включено по умолчанию. После создания бэкенда вы можете сразу развернуть приложение в App Hosting.

  • Укажите название бэкенда.

  • Выберите среду выполнения. По умолчанию выбрана последняя рекомендуемая версия Node.js.

    • Настройте автоматическое обновление базового образа. Функция ABIU включена по умолчанию и автоматически применяет исправления системы безопасности к вашей среде. Чтобы отказаться от ABIU, выберите "Не указано" в качестве среды выполнения.

Удаление серверной ВМ

Чтобы полностью удалить бэкенд, сначала удалите его в консоли Firebase или с помощью CLI Firebase, а затем вручную удалите связанные ресурсы. Будьте осторожны, чтобы не удалить ресурсы, которые могут использоваться другими бэкендами или другими аспектами вашего проекта Firebase.

Консоль Firebase. В меню Settings (Настройки) выберите Delete backend (Удалить серверную часть).

Firebase CLI (версия 13.15.4 или более поздняя)

  1. Чтобы удалить бэкенд App Hosting, выполните следующую команду: Это отключит все домены для вашего бэкенда и удалит связанный сервис Cloud Run:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (Необязательно.) На вкладке консоли Google Cloud для Artifact Registry удалите образ для своего бэкенда в firebaseapphosting-images.

  3. В Cloud Secret Manager удалите все секреты, в названии которых есть "apphosting". Убедитесь, что эти секреты не используются другими серверными частями или другими аспектами вашего проекта Firebase.