Configurar e gerenciar back-ends de hospedagem de apps

O App Hosting foi projetado para ser fácil de usar e exigir pouca manutenção, com configurações padrão otimizadas para a maioria dos casos de uso. Ao mesmo tempo, o App Hosting fornece ferramentas para você gerenciar e configurar back-ends de acordo com suas necessidades específicas. Este guia descreve essas ferramentas e processos.

Definir e atualizar variáveis de ambiente e secrets

O App Hosting permite usar variáveis de ambiente para valores de configuração não sensíveis e secrets para parâmetros sensíveis, como chaves de API, credenciais de banco de dados e tokens de serviço.

  • Variáveis de ambiente padrão: usadas para configurações de texto simples não confidenciais, como URLs de APIs públicas, flags de recursos ou destinos de build. Os valores ficam visíveis para todos os membros do projeto.
  • Secrets: usados para parâmetros sensíveis (como chaves secretas do cliente OAuth, tokens de API ou senhas de banco de dados). Os secrets são armazenados no Cloud Secret Manager. Os valores de secrets são protegidos e nunca são exibidos em texto simples no console do Firebase. Em vez disso, o console fornece links diretos para visualizar e gerenciar valores de secrets diretamente no Cloud Secret Manager.

É possível definir e gerenciar parâmetros de ambiente usando duas abordagens complementares:

  • Console do Firebase: adicione, edite e anexe secrets ou variáveis de forma dinâmica durante a criação inicial do back-end ou após a implantação nas configurações de back-end.

  • Code-first (apphosting.yaml): declare variáveis de ambiente e referências de secrets no arquivo de configuração do repositório para implantações com controle de versões ou use apphosting.<env>.yaml para definir valores diferentes para ambientes diferentes.

Console do Firebase

Captura de tela da caixa de diálogo do console do Firebase para adicionar variáveis de ambiente

apphosting.yaml 

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

Gerenciar variáveis e secrets no console do Firebase

É possível configurar variáveis de ambiente e secrets no console do Firebase ao criar um back-end ou a qualquer momento nas configurações dele. As mudanças salvas sem implantação entram em vigor no próximo lançamento e não afetam o atual.

Configurar variáveis e secrets durante a criação do back-end

Ao criar um novo back-end do App Hosting no console do Firebase, é possível configurar variáveis de ambiente padrão e secrets durante a etapa Configurar seu back-end do assistente de configuração:

  1. No console do Firebase, acesse Hospedagem e sem servidor > App Hosting e clique em Criar back-end.
  2. Conclua as etapas iniciais do assistente para selecionar a região principal e o repositório de código.
  3. Na seção Configurar o back-end, localize os cards recolhíveis para Variáveis de ambiente e Secrets, em que é possível adicionar variáveis padrão e anexar secrets.
  4. Conclua o assistente de criação de back-end e clique em Concluir e implantar.

Gerenciar variáveis e secrets nas configurações de back-end

É possível visualizar, adicionar, editar ou excluir variáveis de ambiente e secrets de back-ends ativos no painel de configurações de back-end:

  1. No console do Firebase, selecione o back-end do App Hosting e abra Configurações > Ambiente.
  2. Revise as configurações atuais na tabela Variáveis de ambiente:
    • Variáveis padrão: os valores são mostrados como texto simples em blocos de código copiáveis.
    • Secrets: exibidos como um link clicável que mostra o nome do secret (que abre o Cloud Secret Manager no console do Google Cloud) ao lado da versão de destino (como latest ou um número de versão específico, como 2).
  3. Para adicionar uma variável ou um secret:
    1. Clique em Adicionar novo.
    2. Na Etapa 1: selecionar tipo, escolha Variável de ambiente padrão (para dados não sensíveis visíveis para todos os membros do projeto) ou Secret (para chaves de API e credenciais sensíveis com acesso restrito) e clique em Próxima.
    3. Na Etapa 2: definir as configurações, insira o nome da Chave e o Valor em texto simples (para variáveis padrão) ou selecione o ID do Secret e a Versão (para secrets).
    4. Salve as mudanças usando uma das seguintes opções:
      • Salvar e implantar: atualiza imediatamente a configuração do back-end e aciona um novo build e lançamento.
      • Apenas salvar (na seta suspensa ao lado de Salvar e implantar): salva as alterações de configuração sem acionar um lançamento imediato. As configurações atualizadas vão entrar em vigor na próxima implantação.
  4. Para editar ou excluir uma entrada, clique no menu Mais ações (...) no final da linha:
    • Selecione Editar para modificar a chave, o valor, o mapeamento do secret ou a versão e, em seguida, clique em Salvar e implantar ou Apenas salvar.
    • Selecione Excluir e confirme a remoção na caixa de diálogo.

