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.
Creare e modificare apphosting.yaml
Per la configurazione avanzata, ad esempio variabili di ambiente 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 anche
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.
Configura l'ambiente
A volte è necessaria una configurazione aggiuntiva per il processo di build, ad esempio
chiavi API di terze parti o impostazioni modificabili. 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, i file dotenv contenenti
variabili di ambiente
funzioneranno
anche con App Hosting. Ti consigliamo di utilizzare apphosting.yaml per un 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 build o solo per l'ambiente 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 delle variabili valide sono composte 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
Eseguire l'override degli script di build ed esecuzione
App Hosting deduce il comando di build e di 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. È meglio usarlo 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 App Hosting dedotto.
Configura l'output della 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 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 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 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 confrontati con l'esistenza 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
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 maggiori informazioni ed un esempio, consulta Connetti Firebase App Hosting a una rete VPC.
Utilizza la mappatura vpcAccess nel file apphosting.yaml per configurare l'accesso.
Utilizza un nome di rete completo o un ID. L'utilizzo degli ID consente
la portabilità tra gli ambienti di gestione temporanea e di produzione con connettori/reti diversi.
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
Gestisci i 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.
Console Firebase: dal menu Build, seleziona App Hosting e poi Inizia.
CLI: (versione 13.15.4 o successive) Per creare un backend, esegui il seguente comando dalla radice della directory del progetto locale, fornendo il tuo projectID come argomento:
firebase apphosting:backends:create --project PROJECT_ID
Per la console o 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 è
/)Di solito è qui che si trova il file
package.json.
Impostare il ramo live
Questo è il ramo del repository GitHub di cui viene eseguito il deployment nell'URL live. 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)
Esegui questo comando per eliminare il backend App Hosting. Questa operazione disattiva tutti i domini per il backend ed elimina il servizio Cloud Run associato:
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID(Facoltativo) Nella scheda della console Google Cloud per Artifact Registry, elimina l'immagine per il backend in "firebaseapphosting-images".
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 altri aspetti del tuo progetto Firebase.