Perguntas frequentes sobre a descontinuação das Extensões do Firebase

Por que estamos descontinuando o Firebase Extensions?

Devido a mudanças e descontinuações futuras na nossa infraestrutura Google Cloud subjacente, vamos desativar o serviço Firebase Extensions gerenciado.

As extensões implantadas vão parar de funcionar depois de 31 de março de 2027?

Não. As extensões já implantadas são executadas diretamente na infraestrutura padrão do Google Cloud (como Cloud Functions, Eventarc, Cloud Run e Cloud Tasks) e vão continuar sendo executadas indefinidamente.

No entanto, após 31 de março de 2027, não será mais possível atualizar, reconfigurar ou desinstalar essas extensões pelo console ou pela CLI do Firebase. Você também não poderá mais baixar as configurações de extensão para ajudar na migração para um kit de funções. Recomendamos migrar ou exportar a configuração da extensão até 31 de março de 2027.

O que acontece se um usuário não fizer nada?

Se um usuário não fizer nada, as funções implantadas vão continuar sendo executadas como recursos padrão. No entanto, após 31 de março de 2027:

1. Eles não podem mudar parâmetros de configuração nem atualizar variáveis de ambiente.
2. Não é possível aplicar correções de bugs, patches de segurança ou upgrades de dependência.
3. Não é possível fazer o download da configuração da extensão para ajudar a configurar um kit de funções de substituição de forma idêntica.
4. A maioria das extensões é criada no SDK legado do Cloud Functions v1, que está vinculado a ambientes de execução mais antigos do Node.js. Quando esses runtimes legados forem totalmente desativados pelo Google Cloud, as funções poderão parar de ser executadas ou ser desativadas. Consulte Suporte ao ambiente de execução.

Algo vai substituir as Extensões do Firebase?

Adicionamos muitos recursos ao Cloud Functions para que ele possa substituir as extensões. Principalmente kits de funções, que podem ser distribuídos usando npm e permitem implantar várias instâncias de funções, semelhante a como você poderia instalar extensões várias vezes em um único projeto.

No entanto, cabe a cada editor de extensão determinar se quer publicar uma substituição oficial do kit de funções no npm. Como as extensões são de código aberto, se o editor não quiser fazer uma substituição oficial, qualquer desenvolvedor poderá fazer um fork para criar uma substituição não oficial com Cloud Functions usando nossas APIs de 2ª geração no SDK do Node.

Os publishers que quiserem fazer uma substituição precisam seguir as instruções no guia de migração para publishers.

Os usuários que quiserem aproveitar os pacotes de substituição oficiais ou criar os próprios podem seguir as instruções no guia de migração para usuários.

O que devo fazer como usuário de uma extensão?

Se você usa extensões e não usa mais as instaladas, desinstale antes de 31 de março de 2027.

Após o desativamento, o botão "Desinstalar" no console Firebase e os comandos da CLI correspondentes serão removidos. Exclua manualmente todos os recursos Google Cloud associados, incluindo os segredos Cloud Functions, Secret Manager, as filas Cloud Tasks e as contas de serviço personalizadas do IAM, usando o console Google Cloud.

No entanto, se você usa ativamente as extensões instaladas, recomendamos migrar para kits de funções. Para migrar para kits de funções, siga as instruções do nosso guia de migração para usuários.

Você pode optar por não migrar para os kits de funções. Nesse caso, recomendamos que você atualize todas as extensões para as versões mais recentes, mantenha-as atualizadas e exporte as configurações de extensão atuais caso queira migrar depois.

O que devo fazer como editor de extensões?

Recomendamos migrar as extensões publicadas para kits de funções publicados no npm. Comece migrando sua extensão para funções de 2ª geração, que é um pré-requisito para criar um kit de funções. Isso envolve empacotar a lógica da extensão usando o SDK Cloud Functions v2. Atualizamos o SDK Cloud Functions v2 com suporte a recursos como segurança declarativa e eventos do ciclo de vida. Agora é possível migrar seu código de extensão atual para uma função de 2ª geração com mudanças mínimas na lógica de negócios principal. Essas funções podem ser publicadas usando um pacote npm. Para mais detalhes, consulte nosso guia de migração para editores.

E se eu tiver outras dúvidas?

Os usuários com dúvidas podem consultar nosso guia de migração de usuários. Se você ainda tiver dúvidas depois de usar o guia, entre em contato com o suporte do Firebase.

Os editores que tiverem dúvidas sobre como migrar Firebase Extensions podem usar nosso guia de migração para editores. Este guia inclui instruções sobre como ficar informado sobre atualizações e receber ajuda para oferecer uma alternativa às suas extensões publicadas.

Quais são os principais caminhos de migração disponíveis?

A partir de setembro de 2026, o Firebase vai oferecer suporte oficial a dois caminhos principais de migração:

