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. Questa guida descrive questi strumenti e queste 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, devi 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 il comando seguente:
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.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 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 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.firebasestorage.app
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.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
Le chiavi di variabile 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_ PORTK_SERVICEK_REVISIONK_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 segreto disponibile per il backend live è bloccato sull'ultima versione disponibile del segreto al momento della compilazione 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 tuo backend App Hosting con il comando CLI firebase
apphosting:secrets:grantaccess.
Sincronizzare lo stato di Firebase Auth
Le app che utilizzano Firebase Auth dovrebbero prendere in considerazione l'utilizzo dell'SDK web Firebase per mantenere sincronizzato lo stato di autenticazione tra client e server. Questa operazione può essere facilitata implementando FirebaseServerApp con un servizio worker. Il flusso di lavoro di base è il seguente:
- Implementa un service worker che aggiunge le intestazioni corrette per la tua app alle richieste al server.
- Recupera le intestazioni dalla richiesta sul server e convertile in un utente di autenticazione 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 creare ed eseguire la tua app web. Qualsiasi proprietario del progetto può creare il primo backend App Hosting per un progetto utilizzando la console Firebase o Firebase CLI. Dopo questa configurazione iniziale, gli amministratori App Hosting possono anche creare e gestire backend aggiuntivi. Per maggiori dettagli, consulta Firebase App Hosting Ruoli IAM.
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 la CLI, segui le istruzioni per assegnare un nome al backend, per configurare una connessione GitHub e per 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 live
Si tratta del ramo del tuo repository GitHub che viene eseguito nel tuo URL attivo. 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.
Esegui il seguente 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(Facoltativo) Nella scheda della console Google Cloud per Artifact Registry, elimina l'immagine per il tuo backend in "firebaseapphosting-images".
In Cloud Secret Manager, elimina tutti i 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.