Migrar as Extensões do Firebase para um kit de funções criado por você

Selecione o caminho de migração: Migrar para kits de funções no npm Migrar para um kit de funções criado por você

Se um editor não tiver criado um kit de substituição oficial distribuído no npm, este guia mostra as etapas para fazer um fork da extensão e configurá-la como um kit de funções local.

Verificar limitações conhecidas da migração

Antes de começar a migrar uma instância de extensão, verifique se a configuração usa algum dos seguintes recursos que exigem uma solução alternativa ou ainda não são compatíveis em kits de funções:

  • Os repositórios Docker personalizados e as chaves do KMS exigem uma solução alternativa manual O Cloud Functions for Firebase não é compatível com parâmetros de sistema de substituição para configurar um repositório Docker personalizado ou uma chave de criptografia gerenciada pelo cliente (chave do KMS). Se a configuração da extensão definir qualquer um desses parâmetros, consulte a solução alternativa para perguntas frequentes.

Antes de começar

Você precisa configurar a CLI Firebase e inicializar um projeto Firebase. Ao usar a CLI, verifique se você está usando a versão >= 15.32.0 do firebase-tools, que tem os novos comandos de migração e kit de funções.

Permissões e papéis necessários da conta

Dependendo do que precisa ser criado e configurado pela CLI Firebase durante a migração, a conta usada para autenticar com Firebase e Google Cloud precisa ter os seguintes papéis:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (se você precisar fazer setIamPermissions para endpoints públicos)
  • roles/secretmanager.admin (se estiver usando secrets)
  • roles/serviceusage.serviceUsageAdmin (se você precisar ativar novas APIs)

Recomendamos usar uma conta que já tenha instalado extensões e implantado funções, já que a maioria dessas permissões já terá sido concedida. Se a conta de migração precisar de mais papéis, siga as instruções do IAM Google Cloud para adicioná-los.

Fazer upgrade da instância de extensão para a versão mais recente

Você precisa atualizar a extensão para a versão mais recente para minimizar a diferença entre a instância da extensão e o kit de substituição. Se a extensão não for atualizada, poderá haver mudanças significativas e incompatíveis entre a instância da extensão e a substituição do kit. A configuração exportada pode não corresponder ao que o kit espera devido a mudanças de parâmetros em diferentes versões.

Use uma das seguintes opções para atualizar a extensão, dependendo de onde ela foi instalada:

  • No console do Firebase
  • Na CLI Firebase, use:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Se você pular esta etapa, a CLI vai pedir que você faça upgrade ao exportar a configuração se a extensão não estiver na versão mais recente.

Fazer um fork da extensão em um kit de funções local

Antes de começar a converter uma extensão em um kit de função local, verifique se o código-fonte da extensão está dentro do projeto Firebase. Para fazer isso, clone o repositório de extensão do GitHub, crie um diretório dentro da raiz do projeto Firebase e copie a pasta functions/ e o extension.yaml da extensão para ele:

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

Siga as etapas de 1 a 8 do guia de migração para editores para migrar o código-fonte da extensão para uma função de 2ª geração. Depois, siga estas etapas.

Fazer com que seu kit local seja compatível com a região da função exportada e parâmetros avançados

Em um kit de funções local, a CLI Firebase não gera um arquivo index.ts para configurar o pacote e configurá-lo para usar parâmetros de sistema migrados. Para usar a região da função e os parâmetros avançados configurados para sua extensão, configure o arquivo index.ts para ler o formato exportado por firebase ext:export --mode functions em um arquivo de variável de ambiente.

Especificamente, no arquivo index.ts de nível superior que exporta suas funções, defina um parâmetro para FUNCTION_DEFAULT_REGION e chame setGlobalOptions com variáveis de ambiente do tipo EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>, semelhante ao modelo index-kit-migration.ts usado pela 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";

Teste seu kit antes da migração

Agora você tem um kit de funções local que, quando implantado, se comporta de maneira idêntica a uma nova instalação da sua extensão. A próxima etapa é verificar e corrigir problemas introduzidos acidentalmente ao longo do caminho antes de migrar as instâncias de extensão de produção para ele.

