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.

Créer et modifier des apphosting.yaml

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

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

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.firebasestorage.app

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 à l'environnement de compilation ou à l'environnement d'exécution uniquement. Par défaut, il est disponible pour les deux.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    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.firebasestorage.app
    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_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION

Forcer des scripts de compilation et d'exécution

App Hosting infère la commande de compilation et de démarrage de votre application en fonction du framework détecté. Si vous souhaitez utiliser une commande de compilation ou de démarrage personnalisée, vous pouvez remplacer les valeurs par défaut de App Hosting dans apphosting.yaml.

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

Le forçage de la commande de compilation prévaut sur toutes les autres commandes de compilation. Il désactive les adaptateurs de framework et les optimisations spécifiques au framework fournies par App Hosting. Il est préférable de l'utiliser lorsque les fonctionnalités de votre application ne sont pas bien prises en charge par les adaptateurs. Si vous souhaitez modifier votre commande de compilation, mais que vous souhaitez tout de même utiliser les adaptateurs fournis, définissez plutôt votre script de compilation dans package.json, comme décrit dans la section Adaptateurs de framework App Hosting.

Utilisez le forçage de la commande d'exécution lorsque vous souhaitez utiliser une commande spécifique pour démarrer votre application, qui est différente de la commande inférée par App Hosting.

Configurer la sortie de compilation

App Hosting optimise les déploiements de votre application par défaut en supprimant les fichiers de sortie inutilisés, comme indiqué par le framework. Si vous souhaitez optimiser davantage la taille de déploiement de votre application ou ignorer les optimisations par défaut, vous pouvez le remplacer dans apphosting.yaml.

outputFiles:
  serverApp:
    include: [dist, server.js]

Le paramètre include reçoit une liste de répertoires et de fichiers par rapport au répertoire racine de l'application qui sont nécessaires pour déployer votre application. Si vous souhaitez vous assurer que tous les fichiers sont conservés, définissez include sur [.] et tous les fichiers seront déployés.

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.

Configurer l'accès au VPC

Le backend App Hosting peut se connecter à un réseau de cloud privé virtuel (VPC). Pour en savoir plus et obtenir un exemple, consultez Connecter Firebase App Hosting à un réseau VPC.

Utilisez le mappage vpcAccess dans votre fichier apphosting.yaml pour configurer l'accès. Utilisez un nom de réseau complet ou un ID. L'utilisation d'ID permet de transférer des données entre les environnements de préproduction et de production avec différents connecteurs/réseaux.

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

Gérer les backends

Les commandes de gestion de base des backends App Hosting sont fournies dans la CLI Firebase et 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 créer et exécuter votre application Web.

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 choisir une région, 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.

  • Attribuez un nom à votre backend.

Supprimer un backend

Pour supprimer complètement un backend, commencez par le supprimer à l'aide de la CLI Firebase ou de la console 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.

Console Firebase: dans le menu Paramètres, sélectionnez Supprimer le backend.

CLI:version 13.15.4 ou ultérieure

  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.