Transferir variáveis de arquivos dotenv

Para apps Next.js, os arquivos dotenv que contêm variáveis de ambiente funcionam com o App Hosting.

Ao criar ou atualizar um back-end, é possível transferir variáveis de ambiente do arquivo dotenv para o console do Firebase copiando e colando todo o conteúdo do arquivo dotenv no primeiro campo Chave no formulário Adicionar novo em Configurações > Ambiente.

Todas as variáveis de ambiente copiadas dessa forma são formatadas automaticamente no formulário sem precisar inserir cada uma individualmente, desde que a entrada use a formatação padrão KEY=value:

KEY1=value1
KEY2=value2
KEY3=value3

Para um controle complexo ou granular de variáveis de ambiente com qualquer framework, recomendamos o uso de apphosting.yaml.

Gerenciar variáveis e secrets no apphosting.yaml

Para fluxos de trabalho que priorizam o código, declare variáveis de ambiente padrão e referências secretas na chave env: no arquivo de configuração apphosting.yaml do repositório do projeto (consulte Criar e editar 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

Cada entrada em env: é compatível com os seguintes campos:

  • variable: o nome da variável de ambiente exposto ao processo do aplicativo.
  • value: o valor da string de texto simples (para variáveis de ambiente padrão).
  • secret: a referência do secret do Cloud Secret Manager (para secrets). É possível usar o nome curto do secret (como myGeminiApiKeySecret ou myGeminiApiKeySecret@1 fixado) ou o caminho completo do recurso (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION). Consulte Armazenar e acessar parâmetros de secret para mais detalhes.
  • availability: controla se a variável ou o secret pode ser acessado durante a fase BUILD, em RUNTIME ou em ambas.

Definir disponibilidade de variáveis

As variáveis de ambiente e os secrets configurados no console do Firebase estão disponíveis no momento do build e da execução. Esse também é o comportamento padrão para entradas definidas em apphosting.yaml, a menos que você restrinja o escopo usando a propriedade availability. No apphosting.yaml (mas não no console), é possível restringir uma variável ou um secret apenas ao ambiente de build (BUILD) ou apenas ao ambiente de execução (RUNTIME).

Acessar variáveis e secrets no código do aplicativo

Sejam configuradas no console do Firebase ou no apphosting.yaml, as variáveis de ambiente e os secrets são expostos ao ambiente de execução do aplicativo como variáveis de ambiente padrão (por exemplo, process.env no 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();
}
  • Acesso do lado do servidor: todas as variáveis de ambiente e secrets podem ser acessados com segurança em contextos de execução do lado do servidor (como componentes do servidor Next.js, rotas de API ou gerenciadores de back-end do Node.js).

  • Exposição do lado do cliente: para expor variáveis de ambiente padrão ao navegador em frameworks como o Next.js, verifique se a chave da variável segue as convenções do framework (por exemplo, prefixada com NEXT_PUBLIC_).

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

Hierarquia de variáveis

O Firebase App Hosting aplica as variáveis de ambiente e os secrets em uma ordem de precedência com base na origem. As configurações definidas no console do Firebase sempre substituem os parâmetros declarados nos arquivos apphosting.yaml e dotenv. Se uma variável de ambiente ou chave secreta com o mesmo nome existir em apphosting.yaml e no console do Firebase, o valor do console terá precedência durante a execução do build e do ambiente de execução.

Confira a ordem de precedência completa:

  1. Console do Firebase → variáveis e secrets definidos no console
  2. apphosting.<env>.yaml: variáveis e secrets especificados em um arquivo YAML específico do ambiente, como apphosting.staging.yaml (consulte Implantar vários ambientes)
  3. apphosting.yaml → variáveis e secrets especificados no arquivo apphosting.yaml
  4. Sistema do Firebase: variáveis definidas pelo Firebase que contêm valores para FIREBASE_CONFIG ou FIREBASE_WEBAPP_CONFIG, além de variáveis de ambiente que definem os nomes de host e as portas para apps SSR (definidos por adaptadores App Hosting em bundle.yaml)

Variáveis ​​de ambiente preenchidas automaticamente

Há variáveis de ambiente que são preenchidas automaticamente pelo App Hosting. Isso inclui as preenchidas pelo Google Cloud, além de variáveis de ambiente específicas do Firebase quando appId é definido no back-end durante a configuração:

  • FIREBASE_CONFIG: (disponível nos ambientes de build e de execução) fornece as seguintes informações de configuração do projeto do Firebase:

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

    Essa configuração é aplicada automaticamente quando você inicializa o SDK Admin do Firebase sem argumentos.

  • FIREBASE_WEBAPP_CONFIG: (disponível apenas no ambiente de build) fornece as seguintes informações de configuração do projeto do 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>

    O SDK do Firebase para JS verifica automaticamente essa variável de ambiente FIREBASE_WEBAPP_CONFIG em um script de pós-instalação durante o build, permitindo que você também inicialize o SDK do cliente sem argumentos.

Consulte Inicializar automaticamente o SDK Admin do Firebase e os SDKs da Web para mais detalhes sobre como usar essas variáveis de ambiente para inicializar os SDKs.

Os valores na configuração real do Firebase vão corresponder aos recursos específicos provisionados no projeto.

Hierarquia de variáveis

O Firebase App Hosting aplica as variáveis em uma ordem de precedência com base na origem delas. Por exemplo, os valores definidos no console do Firebase sempre substituem ou têm precedência sobre os valores definidos nos arquivos apphosting.yaml e dotenv.

Confira a ordem de precedência completa:

  1. Console do Firebase: variáveis definidas no console
  2. apphosting.<env>.yaml → variáveis especificadas em um arquivo YAML específico do ambiente, como apphosting.staging.yaml (consulte Implantar vários ambientes)
  3. apphosting.yaml → variáveis especificadas no arquivo apphosting.yaml
  4. Sistema do Firebase: variáveis definidas pelo Firebase que contêm valores para firebase_config json ou firebase_webapp_config, além de variáveis de ambiente que definem os nomes de host e as portas para apps de SSR (definidos por adaptadores do App Hosting em bundle.yaml)

Nomes reservados e limitações

As variáveis de ambiente definidas no contrato de ambiente de execução do contêiner do Cloud Run são reservadas e não podem ser configuradas.

As variáveis de ambiente fornecidas pelo ambiente, exceto as que são definidas automaticamente, podem mudar em versões futuras do ambiente de execução. Como prática recomendada, não dependa nem modifique variáveis de ambiente que não foram definidas explicitamente e considere prefixar todas as variáveis de ambiente com uma chave exclusiva para evitar conflitos.

Algumas chaves de variáveis de ambiente são reservadas para uso interno. Não use nenhuma dessas chaves nos arquivos de configuração:

  • Strings vazias ("")
  • Chaves que contêm "="
  • Chaves que começam com X_FIREBASE_, X_GOOGLE_ ou CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Chaves duplicadas

Criar e editar apphosting.yaml

Para configurações avançadas, como secrets ou configurações de ambiente de execução, como simultaneidade, CPU e limites de memória, crie e edite o arquivo apphosting.yaml no diretório raiz do app. Esse arquivo oferece suporte a referências a secrets gerenciados com o Cloud Secret Manager, o que torna seguro o check-in no controle de origem.

Para criar apphosting.yaml, execute o seguinte comando:

firebase init apphosting

Isso cria um arquivo apphosting.yaml inicial básico com um exemplo de configuração (comentado). Após a edição, um arquivo apphosting.yaml típico pode ser semelhante ao seguinte, com configurações para o serviço Cloud Run do back-end, algumas variáveis de ambiente e algumas referências a secrets gerenciados pelo 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

O restante deste guia fornece mais informações e contexto para essas configurações de exemplo.

Definir as configurações do serviço Cloud Run

Com as configurações de apphosting.yaml, é possível configurar como o serviço do Cloud Run é provisionado. As configurações disponíveis para o serviço Cloud Run são fornecidas no objeto runConfig:

Observe que cpu, memoryMiB e concurrency têm limites interdependentes (por exemplo, configurações de memória mais altas exigem limites mínimos de CPU mais altos, e CPUs fracionárias exigem uma simultaneidade de 1). Consulte a documentação do Cloud Run sobre limites de CPU e limites de memória para intervalos válidos e combinações necessárias.

Substituir scripts de build e execução

O App Hosting infere o comando de build e inicialização do app com base no framework detectado. Se você quiser usar um comando de build ou de inicialização personalizado, substitua os padrões de App Hosting em apphosting.yaml.

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

A substituição do comando de build tem precedência sobre qualquer outro comando de build e desativa os adaptadores de framework do app, além de desativar as otimizações específicas de framework fornecidas pelo App Hosting. É melhor usá-lo quando os recursos do app não são bem compatíveis com os adaptadores. Se você quiser mudar o comando de build, mas ainda usar os adaptadores fornecidos, defina o script de build em package.json, conforme descrito em Adaptadores de framework do App Hosting.

Use a substituição do comando de execução quando houver um comando específico que você queira usar para iniciar o app que seja diferente do comando inferido pelo App Hosting.

Configurar a saída do build

O App Hosting otimiza as implantações do app por padrão, excluindo arquivos de saída não utilizados, conforme indicado pelo framework. Se você quiser otimizar ainda mais o tamanho da implantação do app ou ignorar as otimizações padrão, substitua isso em apphosting.yaml.

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

O parâmetro include usa uma lista de diretórios e arquivos relativos ao diretório raiz do app que são necessários para implantar o app. Se você quiser garantir que todos os arquivos sejam mantidos, defina include como [.] e todos os arquivos serão implantados.

Armazenar e acessar parâmetros de secrets

Informações sensíveis, como chaves de API, precisam ser armazenadas como secrets. É possível anexar secrets ao back-end no console do Firebase ou referenciá-los em apphosting.yaml para evitar a verificação de informações sensíveis no controle de origem.

Os parâmetros do tipo secret representam parâmetros de string que têm um valor armazenado no Secret Manager do Google Cloud. Em vez de derivar o valor diretamente, os parâmetros de secret verificam a existência no Secret Manager do Google Cloud e carregam os valores durante o lançamento.

env:
  - variable: API_KEY
    secret: myApiKeySecret

Os secrets no Cloud Secret Manager podem ter várias versões. Por padrão, o valor de um parâmetro de secret disponível para o back-end ativo é fixado na versão mais recente do secret no momento em que o back-end foi criado. Se você tiver requisitos para controle de versões e gerenciamento do ciclo de vida de parâmetros, poderá fixar versões específicas no console do Firebase ou no apphosting.yaml. Por exemplo, para fixar na versão 5 em apphosting.yaml:

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

É possível criar secrets com o comando firebase apphosting:secrets:set da CLI Firebase. Será solicitado que você adicione as permissões necessárias. Esse fluxo oferece a opção de adicionar automaticamente a referência do secret a apphosting.yaml.

Conceder acesso ao Cloud Secret Manager

Para que o App Hosting busque valores de secrets durante as implantações de build e de ambiente de execução, a conta de serviço de back-end do App Hosting precisa ter permissão para acessar o Cloud Secret Manager.

Se você criar secrets usando o console do Cloud Secret Manager ou a CLI gcloud em vez de firebase apphosting:secrets:set, conceda acesso ao back-end usando a CLI Firebase:

firebase apphosting:secrets:grantaccess SECRET_NAME

Como alternativa, é possível conceder o papel de Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) ao agente de serviço do App Hosting (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) ou à conta de serviço de ambiente de execução do back-end usando a 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"

