Configurar e gerenciar back-ends de hospedagem de apps

O App Hosting foi projetado para ser fácil de usar e de 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 você gerenciar e configurar back-ends para suas necessidades específicas. Este guia descreve essas ferramentas e processos.

Configurar um back-end

Para configurações avançadas, como variáveis de ambiente ou configurações de ambiente de execução como limites de simultaneidade, CPU e memória, será preciso criar e editar os apphosting.yaml no diretório raiz do seu app. Este arquivo também dá suporte a referências a secrets gerenciados com o Cloud Secret Manager, o que simplifica a verificação do controle de origem.

Veja a aparência de um arquivo apphosting.yaml típico, com configurações para o serviço Cloud Run do back-end, algumas variáveis de ambiente e outras 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.appspot.com
    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 esses exemplos configurações.

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

Com as configurações do apphosting.yaml, é possível definir como seus O serviço Cloud Run está provisionado. As configurações disponíveis para o Serviço Cloud Run são fornecidos no objeto runConfig:

  • cpu: número de CPUs usadas para cada instância de exibição (padrão 0).
  • memoryMiB: quantidade de memória alocada para cada instância de exibição em MiB. (padrão 512)
  • maxInstances: número máximo de contêineres a serem executados por vez (padrão) de 100 e gerenciadas por cotas)
  • minInstances: número de contêineres que devem ser sempre mantidos ativos (padrão 0).
  • concurrency: número máximo de solicitações que cada instância de exibição pode receber (padrão é 80).

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

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

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

Configurar o ambiente de build

Às vezes, você vai precisar de configurações adicionais para o processo de build, como chaves de API de terceiros ou configurações ajustáveis. Ambiente de ofertas do App Hosting em apphosting.yaml para armazenar e extrair esse tipos de dados para seu projeto.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com

Para aplicativos Next.js, os arquivos dotenv que contêm variáveis de ambiente também vão funcionam com App Hosting. Recomendamos o uso de apphosting.yaml para o controle de variáveis de ambiente com qualquer framework.

Em apphosting.yaml, é possível especificar quais processos têm acesso aos seus variável de ambiente usando a propriedade availability. É possível restringir um variável de ambiente esteja disponível apenas para o ambiente de build ou apenas para o ambiente de execução. Por padrão, ele está disponível para ambos.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
    -   BUILD
    -   RUNTIME

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

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
    -   BUILD
    -   RUNTIME

As chaves de variáveis válidas são compostas por caracteres de A a Z ou sublinhados. Algumas as chaves de variável de ambiente são reservadas para uso interno. Não use nenhum desses nos arquivos de configuração:

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

Armazenar e acessar parâmetros do secret

Informações sensíveis, como chaves de API, precisam ser armazenadas como secrets. Você pode 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 armazenados no Cloud Secret Manager. Em vez de derivando o valor diretamente, os parâmetros do secret verificam a existência no Cloud Secret Manager e carregue 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 o valor de um parâmetro secreto disponível para seu back-end ativo é fixado versão mais recente disponível do secret no momento em que o back-end foi criado. Se você têm requisitos para controle de versões e gerenciamento do ciclo de vida dos parâmetros, é possível fixar versões específicas com o Cloud Secret Manager. Por exemplo, para fixar 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 fornece para adicionar automaticamente a referência de secret a apphosting.yaml.

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

Sincronizar o estado do Firebase Auth

Os apps que usam o Firebase Auth devem considerar o uso do SDK da Web do Firebase para ajudar a manter estado de autenticação sincronizado entre o cliente e o servidor. Isso pode ser facilitado pela implementação de FirebaseServerApp com um service worker. O básico fluxo de tarefas é:

  1. Implementar um service worker que adiciona os cabeçalhos corretos ao seu aplicativo em solicitações ao servidor.
  2. Receber os cabeçalhos da solicitação no servidor e convertê-los em um arquivo Auth usuário com FirebaseServerApp.

Gerenciar back-ends

Os comandos para o gerenciamento básico de back-ends App Hosting são fornecidos na CLI Firebase. Algumas operações também estão disponíveis no console do Firebase. Nesta seção, descrever algumas das tarefas de gerenciamento mais comuns, incluindo criar e e excluir back-ends.

Criar um back-end

Um back-end App Hosting é a coleção de recursos gerenciados que O App Hosting cria para criar e executar seu app da Web. É possível criar e listar App Hosting back-ends usando o console do Firebase ou CLI Firebase.

Console do Firebase: no menu Build, selecione App Hosting e Comece a usar o serviço.

CLI: (versão 3.9 ou mais recente) para criar um back-end, execute o comando a seguir da raiz do diretório do seu projeto local, informando aos project ID como argumento (para visualização, somente a região us-central1 tem suporte):

firebase apphosting:backends:create --project PROJECT_ID --location us-central1

No console ou na CLI, siga as instruções para atribuir um nome ao back-end para Configurar um Conexão do GitHub, e defina estas configurações básicas de implantação:

  • Configure o diretório raiz do seu app (o padrão é /)

    Geralmente, é onde o arquivo package.json está localizado.

  • Definir a ramificação ativa

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

  • Aceitar ou recusar lançamentos automáticos

    Os lançamentos automáticos são ativados por padrão. Na conclusão da criação do back-end, é possível escolher se o app será implantado no App Hosting imediatamente.

Excluir um back-end

Para remover totalmente um back-end, primeiro use a CLI Firebase e, em seguida, manualmente remover recursos relacionados, tomando cuidado especial para não excluir recursos que possa ser usado por outros back-ends ou outros aspectos do seu projeto do Firebase.

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

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1

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

  3. No Cloud Secret Manager, faça o seguinte: exclua os secrets com "apphosting" no nome secreto, tomando um para garantir que esses secrets não sejam usados por outros back-ends ou outros aspectos do seu projeto do Firebase.