Configurar e gerenciar back-ends de hospedagem de apps

O App Hosting foi projetado para facilitar o uso e a 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 de acordo com suas necessidades específicas. Este guia descreve essas ferramentas e processos.

Criar e editar apphosting.yaml

Para configurações avançadas, como variáveis de ambiente 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 também aceita referências a secrets gerenciados com o Cloud Secret Manager, o que torna seguro fazer 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 oferece 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 de 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 devem ser mantidos 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 32.768, 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.

Configurar o ambiente

Às vezes, você precisará de configuração adicional para seu processo de build, como chaves de API de terceiros ou configurações ajustáveis. O App Hosting oferece configuração de ambiente em apphosting.yaml para armazenar e recuperar esse tipo de dados para seu projeto.

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

Para apps Next.js, os arquivos dotenv que contêm variáveis de ambiente também funcionam com App Hosting. Recomendamos usar apphosting.yaml para controle granular de variáveis de ambiente com qualquer framework.

Em apphosting.yaml, é possível especificar quais processos têm acesso à sua variável de ambiente usando a propriedade availability. É possível restringir uma variável de ambiente para que ela esteja disponível apenas no ambiente de build ou apenas no ambiente de execução. Por padrão, ele está disponível para os dois.

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

As chaves de variável válidas são compostas de caracteres de A a Z ou 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:

  • Qualquer variável que comece com X_FIREBASE_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION

Substituir scripts de build e execução

O App Hosting deduz 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 Firebase App Hosting a uma rede VPC.

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

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

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 é a coleção de recursos gerenciados que o App Hosting cria para criar e executar seu web app.

Console do Firebase: no menu Build, selecione App Hosting e clique em Começar agora.

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 ativa

    Esse é o branch do seu repositório do GitHub que é implantado 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. 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 especial para garantir que eles não sejam usados por outros back-ends ou outros aspectos do seu projeto do Firebase.