Primeiro, adicione seu fork como um kit local, configure e implante em um projeto de teste. Os kits de funções locais precisam estar dentro do projeto Firebase. Portanto, se o repositório de extensão clonado estiver fora do projeto Firebase, mova-o para dentro do diretório do projeto. Em seguida, execute o comando de instalação do kit a seguir para instalá-lo como um kit local:

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

Esse comando orienta você na escolha de um ID do kit, um ID da instância e uma configuração para sua primeira instância de teste. Em seguida, ele modifica o arquivo firebase.json para registrar um kit local que aponta para o diretório bifurcado, com configurações para cada instância armazenada em um arquivo .env em function-kits/<kit-id>/config-<instance-id>.

Implante seu kit local em um projeto de teste com os recursos adequados para testar o comportamento dele. Se você já tiver um projeto de teste configurado para testar sua extensão, execute o seguinte comando:

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

Exemplo prático:transmitir Cloud Firestore para BigQuery (firestore-bigquery-export)

Verifique a sincronização de ponta a ponta do Cloud Firestore para o BigQuery:

  1. Na página Cloud Firestore do console Firebase, crie a coleção que você definiu como COLLECTION_PATH (users) se ela ainda não existir.
  2. Crie um documento chamado bigquery-mirror-test com campos e valores.

  3. Na página BigQuery do console Google Cloud, consulte a tabela de mudanças bruta. Ele precisa conter uma única linha registrando a criação do documento:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Consulte a visualização mais recente, que vai retornar o evento de mudança mais recente do único documento presente (bigquery-mirror-test):

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Exclua o documento bigquery-mirror-test em Cloud Firestore. Ele desaparece da visualização mais recente, e um evento DELETE é anexado à tabela bruta do changelog.

    É possível inspecionar o histórico completo de um único documento com:

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

Diferenças em relação ao teste da extensão:

  • O gatilho é implantado como kit-<kit-instance-id>-fsexportbigquery, não ext-<instanceId>-fsexportbigquery. Procure esse nome no painel e nos registros de Cloud Functions.
  • Seu código é executado no Firebase Local Emulator Suite como funções padrão. É possível definir valores de parâmetros para usar no emulador com .env.local. Você também pode testar seu código usando o SDK firebase-functions-test, conforme descrito em Testes de unidade de Cloud Functions.
  • O provisionamento não é mais feito pelo tempo de execução das extensões. Se a tabela de changelog estiver faltando após a implantação, execute novamente a tarefa de configuração manualmente: firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>. A tarefa é idempotente. Portanto, ao executá-la novamente, o conjunto de dados, a tabela e as visualizações são reconciliados.
  • Os valores de parâmetro vêm de .env em vez do formulário de instalação. Portanto, as novas execuções de firebase deploy não são interativas depois que .env é concluído.

(Opcional) Limpar após o teste

Se quiser remover essa instância de teste depois do teste, desinstale-a:

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

Isso exclui todos os recursos da nuvem criados ao implantar o kit e remove a configuração da instância dele. Se você tiver apenas uma instância do kit, isso também vai remover a entrada dele de firebase.json. Ele não exclui o diretório local de código-fonte. Ao instalar o kit para a migração de produção, você pode escolher um ID de kit novamente.

Migrar das extensões para o kit local

Agora que o kit local foi testado, é possível migrar a instância da extensão implantada em produção.

1. Instalar a instância do kit de funções de substituição

Instale o kit de função local, transmitindo --no-configure para pular a configuração manual para que a próxima etapa possa exportar a configuração de extensão diretamente para esta instância do kit:

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

2. Configure a instância do kit de funções de forma idêntica à extensão

É necessário personalizar essa instância do kit com uma configuração idêntica à extensão que ela está substituindo. É possível exportar a configuração da instância da extensão para um arquivo .env, que armazena dados de configuração de parâmetros, variáveis de ambiente e referências secretas para todos os Cloud Functions, incluindo kits. Para exportar diretamente para o arquivo de configuração do seu kit, execute:

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

Ao final desta etapa, as informações de configuração da instância serão armazenadas em um arquivo .env específico do projeto no diretório de configuração da instância, como function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

