Configura e gestisci i backend di hosting delle app

App Hosting è stato progettato per essere facile da usare e richiede poca manutenzione, con impostazioni predefinite ottimizzate per la maggior parte dei casi d'uso. Allo stesso tempo, App Hosting fornisce strumenti per gestire e configurare i backend in base alle tue esigenze specifiche. La presente guida descrive questi strumenti e procedure.

Configura un backend

Per la configurazione avanzata, ad esempio le variabili di ambiente o le impostazioni di runtime come la concorrenza, la CPU e i limiti di memoria, dovrai creare e modificare il file apphosting.yaml nella directory principale dell'app. Questo file supporta inoltre i riferimenti ai secret gestiti con Cloud Secret Manager, il che consente di eseguire il check-in nel controllo del codice sorgente in tutta sicurezza.

Per creare apphosting.yaml, esegui questo comando:

firebase init apphosting

Viene creato un file apphosting.yaml di avvio di base con una configurazione di esempio (commentata). Dopo la modifica, un file apphosting.yaml tipico potrebbe avere il seguente aspetto, con le impostazioni per il servizio Cloud Run del backend, alcune variabili di ambiente e alcuni riferimenti ai secret gestiti da 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

Il resto di questa guida fornisce maggiori informazioni e contesto per queste impostazioni di esempio.

Configura le impostazioni del servizio Cloud Run

Con le impostazioni di apphosting.yaml, puoi configurare le modalità di provisioning del tuo servizio Cloud Run. Le impostazioni disponibili per il servizio Cloud Run sono fornite nell'oggetto runConfig:

  • cpu - Numero di CPU utilizzate per ogni istanza di pubblicazione (valore predefinito 0).
  • memoryMiB - Quantità di memoria allocata per ogni istanza di pubblicazione in MiB (valore predefinito 512)
  • maxInstances: il numero massimo di container da eseguire contemporaneamente (valore predefinito di 100 e gestito in base alla quota)
  • minInstances - Numero di container da mantenere sempre attivi (valore predefinito 0).
  • concurrency: numero massimo di richieste che ogni istanza di pubblicazione può ricevere (valore predefinito 80).

Tieni presente la relazione importante tra cpu e memoryMiB. La memoria può essere impostata su qualsiasi valore intero compreso tra 128 e 32768, ma l'aumento del limite di memoria potrebbe richiedere l'aumento dei limiti della CPU:

  • Oltre 4 GB sono necessarie almeno 2 CPU
  • Oltre 8 GB sono necessarie almeno 4 CPU
  • Oltre 16 GB sono necessarie almeno 6 CPU
  • Oltre 24 GB sono necessarie almeno 8 CPU

Analogamente, il valore di cpu influisce sulle impostazioni di concorrenza. Se imposti un valore inferiore a 1 CPU, devi impostare la concorrenza su 1 e la CPU verrà allocata solo durante l'elaborazione delle richieste.

Configura l'ambiente di compilazione

A volte è necessaria una configurazione aggiuntiva per il processo di compilazione, ad esempio chiavi API di terze parti o impostazioni regolabili. App Hosting offre la configurazione dell'ambiente in apphosting.yaml per archiviare e recuperare questo tipo di dati per il tuo progetto.

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

Per le app Next.js, anche i file dotenv contenenti variabili di ambiente funzioneranno con App Hosting. Ti consigliamo di utilizzare apphosting.yaml per il controllo granulare delle variabili di ambiente con qualsiasi framework.

In apphosting.yaml, puoi specificare quali processi hanno accesso alla variabile di ambiente utilizzando la proprietà availability. Puoi limitare una variabile di ambiente in modo che sia disponibile solo per l'ambiente di compilazione o solo per l'ambiente di runtime. Per impostazione predefinita, è disponibile per entrambi.

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

Per le app Next.js, puoi anche utilizzare il prefisso NEXT_PUBLIC_ nello stesso modo in cui lo faresti nel file dotenv per rendere una variabile accessibile nel browser.

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

Le chiavi delle variabili valide sono costituite da caratteri A-Z o trattini bassi. Alcune chiavi delle variabili di ambiente sono riservate per uso interno. Non utilizzare nessuna di queste chiavi nei file di configurazione:

  • Qualsiasi variabile che inizia con X_FIREBASE_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION

Memorizzare e accedere ai parametri dei secret

