Configurar e gerenciar back-ends de hospedagem de apps

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

Definir e atualizar variáveis de ambiente

Às vezes, você pode precisar de mais configurações para o processo de build. O App Hosting oferece configuração de ambiente para armazenar e recuperar esse tipo de dados para seu projeto pelo console do Firebase e, alternativamente, em apphosting.yaml.

Definir variáveis de ambiente no console é a maneira mais rápida de começar. Use apphosting.yaml se precisar armazenar e acessar parâmetros secretos, definir variáveis que só estão disponíveis no momento da criação ou da execução ou compartilhar variáveis de ambiente em vários ambientes. Com o console e o apphosting.<env>.yaml, é possível definir valores diferentes para ambientes diferentes.

Console do Firebase

apphosting.yaml

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

Atenção: as configurações baseadas em console e em arquivos têm algumas diferenças importantes. Portanto, revise esta seção com atenção. O mais importante: os valores definidos no console sempre substituem ou têm precedência sobre os valores definidos em apphosting.yaml. Consulte a hierarquia de variáveis.

Atualizar variáveis

É possível adicionar e editar variáveis de ambiente no console Firebase, na guia Configurações de um back-end. Acesse View Backend >> Settings >> Environment e adicione, edite ou exclua variáveis de ambiente.

Para adicionar e editar variáveis de ambiente em apphosting.yaml,, crie e edite o arquivo manualmente.

As mudanças só vão entrar em vigor no próximo lançamento e não vão afetar o atual. Salve e crie um novo lançamento ou salve as variáveis e faça a implantação depois.

Definir a disponibilidade de variáveis

As variáveis de ambiente criadas no console do Firebase estão disponíveis durante o tempo de build e a execução. Essa também é a condição padrão para variáveis definidas em apphosting.yaml, a menos que você tenha restringido esse escopo usando a propriedade availability. Em apphosting.yaml (mas não no console), é possível restringir uma variável de ambiente para que ela fique disponível apenas para o ambiente de build ou apenas para o ambiente de execução.

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

Para apps Next.js, também é possível usar o prefixo NEXT_PUBLIC_ da mesma forma que faria no arquivo dotenv para tornar uma variável acessível no navegador.

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

arquivos dotenv para Next.js

Para apps Next.js, 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 no primeiro campo "Chave" do formulário "Adicionar novo" em Configurações de variáveis de ambiente.

Todas as variáveis de ambiente copiadas dessa forma devem ser formatadas corretamente no formulário, sem precisar inserir cada uma individualmente, desde que a entrada tenha um formato como este:

KEY1=value1
KEY2=value2
KEY3=value3

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

Hierarquia de variáveis

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

Dica: no console do Firebase, clique em um lançamento específico para conferir os detalhes dele. Navegue até Variáveis de ambiente neste build na parte de baixo do painel de detalhes do lançamento para revisar a lista de variáveis de ambiente usadas durante o lançamento e as fontes delas.

Esta é 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 pelos adaptadores do App Hosting em bundle.yaml)

Nomes reservados e limitações

As chaves de variável válidas precisam começar com uma letra maiúscula e conter apenas letras maiúsculas, dígitos e sublinhados. Algumas chaves de variáveis de ambiente são reservadas para uso interno. Não use nenhuma destas chaves nos arquivos de configuração:

• Strings vazias ("")
• Variáveis que contêm "="
• Qualquer variável que comece com X_FIREBASE_
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION
• Chaves duplicadas

Criar e editar apphosting.yaml

Para configurações avançadas, como segredos ou configurações de tempo 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 aceita referências a secrets gerenciados com o Cloud Secret Manager, tornando 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 (em comentário). Depois da edição, um arquivo apphosting.yaml típico pode ter esta aparência, 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 sobre essas configurações de exemplo.

Configurar as definições do serviço Cloud Run

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

• cpu: número de CPUs usadas para cada instância de veiculação (padrão: 0).
• memoryMiB: quantidade de memória alocada para cada instância de serviço em MiB (padrão: 512)
• maxInstances: número máximo de contêineres que podem ser executados ao mesmo tempo (padrão de 100 e gerenciado por cota).
• minInstances: número de contêineres que sempre precisam estar ativos (padrão 0).
• concurrency: número máximo de solicitações que cada instância de veiculação pode receber (padrão: 80).

Observe a relação importante entre cpu e memoryMiB. A memória pode ser definida como qualquer valor inteiro entre 128 e 32768, mas aumentar o limite de memória pode exigir o aumento dos limites de CPU:

• Mais de 4 GiB requer pelo menos 2 CPUs
• Mais de 8 GiB requer pelo menos 4 CPUs
• Mais de 16 GiB requer pelo menos 6 CPUs
• Mais de 24 GiB requer pelo menos 8 CPUs

Da mesma forma, o valor de cpu afeta as configurações de simultaneidade. Se você definir um valor menor que 1 CPU, defina a simultaneidade como 1. A CPU só será alocada durante o processamento da solicitação.

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 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 e as otimizações específicas do framework fornecidas pelo App Hosting. É melhor usar 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 do framework App Hosting.

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

Configurar a saída do build

Por padrão, o App Hosting otimiza as implantações do app excluindo arquivos de saída não utilizados, conforme indicado pelo framework. Se quiser otimizar ainda mais o tamanho de 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 recebe 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 secret

Informações sensíveis, como chaves de API, precisam ser armazenadas como secrets. É possível fazer referência a secrets 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 do secret verificam a existência no Secret Manager do Google Cloud e carregam os valores durante o lançamento.

  -   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 secreto disponível para seu back-end ativo é fixado na versão mais recente disponível do secret no momento em que o back-end foi criado. Se você tiver requisitos de controle de versões e gerenciamento do ciclo de vida de parâmetros, poderá fixar versões específicas com o Cloud Secret Manager. Por exemplo, para fixar na versão 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

É possível criar secrets com o comando da CLI firebase apphosting:secrets:set, e você vai receber uma solicitação para adicionar as permissões necessárias. Esse fluxo oferece a opção de adicionar automaticamente a referência do secret a apphosting.yaml.

Para usar o conjunto completo de funcionalidades do Cloud Secret Manager, use o console do Cloud Secret Manager. Se fizer isso, você precisará conceder permissões ao seu back-end App Hosting com o comando da CLI firebase apphosting:secrets:grantaccess.

Configurar o acesso à VPC

Seu back-end 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 ou ID totalmente qualificado de rede/conector. O uso de IDs permite a portabilidade entre ambientes de teste e produção com diferentes conectores/redes.

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

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

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

Gerenciar back-ends

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

Criar um back-end

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

O proprietário do projeto precisa criar o primeiro back-end App Hosting. Após essa configuração inicial, os administradores do App Hosting também podem criar e gerenciar back-ends adicionais. Para ver todos os repositórios da sua organização, confira se você tem a função de administrador da organização no GitHub. Uma função de membro padrão só mostra os repositórios que você criou pessoalmente. Para mais detalhes, consulte Papéis do IAM do Firebase App Hosting.

Console do Firebase: no menu Build, selecione App Hosting e depois Criar back-end. Se for o primeiro back-end no seu projeto do Firebase, selecione Começar.

CLI: (versão 13.15.4 ou mais recente) para criar um back-end, execute o seguinte comando na raiz do diretório do projeto local, fornecendo seu projectID 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

  As implantações automáticas são ativadas por padrão. Ao concluir a criação do back-end, você pode escolher implantar o app em App Hosting imediatamente.

• Atribua um nome ao back-end.

Excluir um back-end

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

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

CLI:versão 13.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 seu 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 seu back-end em "firebaseapphosting-images".

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