O App Hosting foi projetado para facilitar o uso e reduzir a manutenção, com configurações padrão otimizadas para a maioria dos casos de uso. Ao mesmo tempo, o App Hosting fornece ferramentas para 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 execução,
como simultaneidade, CPU e limites de memória, é necessário criar e editar o
arquivo apphosting.yaml
no diretório raiz do app. Esse arquivo também
oferece suporte a referências a segredos 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 exemplo de configuração (comentado). Após a edição, um arquivo apphosting.yaml
típico pode ficar assim,
com configurações para o serviço Cloud Run do back-end, algumas
variáveis de ambiente e algumas referências a segredos gerenciados pelo Gerenciador de secrets do
Cloud:
# 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 oferece mais informações e contexto sobre esses exemplos de configurações.
Configurar as configurações do serviço Cloud Run
Com as configurações de apphosting.yaml
, é possível definir como o
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 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 gerenciado por cota)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 veiculação pode receber (padrão: 80).
Observe a relação importante entre cpu
e memoryMiB
. A memória pode ser definida
para qualquer valor inteiro entre 128 e 32768, mas aumentar o limite de memória pode
requerer o aumento dos limites da CPU:
- Mais de 4 GiB exige 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, será necessário 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ção adicional para o 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.appspot.com
Para apps Next.js, os arquivos dotenv que contêm
variáveis de ambiente
também funcionam com App Hosting. Recomendamos o uso de apphosting.yaml
para controle granular de variáveis de ambiente com qualquer framework.
No 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 para o ambiente de build ou
apenas para o ambiente de execução. Por padrão, ele está disponível para os dois.
env:
- variable: STORAGE_BUCKET
value: mybucket.appspot.com
availability:
- BUILD
- RUNTIME
Para apps Next.js, também é possível usar o prefixo NEXT_PUBLIC_
da mesma forma que
no 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á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 dessas chaves 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 secretos
Informações sensíveis, como chaves de API, precisam ser armazenadas como secrets. É possível
referenciar secrets no apphosting.yaml
para evitar a verificação de informações confidenciais
no controle de origem.
Os parâmetros do tipo secret
representam parâmetros de string que têm um valor
armazenado no Cloud Secret Manager.
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 de 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 firebase apphosting:secrets:set
da CLI.
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 secreta a apphosting.yaml
.
Para usar o pacote completo de funcionalidades do Cloud Secret Manager, use o console do Cloud Secret Manager. Se você fizer isso, vai precisar conceder
permissões ao back-end App Hosting com o comando firebase
apphosting:secrets:grantaccess
da CLI.
Sincronizar o estado do Firebase Auth
Os apps que usam o Firebase Auth precisam considerar o uso do SDK da Web do Firebase para manter
o estado de autenticação sincronizado entre o cliente e o servidor. Isso pode ser
facilitado implementando FirebaseServerApp
com um service worker. O fluxo de tarefas
básico é:
- Implemente um worker de serviço que adicione os cabeçalhos corretos para o app em solicitações ao servidor.
- Receba os cabeçalhos da solicitação no servidor e converta-os em um usuário de
autenticação com
FirebaseServerApp
.
Gerenciar back-ends
Os comandos para 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 Firebase. Esta seção descreve 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 App Hosting é a coleção de recursos gerenciados que App Hosting cria para criar e executar seu app da Web. É possível criar e listar back-ends de App Hosting usando o console do Firebase ou a CLI Firebase.
Console do Firebase: no menu Build, selecione App Hosting e, em seguida, 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 o projectID e a região preferida como argumentos:
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, configurar uma conexão do GitHub e definir estas configurações básicas de implantação:
Defina o diretório raiz do seu app (padrão:
/
)É onde o arquivo
package.json
geralmente está localizado.
Definir a ramificação ativa
Essa é a ramificação do repositório do GitHub que é implantada no 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. Após a 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, 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.
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 --location us-central1
(Opcional) Na guia do Console do Google Cloud para Artifact Registry, exclua a imagem do back-end em "firebaseapphosting-images".
No Cloud Secret Manager, exclua todos os secrets com "apphosting" no nome do secret, com cuidado especial para garantir que eles não sejam usados por outros back-ends ou outros aspectos do seu projeto do Firebase.