Acesso ao console e permissões baseadas em papéis

O console do Firebase restringe dinamicamente os recursos de gerenciamento de ambiente e do Secret Manager com base nas permissões do IAM do usuário:

  • Papel de leitor: usuários com permissões de projeto somente leitura podem visualizar as configurações atuais, mas não podem fazer mudanças.
    • Durante a criação do back-end, o botão Criar back-end fica desativado.
    • Em Configurações > Ambiente do back-end, o botão Adicionar novo está desativado, e os menus de linha Mais ações (...) estão ocultos.
  • Permissões ausentes do Secret Manager: os usuários que não têm permissões do IAM para interagir com o Cloud Secret Manager recebem uma mensagem de aviso no console (Peça permissão ao proprietário do projeto para adicionar secrets):
    • Durante a criação do back-end, o card Secrets fica desativado.
    • Em Configurações > Ambiente do back-end, a opção Secret é desativada ao clicar em Adicionar novo, e algumas das opções no menu de linha Mais ações (...) ficam ocultas nas entradas de secret atuais.

Configurar o acesso à VPC

O back-end do App Hosting pode se conectar a uma rede de nuvem privada virtual (VPC). Para mais informações e um exemplo, consulte Conectar o Firebase App Hosting a uma rede VPC.

Use o mapeamento vpcAccess no arquivo apphosting.yaml para configurar o acesso. Use um nome de rede/conector totalmente qualificado ou um ID. O uso de IDs permite a portabilidade entre ambientes de preparo e de produção com diferentes conectores/redes.