3. Implantar e verificar a substituição do kit

Agora que o kit está instalado e disponível como um conjunto de funções, você pode fazer o deployment da substituição do kit. Os kits de funções funcionam como funções padrão, em que cada instância do kit atua como uma base de código separada para organizar suas funções. Você pode implantar todas as suas funções ou apenas uma instância de kit específica. Ao migrar uma única instância de extensão, implante apenas essa instância do kit.

Se o kit usar novos parâmetros que não estavam presentes na instância da extensão de que você migrou, a CLI Firebase vai pedir esses parâmetros no início do processo de implantação. Isso não é esperado neste exemplo prático de uma extensão firestore-bigquery-export atualizada, mas muitos kits solicitam um novo parâmetro para qualquer origem de acionamento de evento usada pelo kit. Como parte dessa migração, os kits atualizados usam funções de 2ª geração, enquanto as extensões usavam funções de 1ª geração. Na 2ª geração, as funções ficam perto das fontes de eventos e são adicionadas como um parâmetro extra. Em atualizações futuras, se novos parâmetros forem adicionados, a CLI vai pedir que você os inclua na próxima implantação.

Exemplo prático:

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

Saída:

=== 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 se o firebase deploy do kit não teve erros, confira os registros de implantação para saber se algum hook de ciclo de vida foi acionado. Extensões populares, como Stream Cloud Firestore para BigQuery, usam hooks de ciclo de vida. Confira abaixo um exemplo de como um hook de ciclo de vida aparece quando é acionado:

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

Essas mensagens de registro confirmam o seguinte:

  • Um hook de ciclo de vida foi encontrado e executado.
  • Uma tarefa foi enfileirada na fila de tarefas associada ao hook do ciclo de vida.
  • Um link para o Cloud Logging foi fornecido para que você possa validar se a tarefa foi concluída sem erros.

Siga o link de registros até o console Google Cloud para validar se não há erros nos registros e se o evento da fila de tarefas foi processado corretamente. Se o evento de ciclo de vida não for executado corretamente, você poderá acioná-lo novamente executando:

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

Se você estiver implantando uma instância do kit de funções pela primeira vez, execute:

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

Se, a qualquer momento durante a validação, você decidir interromper ou desfazer essa migração, desinstale o kit seguindo as instruções em Desinstalar a extensão.

4. Desinstalar a extensão

Depois de verificar o kit de funções implantado, desinstale a extensão para não duplicar o comportamento dela uma vez para o kit e outra para a extensão. É possível desinstalar todas as extensões da CLI Firebase independente de como elas foram instaladas se você transmitir a flag --immediate:

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

Exemplo prático:

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

Saída:

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

Migrações avançadas

Você pode ter extensões em vários projetos do Firebase que quer gerenciar com uma única base de código. Por exemplo, se você implantar a mesma infraestrutura em um ambiente testing e um ambiente production, cada um com uma instância documents Cloud Firestore que você exporta para BigQuery, é possível ter duas instâncias da extensão firestore-bigquery-export instaladas:

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

Se você migrou essas duas instâncias de extensão para duas instâncias do kit de funções em uma única base de código ao trabalhar com a CLI Firebase e implantou usando firebase deploy --project testing e firebase deploy --project production, cada implantação criaria duas instâncias nos ambientes testing e production.

Em vez disso, substitua as duas instâncias de extensão por uma instância do kit de funções firestore-bigquery-export implantada em vários projetos, em que cada projeto tem a própria configuração. O diretório de configuração da instância deve ter esta aparência:

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

Cada implantação em testing e production cria uma instância do seu kit com a configuração correspondente. Os comandos da CLI atuais criam essa configuração desde que você transmita a flag --project em cada invocação de ext:migrate ou functions:kits:install.

Exemplo prático:

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

Agora você tem uma única instância do kit configurada para implantação nos projetos testing e production com as respectivas configurações. Se você criar uma instância no projeto testing e executar o comando functions:kits:install para o mesmo pacote no projeto production, vai aparecer a opção de reutilizar a instância configurada para testing ou instalar uma segunda instância.