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 procedure.

Impostare e aggiornare le variabili di ambiente

A volte potrebbe essere necessaria una configurazione aggiuntiva per il processo di build. 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 è il modo più rapido per iniziare. Utilizza apphosting.yaml se devi archiviare e accedere ai parametri secret, impostare variabili disponibili solo in fase di build o runtime o condividere variabili di ambiente in più ambienti. Sia con la console che con apphosting.<env>.yaml, puoi impostare valori diversi per ambienti diversi.

Console Firebase

apphosting.yaml

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

Attenzione :la configurazione basata sulla console e quella basata sui file presentano alcune differenze chiave, quindi assicurati di esaminare attentamente questa sezione. Ancora più importante: i valori impostati nella console hanno sempre la precedenza sui valori impostati in apphosting.yaml. Consulta la gerarchia delle variabili.

Aggiorna variabili

Puoi aggiungere e modificare le variabili di ambiente nella console Firebase nella scheda Impostazioni di un backend. Vai a Visualizza backend >> Impostazioni >> Ambiente e poi aggiungi, modifica o elimina le variabili di ambiente.

Per aggiungere e modificare le variabili di ambiente in apphosting.yaml,, crea e modifica 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 e esegui il deployment in un secondo momento.

Impostare la disponibilità delle variabili

Le variabili di ambiente create nella console Firebase sono disponibili sia in fase di build 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 una variabile di ambiente in modo che sia disponibile solo per l'ambiente di build o solo per l'ambiente 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 in modo ordinato nel modulo senza la necessità di inserirle singolarmente, purché l'input abbia un formato come il 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.

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 hanno sempre la precedenza sui valori impostati nei file apphosting.yaml e dotenv.

Suggerimento :nella console Firebase puoi fare clic su un'implementazione specifica per visualizzarne i dettagli. Vai a Variabili di ambiente in questa build nella parte inferiore del riquadro dei dettagli del lancio per esaminare l'elenco delle variabili di ambiente utilizzate durante il lancio e le relative origini.

Ecco l'ordine di precedenza completo:

1. Console Firebase → 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 chiavi delle variabili valide devono iniziare con una lettera maiuscola e contenere solo lettere maiuscole, cifre e trattini bassi. Alcune chiavi delle variabili di ambiente sono riservate per uso interno. Non utilizzare nessuna di queste chiavi nei file di configurazione:

• Stringhe vuote ("")
• Variabili che contengono "="
• Qualsiasi variabile che inizia con X_FIREBASE_
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION
• Chiavi duplicate

Creare e modificare apphosting.yaml

Per la configurazione avanzata, ad esempio segreti o impostazioni di runtime come 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 da archiviare nel controllo del codice sorgente.

Per creare apphosting.yaml, esegui questo comando:

firebase init apphosting

In questo modo viene creato un file apphosting.yaml di base con una configurazione di esempio (commentata). Dopo la modifica, un tipico file apphosting.yaml potrebbe essere simile al seguente, 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 maggiori informazioni e contesto per queste impostazioni di esempio.

Configura 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 servizio Cloud Run sono fornite nell'oggetto runConfig:

• cpu: numero di CPU utilizzate per ogni istanza di gestione (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 di 100 e gestito dalla quota)
• minInstances: numero di container da mantenere sempre attivi (il valore predefinito è 0).
• concurrency: numero massimo di richieste che ogni istanza di gestione 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:

• Più di 4 GiB richiedono almeno 2 CPU
• Più di 8 GB richiedono almeno 4 CPU
• Più di 16 GiB richiedono almeno 6 CPU
• Più di 24 GiB richiedono 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.

Eseguire l'override degli 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 di avvio personalizzato, puoi sostituire i valori predefiniti di App Hosting in apphosting.yaml.

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

L'override del comando di build ha la precedenza su qualsiasi altro comando di build e disattiva gli adattatori del framework e le ottimizzazioni specifiche del framework fornite da App Hosting per la tua app. È meglio 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 come descritto in Adattatori framework App Hosting.

Utilizza l'override del comando di esecuzione quando vuoi utilizzare un comando specifico per avviare l'app diverso dal comando dedotto App Hosting.

Configura l'output della build

App Hosting ottimizza i deployment delle 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 eseguire l'override 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 il deployment dell'app. Se vuoi assicurarti che tutti i file vengano conservati, imposta include su [.] e tutti i file verranno sottoposti a deployment.

Archivia e accedi ai parametri secret

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

I parametri di tipo secret rappresentano parametri stringa con un valore memorizzato in Cloud Secret Manager. Anziché derivare direttamente il valore, i parametri secret vengono controllati in Cloud Secret Manager e i valori vengono caricati 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 secret disponibile per il backend live è bloccato sulla 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 eseguire il pinning a 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 CLI firebase apphosting:secrets:set 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 invece la console Cloud Secret Manager. In questo caso, dovrai concedere le autorizzazioni al backend App Hosting con il comando CLI firebase apphosting:secrets:grantaccess.

Configura l'accesso VPC

Il backend App Hosting può connettersi a una rete Virtual Private Cloud (VPC). Per ulteriori informazioni ed esempi, consulta Connettere 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 gestione temporanea 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

Gestisci backend

I comandi per la gestione di base dei backend App Hosting sono forniti nell'interfaccia a riga di comando Firebase e nella console Firebase. Questa sezione descrive 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.

Un proprietario del progetto deve creare il primo backend App Hosting. Dopo questa configurazione iniziale, App Hosting gli amministratori possono anche creare e gestire backend aggiuntivi. Per visualizzare tutti i repository della tua organizzazione, assicurati di disporre del ruolo di amministratore dell'organizzazione in GitHub. Un ruolo di membro standard mostra solo i repository che hai creato personalmente. Per maggiori dettagli, vedi Ruoli IAM di Firebase App Hosting.

Console Firebase: dal menu Build, seleziona App Hosting e poi Crea backend (se questo è il primo backend nel tuo progetto Firebase, seleziona Inizia).

CLI: (versione 13.15.4 o successive) Per creare un backend, esegui il seguente comando dalla directory principale del progetto locale, fornendo il tuo projectID come argomento:

firebase apphosting:backends:create --project PROJECT_ID

Per la console o la CLI, 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 è /)

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

• Impostare il branch live

  Questo è il branch del tuo repository GitHub di cui viene eseguito il deployment nell'URL pubblicato. Spesso è il ramo in cui vengono uniti i rami delle 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.

• Assegna un nome al backend.

Elimina un backend

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

Console Firebase: dal menu Impostazioni, seleziona Elimina backend.

CLI: (versione 13.15.4 o successive)

1. Esegui questo comando per eliminare il backend App Hosting. Questa azione disabilita tutti i domini per il backend ed elimina il servizio Cloud Run associato:

   firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
   

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

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