Configura e gestisci i backend di hosting delle app

App Hosting è stato progettato per essere facile da usare e richiedere 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. Questa guida descrive questi strumenti e processi.

Impostare e aggiornare le variabili di ambiente

A volte potresti aver bisogno di una configurazione aggiuntiva per il processo di compilazione. App Hosting offre la configurazione dell'ambiente per archiviare e recuperare questo tipo di dati per il tuo progetto tramite la console Firebase e, in alternativa, in apphosting.yaml.

L'impostazione delle variabili di ambiente nella console Firebase è il modo più rapido per iniziare. Utilizza apphosting.yaml se devi archiviare e accedere ai secret, impostare variabili disponibili solo in fase di build o di runtime o condividere le variabili di ambiente tra più ambienti. Sia con la console sia con apphosting.<env>.yaml, puoi impostare valori diversi per ambienti diversi.

Firebase console

Acquisizione schermo della finestra di dialogo della console Firebase per l&#39;aggiunta di variabili di ambiente

apphosting.yaml 

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

Aggiornare le variabili

Puoi aggiungere, modificare o eliminare le variabili di ambiente nella Firebase console o utilizzando apphosting.yaml:

  • Firebase console:

    1. Nella Firebase console, vai a Hosting e serverless > App Hosting.

    2. Vai a Visualizza backend > Impostazioni > Ambiente.

    3. Aggiungi, modifica o elimina le variabili di ambiente.

  • apphosting.yaml:

    Scopri come creare e modificare il file manualmente.

Le modifiche verranno applicate solo alla prossima implementazione e non influiranno su quella attuale. Salva e crea una nuova implementazione oppure salva le variabili ed esegui il deployment in un secondo momento.

Impostare la disponibilità delle variabili

Le variabili di ambiente create nella console Firebase sono disponibili sia in tempo di compilazione sia in fase di runtime. Questa è anche la condizione predefinita per le variabili definite in apphosting.yaml, a meno che tu non abbia ristretto l'ambito utilizzando la proprietà availability. In apphosting.yaml (ma non nella console), puoi limitare la disponibilità di una variabile di ambiente solo all'ambiente di build o solo all'ambiente di runtime.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    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.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

File dotenv per Next.js

Per le app Next.js, i file dotenv contenenti variabili di ambiente funzionano con App Hosting.

Quando crei o aggiorni un backend, puoi trasferire le variabili di ambiente dal file dotenv alla console Firebase copiando e incollando l'intero contenuto del file dotenv nel primo campo "Chiave" del modulo "Aggiungi nuovo" in Impostazioni variabili di ambiente.

Tutte le variabili di ambiente copiate in questo modo devono essere formattate correttamente nel modulo senza doverle inserire singolarmente, purché l'input abbia un formato simile al seguente:

KEY1=value1
KEY2=value2
KEY3=value3

Per un controllo complesso o granulare delle variabili di ambiente con qualsiasi framework, ti consigliamo di utilizzare apphosting.yaml.

Variabili di ambiente compilate automaticamente