1. Migrar para uma função compartilhada do NPM ("kit de funções"): recomendado para fazer streaming do Firestore para o BigQuery e qualquer outro kit de funções que fique disponível no npm. A lógica principal é empacotada como uma biblioteca NPM padrão usando o SDK Cloud Functions v2. Os usuários inicializam uma base de código Cloud Functions padrão, instalam o pacote, reexportam as funções e as implantam de forma independente usando a CLI.
2. Fork e autogerenciamento: recomendado para todas as extensões que não têm um kit de funções disponível no npm. Os usuários copiam ou bifurcam o código-fonte da extensão de código aberto, refatoram os gatilhos em funções padrão do Firebase v2 usando habilidades de migração de IA de melhor esforço ou guias manuais e assumem a propriedade total da base de código e da manutenção contínua dela.

Quais extensões estão sendo migradas para kits de funções?

A extensão Transmitir o Firestore para o BigQuery foi migrada para um kit de funções disponível como o pacote npm @firebase-function-kits/firestore-bigquery-export.

Por que a migração exige um upgrade da v1 para a v2 do Cloud Functions?

O suporte padrão do Cloud Functions v1 termina com o ambiente de execução do Node.js 22. Para evitar uma "migração dupla", em que os desenvolvedores migram do Firebase Extensions apenas para serem forçados a uma segunda refatoração manual quando os runtimes legados forem desativados, o Firebase recomenda fazer upgrade de todas as funções migradas para o SDK v2 imediatamente durante essa transição. Isso é necessário para os kits de funções.

Como usuário das extensões, você também pode criar seus próprios kits de funções usando o guia de migração para usuários.

A migração para o Cloud Functions autogerenciado vai mudar o faturamento de um cliente?

Em geral, não. As extensões implantadas já cobram dos clientes pelos recursos Google Cloud subjacentes que eles consomem, como invocações de Cloud Functions, Cloud Storage ou armazenamento e consultas de BigQuery. No entanto, durante a janela de migração, os clientes podem incorrer em um pequeno custo adicional temporário se executarem o Firebase Extensions legado e a função de substituição recém-implantada em paralelo para garantir uma transição segura.

Como é feito o faturamento das contas empresariais especializadas da Mandiant ou de outras empresas?

Essa descontinuação é uma mudança em toda a plataforma que afeta todos os projetos Firebase e Google Cloud. Os contratos padrão de faturamento e assinatura não serão afetados. Se os clientes pedirem créditos de SLA devido a um tempo de inatividade por descontinuação ou tiverem exceções de faturamento complexas, encaminhe o caso diretamente pelos canais normais de suporte ao faturamento.

Qual é o risco de perda de dados ou inatividade do serviço durante a migração?

A transição de recursos gerenciados para bases de código autogerenciadas apresenta um pequeno risco de interrupção do serviço ou perda de eventos.

• Interrupção do gatilho: se os gatilhos antigos forem excluídos antes que os novos sejam ativados, será criada uma lacuna em que os eventos (por exemplo, gravações de documentos Cloud Firestore) serão perdidos permanentemente. Recomendamos implantar o kit de substituição e validá-lo antes de remover a extensão para evitar perda de dados.
• Lacunas de permissão: se a base de código recém-implantada não tiver as permissões necessárias do IAM, operações como gravação em BigQuery vão falhar silenciosamente ou falhar durante a execução. Adicionamos segurança declarativa para funções. Assim, a primeira implantação do kit feita por uma conta que pode consultar e definir papéis e gerar uma conta de serviço vai reduzir esse problema.

Como evitamos a perda de dados na extensão de exportação crítica Cloud Firestore para BigQuery?

Para uma transição segura e sem perda de dados, o suporte precisa orientar os usuários a seguir uma migração baseada em sobreposição em vez de uma baseada em lacunas. Esse é o padrão com a migração para kits:

1. Implante o kit de funções de substituição enquanto a extensão ainda estiver instalada e em execução. Aguarde alguns minutos para que o Eventarc seja totalmente provisionado.
2. Grave um documento de teste na coleção Cloud Firestore monitorada e verifique se a nova função autogerenciada grava uma linha correspondente na tabela de changelog BigQuery (com um novo ID de evento).
3. Depois que a nova implantação for confirmada, desinstale ou desative imediatamente a extensão legada para encerrar o comportamento de gravação dupla.
4. Mantenha a janela de sobreposição o mais curta possível para minimizar o custo do processamento duplicado de cada gravação e a possibilidade de linhas duplicadas no changelog bruto do BigQuery.
5. Na maioria dos casos, a tabela de mudanças bruta (*_raw_changelog) vai remover a duplicação por insertID. Mesmo nos casos em que você recebe linhas duplicadas no registro de mudanças, a visualização mais recente da tabela (*_raw_latest) estará correta.

Mais informações sobre a migração dessa extensão em particular e sobre como se recuperar de uma perda de dados estão detalhadas no README.md do kit.

O que devo fazer se a etapa de provisionamento do ciclo de vida falhar?

No serviço gerenciado, as tarefas de configuração (como a criação de BigQuery conjuntos de dados, tabelas e visualizações) eram processadas automaticamente. No modelo NPM autogerenciado, elas são acionadas usando uma função de fila de tarefas do ciclo de vida. Por exemplo, em firestore-bigquery-export, isso é chamado de initBigQuerySync.

