Configurer et gérer des backends App Hosting

App Hosting a été conçu pour être facile à utiliser et à entretenir, avec des paramètres par défaut optimisés pour la plupart des cas d'utilisation. En même temps, App Hosting 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 (simultanéité, limites de processeur et de mémoire, etc.), vous devrez 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 l'enregistrer dans le contrôle de la source en toute sécurité.

Pour créer apphosting.yaml, exécutez la commande suivante :

firebase init apphosting

Cela crée un fichier apphosting.yaml de base avec un exemple de configuration (commenté). Après modification, un fichier apphosting.yaml standard peut se présenter comme suit, avec des paramètres pour le service Cloud Run du backend, des variables d'environnement et des références à des secrets gérés par 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

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 (0 par défaut).
  • memoryMiB : quantité de mémoire allouée à chaque instance de diffusion en Mio (512 par défaut)
  • maxInstances : nombre maximal de conteneurs pouvant être exécutés simultanément (par défaut, 100 et géré par le quota)
  • minInstances : nombre de conteneurs à maintenir en vie (0 par défaut).
  • 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 l'augmentation de la limite de mémoire peut nécessiter l'augmentation des limites de processeur :

  • Plus de 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 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 à un processeur, vous devez définir la simultanéité sur 1. Le processeur ne sera 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 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 qui ont 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 à 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 variables valides sont composées de caractères A-Z ou de traits de soulignement. Certaines clés de variables 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

Remplacer les scripts de compilation et d'exécution

App Hosting déduit 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 remplacement de la commande de compilation prévaut sur toutes les autres commandes de compilation. Il désactive les adaptateurs de framework et toutes les optimisations spécifiques au framework fournies par App Hosting pour votre application. 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 continuer à utiliser nos adaptateurs fournis, définissez votre script de compilation dans package.json, comme décrit dans Adaptateurs de framework App Hosting.

Utilisez le remplacement de la commande d'exécution lorsqu'une commande spécifique est requise pour démarrer votre application, différente de la commande déduite 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 remplacer cette valeur dans apphosting.yaml.

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

Le paramètre include accepte une liste de répertoires et de fichiers relatifs au répertoire racine de l'application, qui sont nécessaires au déploiement de votre application. Si vous souhaitez vous assurer que tous les fichiers sont conservés, définissez "include" sur [.]. Tous les fichiers seront alors déployés.

Stocker des paramètres secrets et y accéder

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 d'inclure 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 l'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 secret disponible pour votre backend en direct est épinglée à la dernière version disponible du secret au moment où le backend a été créé. Si vous avez des exigences concernant la gestion des versions et du cycle de vie des paramètres, vous pouvez les é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 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

Votre 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 la portabilité 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 permettant de gérer de base les backends App Hosting sont fournies dans la CLI Firebaseet 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 des ressources gérées que App Hosting crée pour concevoir et exécuter votre application Web.

Console Firebase : dans le menu Créer, sélectionnez App Hosting, 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 comme argument :

firebase apphosting:backends:create --project PROJECT_ID

Que vous utilisiez la console ou la CLI, suivez les instructions pour choisir une région, configurer une connexion GitHub et définir 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éfinissez 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 direct. Il s'agit souvent de la branche dans laquelle les branches de fonctionnalité 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 utiliser la CLI Firebase ou la console Firebase pour le supprimer, puis supprimez manuellement les ressources associées. Veillez tout particulièrement à ne pas supprimer les ressources qui pourraient ê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. 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

  2. (Facultatif) Dans l'onglet Google Cloud Console pour Artifact Registry, supprimez l'image de votre backend dans "firebaseapphosting-images".

  3. Dans Cloud Secret Manager, supprimez tous les secrets dont le nom contient "apphosting", en veillant tout particulièrement à ce que ces secrets ne soient pas utilisés par d'autres backends ni par d'autres aspects de votre projet Firebase.