Configurer et gérer des backends App Hosting

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 vous fournit des outils pour gérer et configurer les backends en fonction de vos besoins spécifiques. Ce guide décrit ces outils et processus.

Configurer un backend

Pour une configuration avancée, comme 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 traitement 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:

  • Plus de 4 Gio nécessitent au moins deux CPU
  • Plus de 8 Gio nécessitent au moins quatre processeurs
  • Plus de 16 Gio nécessitent au moins six processeurs.
  • 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 aurez parfois besoin d'une configuration supplémentaire pour votre processus de compilation, comme des clés d'API tierces ou des paramètres réglables. 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 une variable d'environnement à être disponible uniquement pour l'environnement de compilation ou uniquement pour 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 latin (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_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_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 des 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 secrets vérifient son existence 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 en direct est épinglée à la dernière version disponible du secret au moment de la création du backend. Si vous avez des exigences concernant la 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 devrez accorder des autorisations à votre backend App Hosting avec 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, vous pouvez implémenter FirebaseServerApp avec un service worker. Le flux de tâches de base est le suivant:

  1. Implémentez un service worker qui ajoute les en-têtes appropriés pour votre application sur les requêtes envoyées au serveur.
  2. Obtenez les en-têtes de la requête sur le serveur, puis convertissez-les en utilisateur authentifié 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 fournissant votre projectID et la région de votre choix comme arguments:

firebase apphosting:backends:create --project PROJECT_ID --location us-central1

Dans la console ou la CLI, suivez les invites pour attribuer un nom à votre backend, configurer une connexion GitHub et configurer ces paramètres de déploiement de base:

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

  1. Exécutez la commande suivante pour supprimer le backend App Hosting. Tous les domaines de votre backend sont alors désactivés, et le service Cloud Run associé est supprimé:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1
    
  2. (Facultatif) Dans l'onglet Google Cloud Console de Artifact Registry, supprimez l'image de votre backend dans "firebaseapphosting-images".

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