App Hosting a été conçu pour être facile à utiliser et nécessiter peu d'entretien, avec des paramètres par défaut optimisés pour la plupart des cas d'utilisation. En parallèle, App Hosting fournit des outils vous permettant de gérer et de configurer les backends en fonction de vos besoins spécifiques. Le présent guide décrit ces outils et processus.
Configurer un backend
Pour les configurations avancées telles que les variables d'environnement ou les paramètres d'exécution tels que la simultanéité, le processeur et les limites de mémoire, vous devez créer et modifier le fichier apphosting.yaml dans le répertoire racine de votre application. Ce fichier accepte également les références aux secrets gérés avec Cloud Secret Manager, ce qui permet de les vérifier en toute sécurité dans le contrôle de source.
Pour créer apphosting.yaml, exécutez la commande suivante :
firebase init apphosting
Un fichier apphosting.yaml de démarrage de base est créé avec un exemple de configuration (commenté). Après modification, un fichier apphosting.yaml typique peut se présenter comme suit, avec des paramètres pour le service Cloud Run du backend, certaines variables d'environnement et des références à des secrets gérés par Secret Manager Cloud :
# 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
Le reste de ce guide fournit plus d'informations et de contexte sur ces exemples de paramètres.
Configurer les paramètres du service Cloud Run
Les paramètres apphosting.yaml vous permettent de configurer la façon dont votre service Cloud Run est provisionné. Les paramètres disponibles pour le service Cloud Run sont fournis dans l'objet runConfig:
cpu: nombre de processeurs utilisés pour chaque instance de diffusion (par défaut, 0).memoryMiB: quantité de mémoire allouée pour chaque instance de diffusion en Mio (512 par défaut)maxInstances: nombre maximal de conteneurs pouvant être exécutés à la fois (100 par défaut et géré par quota)minInstances: nombre de conteneurs à maintenir en permanence (par défaut : 0).concurrency: nombre maximal de requêtes que chaque instance de diffusion peut recevoir (80 par défaut).
Notez la relation importante entre cpu et memoryMiB. La mémoire peut être définie sur n'importe quelle valeur entière comprise entre 128 et 32 768, mais augmenter la limite de mémoire peut nécessiter d'augmenter les limites de processeur:
- Les commandes supérieures à 4 Gio nécessitent au moins deux processeurs.
- Plus de 8 Gio nécessitent au moins quatre processeurs
- Plus de 16 Gio nécessitent au moins six CPU
- Plus de 24 Gio nécessitent au moins huit processeurs
De même, la valeur de cpu affecte les paramètres de simultanéité. Si vous définissez une valeur inférieure à 1 CPU, vous devez définir la simultanéité sur 1. Le processeur ne sera alors alloué que lors du traitement des requêtes.
Configurer l'environnement de compilation
Vous devrez parfois configurer des éléments supplémentaires pour votre processus de compilation, tels que des clés d'API tierces ou des paramètres ajustables. App Hosting propose une configuration d'environnement dans apphosting.yaml pour stocker et récupérer ce type de données pour votre projet.
env:
- variable: STORAGE_BUCKET
value: mybucket.appspot.com
Pour les applications Next.js, les fichiers dotenv contenant des variables d'environnement fonctionneront également avec App Hosting. Nous vous recommandons d'utiliser apphosting.yaml pour un contrôle précis des variables d'environnement avec n'importe quel framework.
Dans apphosting.yaml, vous pouvez spécifier les processus ayant accès à votre variable d'environnement à l'aide de la propriété availability. Vous pouvez limiter la disponibilité d'une variable d'environnement à l'environnement de compilation ou uniquement à l'environnement d'exécution. Par défaut, il est disponible pour les deux.
env:
- variable: STORAGE_BUCKET
value: mybucket.appspot.com
availability:
- BUILD
- RUNTIME
Pour les applications Next.js, vous pouvez également utiliser le préfixe NEXT_PUBLIC_ de la même manière que dans votre fichier dotenv pour rendre une variable accessible dans le navigateur.
env:
- variable: NEXT_PUBLIC_STORAGE_BUCKET
value: mybucket.appspot.com
availability:
- BUILD
- RUNTIME
Les clés de variable valides sont composées de caractères de l'alphabet A-Z ou de traits de soulignement. Certaines clés de variable d'environnement sont réservées à un usage interne. N'utilisez aucune de ces clés dans vos fichiers de configuration:
- Toute variable commençant par
X_FIREBASE_ PORTK_SERVICEK_REVISIONK_CONFIGURATION
Stocker et accéder aux paramètres de secret
Les informations sensibles telles que les clés API doivent être stockées en tant que secrets. Vous pouvez faire référence à des secrets dans apphosting.yaml pour éviter de vérifier des informations sensibles dans le système de gestion des versions.
Les paramètres de type secret représentent les paramètres de chaîne dont la valeur est stockée dans Cloud Secret Manager.
Au lieu de dériver directement la valeur, les paramètres du secret vérifient qu'ils existent dans Cloud Secret Manager et chargent les valeurs lors du déploiement.
- variable: API_KEY
secret: myApiKeySecret
Les secrets dans Cloud Secret Manager peuvent avoir plusieurs versions. Par défaut, la valeur d'un paramètre de secret disponible pour votre backend actif est épinglée sur la dernière version disponible du secret au moment de la création du backend. Si vous avez des exigences de gestion des versions et du cycle de vie des paramètres, vous pouvez épingler des versions spécifiques avec Cloud Secret Manager. Par exemple, pour épingler la version 5 :
- variable: PINNED_API_KEY
secret: myApiKeySecret@5
Vous pouvez créer des secrets avec la commande CLI firebase apphosting:secrets:set. Vous serez alors invité à ajouter les autorisations nécessaires. Ce flux vous permet d'ajouter automatiquement la référence secrète à apphosting.yaml.
Pour utiliser l'ensemble des fonctionnalités de Cloud Secret Manager, vous pouvez utiliser la console Cloud Secret Manager. Dans ce cas, vous devez accorder des autorisations à votre backend App Hosting à l'aide de la commande CLI firebase
apphosting:secrets:grantaccess.
Synchroniser l'état de Firebase Auth
Les applications qui utilisent Firebase Auth doivent envisager d'utiliser le SDK Web Firebase pour synchroniser l'état d'authentification entre le client et le serveur. Pour ce faire, implémentez FirebaseServerApp avec un service worker. Le flux de tâches de base est le suivant:
- Implémentez un service worker qui ajoute les en-têtes appropriés pour votre application sur les requêtes envoyées au serveur.
- Récupérez les en-têtes de la requête sur le serveur et convertissez-les en utilisateur auth avec
FirebaseServerApp.
Gérer les backends
Les commandes de gestion de base des backends App Hosting sont fournies dans la CLI Firebase. Certaines opérations sont également disponibles dans la console Firebase. Cette section décrit certaines des tâches de gestion les plus courantes, y compris la création et la suppression de backends.
Créer un backend
Un backend App Hosting est l'ensemble de ressources gérées que App Hosting crée pour compiler et exécuter votre application Web. Vous pouvez créer et lister des backends App Hosting à l'aide de la console Firebase ou de la CLI Firebase.
Console Firebase : dans le menu Créer, sélectionnez Hébergement d'applications, puis Premiers pas.
CLI : (version 13.15.4 ou ultérieure) pour créer un backend, exécutez la commande suivante à partir de la racine du répertoire de votre projet local, en indiquant l'ID de projet et la région de votre choix comme arguments:
firebase apphosting:backends:create --project PROJECT_ID --location us-central1
Pour la console ou la CLI, suivez les instructions pour attribuer un nom à votre backend, configurer une connexion GitHub et configurer les paramètres de déploiement de base suivants:
Définissez le répertoire racine de votre application (par défaut,
/)C'est généralement là que se trouve votre fichier
package.json.
Définir la branche en direct
Il s'agit de la branche de votre dépôt GitHub qui est déployée sur votre URL en ligne. Il s'agit souvent de la branche dans laquelle les branches de fonctionnalités ou de développement sont fusionnées.
Accepter ou refuser les déploiements automatiques
Les déploiements automatiques sont activés par défaut. Une fois le backend créé, vous pouvez choisir de déployer immédiatement votre application sur App Hosting.
Supprimer un backend
Pour supprimer complètement un backend, commencez par utiliser la CLI Firebase, puis supprimez manuellement les composants associés, en veillant à ne pas supprimer les ressources susceptibles d'être utilisées par d'autres backends ou d'autres aspects de votre projet Firebase.
Exécutez la commande suivante pour supprimer le backend App Hosting. Cette opération désactive tous les domaines de votre backend et supprime le service Cloud Run associé :
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1(Facultatif) Dans l'onglet de la console Google Cloud pour Artifact Registry, supprimez l'image de votre backend dans "firebaseapphosting-images".
Dans Cloud Secret Manager, supprimez tous les secrets contenant "apphosting" dans le nom du secret, en veillant particulièrement à vous assurer que ces secrets ne sont pas utilisés par d'autres backends ou d'autres aspects de votre projet Firebase.