Le informazioni sensibili come le chiavi API devono essere archiviate come secret. Puoi fare riferimento ai secret in apphosting.yaml per evitare di controllare le informazioni sensibili nel controllo del codice sorgente.

I parametri di tipo secret rappresentano parametri di stringa con un valore memorizzato in Cloud Secret Manager. Invece di ricavare direttamente il valore, i parametri dei secret ne verificano l'esistenza in Cloud Secret Manager e caricano i valori durante l'implementazione.

  -   variable: API_KEY
      secret: myApiKeySecret

I secret in Cloud Secret Manager possono avere più versioni. Per impostazione predefinita, il valore di un parametro del secret disponibile per il backend live è bloccato all'ultima versione disponibile del secret al momento della creazione del backend. Se hai requisiti per il controllo delle versioni e la gestione del ciclo di vita dei parametri, puoi bloccare versioni specifiche con Cloud Secret Manager. Ad esempio, per bloccare la versione 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Puoi creare secret con il comando firebase apphosting:secrets:set della CLI, e ti verrà chiesto di aggiungere le autorizzazioni necessarie. Questo flusso ti offre la possibilità di aggiungere automaticamente il riferimento al secret a apphosting.yaml.

Per utilizzare la suite completa di funzionalità di Cloud Secret Manager, puoi utilizzare la console Cloud Secret Manager. In questo caso, dovrai concedere le autorizzazioni al backend App Hosting con il comando dell'interfaccia a riga di comando firebase apphosting:secrets:grantaccess.

Sincronizzare lo stato di Firebase Auth

Le app che utilizzano Firebase Auth dovrebbero valutare l'utilizzo dell'SDK web Firebase per mantenere lo stato dell'autenticazione sincronizzato tra il client e il server. Ciò può essere facilitato implementando FirebaseServerApp con un service worker. Il flusso delle attività di base è:

  1. Implementa un service worker che aggiunge le intestazioni corrette per la tua app alle richieste al server.
  2. Recupera le intestazioni della richiesta sul server e convertile in un utente auth con FirebaseServerApp.

Gestire i backend

I comandi per la gestione di base dei backend App Hosting sono forniti nell'interfaccia a riga di comando Firebase. Alcune operazioni sono disponibili anche nella console Firebase. In questa sezione vengono descritte alcune delle attività di gestione più comuni, tra cui la creazione e l'eliminazione dei backend.

Crea un backend

Un backend App Hosting è la raccolta di risorse gestite che App Hosting crea per compilare ed eseguire la tua app web. Puoi creare e elencare i backend App Hosting utilizzando la console Firebase o la CLI Firebase.

Console Firebase: nel menu Build, seleziona App Hosting e poi Inizia.

CLI: (versione 13.15.4 o successive) per creare un backend, esegui il seguente comando dalla directory principale del progetto locale, specificando il projectID e la regione preferita come argomenti:

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

Sia per la console che per l'interfaccia a riga di comando, segui le istruzioni per assegnare un nome al tuo backend, per configurare una connessione GitHub e configurare queste impostazioni di deployment di base:

  • Imposta la directory principale della tua app (il valore predefinito è /)

    Di solito è qui che si trova il file package.json.

  • Imposta il ramo attivo

    Si tratta del ramo del tuo repository GitHub di cui viene eseguito il deployment nell'URL pubblicato. Spesso è il ramo in cui vengono uniti i rami di funzionalità o di sviluppo.

  • Accettare o rifiutare le implementazioni automatiche

    Le implementazioni automatiche sono abilitate per impostazione predefinita. Al termine della creazione del backend, puoi scegliere di eseguire immediatamente il deployment della tua app su App Hosting.

Elimina un backend

Per rimuovere completamente un backend, utilizza prima l'interfaccia a riga di comando Firebase e poi rimuovi manualmente gli asset correlati, prestando particolare attenzione a non eliminare le risorse che potrebbero essere utilizzate da altri backend o altri aspetti del tuo progetto Firebase.

  1. Esegui questo comando per eliminare il backend App Hosting. In questo modo vengono disattivati tutti i domini per il tuo backend ed eliminato il servizio Cloud Run associato:

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

  2. (Facoltativo) Nella scheda della console Google Cloud per Artifact Registry, elimina l'immagine per il tuo backend in "firebaseapphosting-images".

  3. In Cloud Secret Manager, elimina tutti gli secret con "apphosting" nel nome, facendo attenzione a verificare che questi secret non vengano utilizzati da altri backend o da altri aspetti del tuo progetto Firebase.