Esistono variabili di ambiente che vengono compilate automaticamente da App Hosting. Queste includono quelle compilate da Google Cloud, nonché le variabili di ambiente specifiche di Firebase quando appId è impostato sul backend durante la configurazione:

  • FIREBASE_CONFIG: (disponibile negli ambienti di build e runtime) fornisce le seguenti informazioni di configurazione del progetto Firebase:

    {
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
  "projectId": 'PROJECT_ID'
}

    Questa configurazione viene applicata automaticamente quando inizializzi l'SDK Admin Firebase senza argomenti.

  • FIREBASE_WEBAPP_CONFIG: (disponibile solo nell'ambiente di build) fornisce le seguenti informazioni di configurazione del progetto Firebase:

    {
  "apiKey": 'API_KEY',
  "appId": 'APP_ID',
  "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "messagingSenderId": 'PROJECT_NUMBER',
  "projectId": 'PROJECT_ID',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
}

    L'SDK Firebase JS verifica automaticamente la presenza di questa FIREBASE_WEBAPP_CONFIG variabile di ambiente in uno script postinstall durante la build, consentendoti di inizializzare l'SDK client senza argomenti.

Per maggiori dettagli su come utilizzare queste variabili di ambiente per inizializzare gli SDK, consulta Inizializzare automaticamente l'SDK Firebase Admin e gli SDK web.

Tieni presente che i valori nella configurazione Firebase effettiva corrisponderanno alle risorse specifiche di cui hai eseguito il provisioning nel progetto.

Gerarchia delle variabili

Firebase App Hosting applica le variabili in un ordine di precedenza in base alla loro origine. Ad esempio, i valori impostati nella console Firebase sostituiscono sempre i valori impostati nei file apphosting.yaml e dotenv o hanno la precedenza su di essi.

Ecco l'ordine di precedenza completo:

  1. Firebase console → variabili impostate nella console
  2. apphosting.<env>.yaml → variabili specificate in un file YAML specifico dell'ambiente, ad esempio apphosting.staging.yaml (vedi Eseguire il deployment di più ambienti)
  3. apphosting.yaml → variabili specificate nel file apphosting.yaml
  4. Sistema Firebase → variabili impostate da Firebase che contengono valori per firebase_config json o firebase_webapp_config, nonché variabili di ambiente che impostano i nomi host e le porte per le app SSR (impostate dagli adattatori di App Hosting in bundle.yaml)

Nomi riservati e limitazioni

Le variabili di ambiente definite nel Cloud Run contratto di runtime del container sono riservate e non possono essere impostate.

Le variabili di ambiente fornite dall'ambiente, diverse da quelle impostate automaticamente, potrebbero cambiare nelle versioni future del runtime. Come best practice, ti consigliamo di non fare affidamento su variabili di ambiente che non hai impostato in modo esplicito né di modificarle e di aggiungere un prefisso a qualsiasi variabile di ambiente con una chiave univoca per evitare conflitti.

Alcune chiavi delle variabili di ambiente sono riservate per uso interno. Non utilizzare queste chiavi nei file di configurazione:

  • Stringhe vuote ("")
  • Chiavi che contengono "="
  • Chiavi che iniziano con X_FIREBASE_, X_GOOGLE_ o CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Chiavi duplicate

Creare e modificare apphosting.yaml

Per la configurazione avanzata, come i secret o le impostazioni di runtime come i limiti di concorrenza, CPU e memoria, devi creare e modificare il file apphosting.yaml nella directory principale dell'app. Questo file supporta i riferimenti ai secret gestiti con Cloud Secret Manager, il che lo rende sicuro per il controllo del codice sorgente.

Per creare apphosting.yaml, esegui il comando seguente:

firebase init apphosting

Viene creato un file apphosting.yaml di base con una configurazione di esempio (commentata). Dopo la modifica, un tipico file apphosting.yaml 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.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

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

Configurare le impostazioni del servizio Cloud Run

Con le impostazioni di apphosting.yaml, puoi configurare il provisioning del servizio Cloud Run. Le impostazioni disponibili per il Cloud Run servizio 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 : numero massimo di container da eseguire contemporaneamente (valore predefinito 100 e gestito dalla 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 l'importante relazione 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 GiB richiede almeno 2 CPU
  • Oltre 8 GiB richiede almeno 4 CPU
  • Oltre 16 GiB richiede almeno 6 CPU
  • Oltre 24 GiB richiede almeno 8 CPU

Allo stesso modo, 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.

Sostituire gli script di build ed esecuzione

App Hosting deduce il comando di build e avvio dell'app in base al framework rilevato. Se vuoi utilizzare un comando di build o avvio personalizzato, puoi sostituire i valori predefiniti di App Hosting in apphosting.yaml.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

La sostituzione del comando di build ha la precedenza su tutti gli altri comandi di build e disattiva gli adattatori del framework e le ottimizzazioni specifiche del framework fornite da App Hosting per la tua app. È consigliabile utilizzarlo quando le funzionalità dell'app non sono ben supportate dagli adattatori. Se vuoi modificare il comando di build ma continuare a utilizzare gli adattatori forniti, imposta lo script di build in package.json invece come descritto in App Hosting adattatori del framework.

Utilizza la sostituzione del comando di esecuzione quando vuoi utilizzare un comando specifico per avviare l'app diverso da quello dedotto da App Hosting.

Configurare l'output di build

App Hosting ottimizza i deployment dell'app per impostazione predefinita eliminando i file di output inutilizzati come indicato dal framework. Se vuoi ottimizzare ulteriormente le dimensioni del deployment dell'app o ignorare le ottimizzazioni predefinite, puoi sostituirle in apphosting.yaml.

outputFiles:
  serverApp:
    include: [dist, server.js]

Il parametro include accetta un elenco di directory e file relativi alla directory principale dell'app necessari per eseguire il deployment dell'app. Se vuoi assicurarti che tutti i file vengano mantenuti, imposta include su [.] e verrà eseguito il deployment di tutti i file.

Archiviare 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 i parametri stringa il cui valore è archiviato in Cloud Secret Manager. Anziché derivare direttamente il valore, i parametri dei secret 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 dei secret disponibile per il backend pubblicato è associato alla versione più recente 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 associarli a versioni specifiche con Cloud Secret Manager. Ad esempio, per associarli alla versione 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Puoi creare secret con il comando CLI Firebase firebase apphosting:secrets:set e ti verrà chiesto di aggiungere le autorizzazioni necessarie. Questo flusso ti consente 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 di Cloud Secret Manager. In questo caso, devi concedere le autorizzazioni al backend App Hosting con il comando CLI Firebase firebase apphosting:secrets:grantaccess.

Configurare l'accesso VPC

Il backend App Hosting può connettersi a una rete Virtual Private Cloud (VPC). Per ulteriori informazioni e un esempio, consulta Connetti Firebase App Hosting a una rete VPC.

Utilizza il mapping vpcAccess nel file apphosting.yaml per configurare l'accesso. Utilizza un nome di rete/connettore completo o un ID. L'utilizzo degli ID consente la portabilità tra gli ambienti di staging e di produzione con connettori/reti diversi.

Configurazione dell'uscita VPC diretta (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

Configurazione del connettore serverless (apphosting.yaml):

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

Gestire i backend

I comandi per la gestione di base dei backend App Hosting sono disponibili nella console Firebase e in CLI Firebase. Questa sezione descrive alcune delle attività di gestione più comuni, tra cui la creazione e l'eliminazione dei backend.

Creare un backend

Un backend App Hosting è l'insieme di risorse gestite che App Hosting crea per creare ed eseguire la tua app web.

Firebase console: vai a Hosting e serverless > App Hosting, e fai clic su Crea backend (se è il primo backend nel tuo progetto Firebase, fai clic su Inizia).

Firebase CLI: (versione 13.15.4 o successive) per creare un backend, esegui il comando seguente dalla directory principale della directory del progetto locale, fornendo l' ID progetto come argomento:

firebase apphosting:backends:create --project PROJECT_ID

Sia per la console sia per l'interfaccia a riga di comando, segui le istruzioni per scegliere una regione, configurare una connessione GitHub, e configurare queste impostazioni di deployment di base:

  • Imposta la directory principale dell'app (il valore predefinito è /)

    In genere qui si trova il file package.json.

  • Imposta il branch pubblicato

    Questo è il branch del tuo repository GitHub di cui viene eseguito il deployment nell'URL pubblicato. Spesso è il branch in cui vengono uniti i branch delle funzionalità o di sviluppo.

  • Accetta o rifiuta le implementazioni automatiche

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

  • Assegna un nome al backend.

Eliminare un backend

Per rimuovere completamente un backend, utilizza prima la Firebase console o la Firebase CLI per eliminarlo, quindi rimuovi manualmente gli asset correlati, facendo attenzione a non eliminare le risorse che potrebbero essere utilizzate da altri backend o da altri aspetti del tuo progetto Firebase.

Firebase console: dal menu Impostazioni, seleziona Elimina backend.

Firebase CLI: (versione 13.15.4 o successive)

  1. Esegui il comando seguente per eliminare il backend App Hosting. In questo modo, tutti i domini del backend vengono disattivati e il servizio associato Cloud Run viene eliminato:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

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

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