Se essa etapa falhar ou não for executada automaticamente:

1. Verifique se a conta de serviço de tempo de execução do Cloud Functions recebeu os papéis do IAM necessários. Por exemplo, para firestore-bigquery-export, isso inclui:

   • Para criar recursos e inserir linhas: roles/bigquery.dataEditor
   • Para executar jobs e criar visualizações: roles/bigquery.user
   • Para enfileirar a tarefa de provisionamento: roles/cloudtasks.enqueuer

2. Confirme se o autor da chamada tem permissões roles/cloudtasks.enqueuer.

3. Execute novamente o comando de inicialização do ciclo de vida manualmente usando a CLI:

   firebase functions:lifecycle:run afterInstall KIT_INSTANCE_ID
   

4. Verifique os registros de Cloud Logging da função de acionamento e da execução da fila de tarefas para diagnosticar erros de permissão ou configuração.

Como as credenciais do Secret Manager são migradas?

No modelo gerenciado, os recursos Secret Manager foram vinculados automaticamente às instâncias de extensão. Quando você usa os comandos ext:migrate ou ext:export --mode functions para exportar a configuração das extensões para um kit de funções, impedimos que as extensões gerenciem esses secrets para que eles permaneçam no projeto após a desinstalação da extensão. Se você quiser remover esses segredos no futuro, faça isso manualmente no console do Google Cloud.

E se um usuário quiser executar várias instâncias de uma extensão migrada?

Introduzimos os kits de funções como uma forma de oferecer suporte a várias instâncias de uma função semelhante a como você pode ter várias versões de uma extensão. Cada kit vai receber um ID de instância exclusivo, que é semelhante a uma base de código e pode ser usado de forma intercambiável com bases de código em comandos da CLI. Quando implantadas, todas as funções em uma instância de kit são prefixadas com kit-<instance-id>- para garantir que cada função tenha um nome exclusivo, semelhante ao prefixo ext-<extension-instance-id>- em extensões. Para saber mais sobre como usar kits de funções como parte da migração, consulte nosso guia de migração para usuários.

A instalação do Kit usa npm. E se eu quiser usar o Yarn ou outro gerenciador de pacotes compatível com o Node?

No momento, não temos planos de oferecer suporte ao Yarn ou a outros gerenciadores de pacotes. A instalação do kit funciona executando diretamente comandos npm ao configurar o código-fonte do kit na primeira instalação.

Como alternativa, você pode criar um diretório de origem, instalar o pacote npm do kit e configurá-lo com builds e exportações adequados. Consulte nossos modelos index-kit do TypeScript em firebase-tools ou confira um kit instalado pelo npm como exemplo. Depois disso, é possível instalar como um kit local usando --directory em vez de --package. Daqui em diante, você precisará identificar o kit por diretório ou ID, mas poderá usar os comandos do kit para adicionar e remover instâncias.

Minha extensão usa o repositório do Docker ou parâmetros avançados do sistema de chaves do KMS. Como posso configurar isso nos kits de funções?

No momento, não é possível configurar um repositório do Docker ou uma chave do KMS em Cloud Functions para Firebase. Se você estiver migrando de uma extensão com esses parâmetros de sistema configurados e quiser preservar essa funcionalidade, aplique os parâmetros às funções do novo kit usando o gcloud CLI.

Pré-requisitos

1. Implante o kit de funções inicialmente seguindo os guias de migração para que as funções existam em Google Cloud.

2. Defina as variáveis de ambiente no terminal:

   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. Pré-crie .gcloudignore na raiz de origem do kit para que os arquivos de build compilados não sejam ignorados por .gitignore:

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

4. Conceda as permissões necessárias do IAM:

   • Para chaves do KMS (concede acesso de descriptografia aos agentes de serviço):

     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
     

   • Para Artifact Registry (concede acesso de gravação a Cloud Build e acesso de leitura a 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"
     

Aplicar as configurações usando o gcloud CLI

Execute gcloud functions deploy para cada função no seu kit:

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}"

Essa solução alternativa não funciona nas seguintes condições:

1. Novas instâncias de kit: adicionar uma instância em firebase.json cria um novo recurso Cloud Functions v2 que usa chaves gerenciadas pelo Google e gcf-artifacts por padrão. É necessário executar gcloud para cada nova instância.
2. Recriação da função: mudar um tipo de gatilho (por exemplo, de HTTPS para um gatilho Cloud Firestore), alterar o ponto de entrada ou renomear faz com que a CLI Firebase exclua a função antiga e crie uma nova. A nova função perde essas configurações até que você execute gcloud novamente.
3. Desvio de configuração: a CLI do Firebase não mostra o status do KMS ou do repositório do Docker em firebase functions:list ou registros de diferenças, o que dificulta a auditoria da infraestrutura.

Como verificar o sucesso

Para confirmar se o repositório e a chave de criptografia foram aplicados, execute o seguinte comando:

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