Configuração de saída de VPC direta (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

Configuração do conector sem servidor (apphosting.yaml):

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

Gerenciar back-ends

Os comandos para o gerenciamento básico de back-ends do App Hosting são fornecidos no console do Firebase e na CLI Firebase. Nesta seção, descrevemos algumas das tarefas de gerenciamento mais comuns, incluindo a criação e a exclusão de back-ends.

Criar um back-end

Um back-end do App Hosting é a coleção de recursos gerenciados que o App Hosting cria para criar e executar seu app da Web.

Console do Firebase: acesse Hospedagem e sem servidor > App Hosting e clique em Criar back-end (se esse for o primeiro back-end no seu projeto do Firebase, clique em Começar).

CLI do Firebase: (v13.15.4 ou mais recente) para criar um back-end, execute o seguinte comando na raiz do diretório do projeto local, fornecendo o ID do projeto como um argumento:

firebase apphosting:backends:create --project PROJECT_ID

No console ou na CLI, siga as instruções para escolher uma região, configurar uma conexão do GitHub e definir estas configurações básicas de implantação:

  • Defina o diretório raiz do app (o padrão é /).

    É onde o arquivo package.json geralmente está localizado.

  • Defina a ramificação em uso

    Esta é a ramificação do seu repositório do GitHub que é implantada no seu URL ativo. Muitas vezes, é a ramificação em que as ramificações de recursos ou de desenvolvimento são mescladas.

  • Aceitar ou recusar lançamentos automáticos

    Os lançamentos automáticos são ativados por padrão. Após a conclusão da criação do back-end, é possível implantar o app no App Hosting imediatamente.

  • Atribua um nome ao back-end.

  • Selecione o ambiente de execução. Por padrão, a versão recomendada mais recente do Node.js é pré-selecionada para você.

Excluir um back-end

Para remover completamente um back-end, primeiro use o console do Firebase ou a CLI do Firebase para excluí-lo e, em seguida, remova manualmente os recursos relacionados, tomando cuidado especial para não excluir nenhum recurso que possa ser usado por outros back-ends ou outros aspectos do seu projeto do Firebase.

Console do Firebase: no menu Configurações, selecione Excluir back-end.

CLI do Firebase (v13.15.4 ou mais recente)

  1. Execute o comando a seguir para excluir o back-end App Hosting. Isso desativa todos os domínios do back-end e exclui o serviço Cloud Run associado:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (Opcional) Na guia do console do Google Cloud para Artifact Registry, exclua a imagem do back-end em "firebaseapphosting-images".

  3. No Cloud Secret Manager, exclua todos os secrets com "apphosting" no nome, tomando cuidado especial para garantir que eles não sejam usados por outros back-ends ou outros aspectos do seu projeto do Firebase.