Configurer et gérer des backends App Hosting

App Hosting a été conçu pour être facile à utiliser et nécessiter peu de maintenance, 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.

Définir et mettre à jour des variables d'environnement

Vous pouvez parfois avoir besoin d'une configuration supplémentaire pour votre processus de compilation. App Hosting propose une configuration d'environnement pour stocker et récupérer ce type de données pour votre projet via la console Firebase et, en alternative, dans apphosting.yaml.

Définir des variables d'environnement dans la Firebase console est le moyen le plus rapide de commencer. Utilisez apphosting.yaml si vous devez stocker des paramètres secrets et y accéder, définir des variables qui ne sont disponibles qu'au moment de la compilation ou de l'exécution, ou partager des variables d'environnement entre plusieurs environnements. Avec la console et apphosting.<env>.yaml, vous pouvez définir différentes valeurs pour différents environnements.

Firebase console

Capture d'écran de la boîte de dialogue de la console Firebase permettant d'ajouter des variables d'environnement

`apphosting.yaml`

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

Mettre à jour des variables

Vous pouvez ajouter, modifier ou supprimer des variables d'environnement dans la Firebase console ou à l'aide de votre apphosting.yaml :

Firebase console:
1. Dans la console Firebase, accédez à Hosting & Serverless > App Hosting.
2. Accédez à View Backend > Settings > Environment.
3. Ajoutez, modifiez ou supprimez des variables d'environnement.
apphosting.yaml:

Découvrez comment créer et modifier le fichier manuellement.

Vos modifications ne prendront effet que lors de votre prochain déploiement et n'affecteront pas le déploiement actuel. Enregistrez et créez un déploiement ou enregistrez vos variables et déployez-les ultérieurement.

Définir la disponibilité des variables

Les variables d'environnement créées dans la Firebase console sont disponibles au moment de la compilation et de l'exécution. Il s'agit également de la condition par défaut pour les variables définies dans apphosting.yaml, sauf si vous avez limité cette portée à l'aide de la propriété availability. Dans apphosting.yaml (mais pas dans la console), vous pouvez limiter une variable d'environnement pour qu'elle ne soit disponible que dans l'environnement de compilation ou uniquement dans l'environnement d'exécution.

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

Fichiers `dotenv` pour Next.js

Pour les applications Next.js, les fichiers dotenv contenant des variables d'environnement fonctionnent avec App Hosting.

Lorsque vous créez ou mettez à jour un backend, vous pouvez transférer des variables d'environnement de votre dotenv fichier vers la Firebase console en copiant et en collant l'intégralité du contenu du dotenv fichier dans le premier champ "Clé" du formulaire "Ajouter" dans Paramètres des variables d'environnement.

Toutes les variables d'environnement copiées de cette manière doivent être correctement mises en forme dans le formulaire sans qu'il soit nécessaire de les saisir individuellement, à condition que l'entrée présente un format semblable à celui-ci :

KEY1=value1
KEY2=value2
KEY3=value3

Pour un contrôle complexe ou précis des variables d'environnement avec n'importe quel framework, nous vous recommandons d'utiliser apphosting.yaml.

Variables d'environnement renseignées automatiquement

Certaines variables d'environnement sont renseignées automatiquement par App Hosting. Il s'agit de celles renseignées par Google Cloud, ainsi que des variables d'environnement spécifiques à Firebase lorsque appId est défini sur le backend lors de la configuration :

FIREBASE_CONFIG: (disponible dans les environnements de compilation et d'exécution) fournit les informations de configuration du projet Firebase suivantes :
```
{
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
  "projectId": 'PROJECT_ID'
}
```
Cette configuration est appliquée automatiquement lorsque vous initialisez le SDK Firebase Admin sans aucun argument.
FIREBASE_WEBAPP_CONFIG: (disponible uniquement dans l'environnement de compilation) fournit les informations de configuration du projet Firebase suivantes :
```
{
  "apiKey": 'API_KEY',
  "appId": 'APP_ID',
  "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "messagingSenderId": 'PROJECT_NUMBER',
  "projectId": 'PROJECT_ID',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
}
```
Le SDK Firebase JS recherche automatiquement cette variable d'environnement FIREBASE_WEBAPP_CONFIG dans un script post-installation lors de la compilation, ce qui vous permet également d'initialiser le SDK client sans aucun argument.

Pour en savoir plus sur l'utilisation de ces variables d'environnement pour initialiser les SDK, consultez Initialiser automatiquement le SDK Firebase Admin et les SDK Web.

Notez que les valeurs de votre configuration Firebase réelle correspondent aux ressources spécifiques que vous avez provisionnées dans votre projet.

Hiérarchie des variables

Firebase App Hosting applique vos variables par ordre de priorité en fonction de leur source. Par exemple, les valeurs définies dans la console Firebase remplacent toujours celles définies dans les fichiers apphosting.yaml et dotenv.

Voici l'ordre de priorité complet :

Firebase console → variables définies dans la console
apphosting.<env>.yaml → variables spécifiées dans un fichier YAML spécifique à l'environnement, tel que apphosting.staging.yaml (voir Déployer plusieurs environnements)
apphosting.yaml → variables spécifiées dans le fichier apphosting.yaml
Système Firebase → variables définies par Firebase qui contiennent des valeurs pour firebase_config json ou firebase_webapp_config, ainsi que des variables d'environnement qui définissent les noms d'hôte et les ports pour les applications SSR (définies par les adaptateurs App Hosting dans bundle.yaml)

Noms réservés et limites

Les variables d'environnement définies dans le Cloud Run contrat d'exécution du conteneur sont réservées et ne peuvent pas être définies.

Les variables d'environnement fournies par l'environnement, autres que celles définies automatiquement, pourront faire l'objet de modifications dans des versions d'exécution ultérieures. Nous vous recommandons de ne pas modifier ni dépendre de variables d'environnement que vous n'avez pas définies explicitement, et d'envisager de préfixer les variables d'environnement à l'aide d'une clé unique pour éviter tout conflit.

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 :

Chaînes vides ("")
Clés contenant "="
Clés commençant par X_FIREBASE_, X_GOOGLE_ ou CLOUD_RUN_
PORT
K_SERVICE
K_REVISION
K_CONFIGURATION
Clés en double

Créer et modifier `apphosting.yaml`

Pour une configuration avancée, telle que les secrets 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 les références aux secrets gérés avec Cloud Secret Manager, ce qui permet de l'inclure dans le système de gestion des versions 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ée). Après modification, un fichier apphosting.yaml type peut se présenter comme suit, avec des paramètres pour le service Cloud Run du backend, certaines variables d'environnement et quelques 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 pour ces exemples de paramètres.

Configurer les paramètres du service Cloud Run

Avec les paramètres apphosting.yaml, vous pouvez configurer la manière dont votre Cloud Run service est provisionné. Les paramètres disponibles pour le Cloud Run service sont fournis dans l'runConfig objet :

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 à exécuter à la fois (100 par défaut et géré par le quota)
minInstances : nombre de conteneurs à maintenir en permanence (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écessite au moins 2 processeurs
Plus de 8 Gio nécessite au moins 4 processeurs
Plus de 16 Gio nécessite au moins 6 processeurs
Plus de 24 Gio nécessite au moins 8 processeurs

De même, la valeur de cpu affecte les paramètres de simultanéité. Si vous définissez une valeur inférieure à 1 processeur, vous devez définir la simultanéité sur 1, et le processeur ne sera alloué que lors du traitement des requêtes.

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's 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 et désactive les adaptateurs de framework et toutes 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 compatibles avec les adaptateurs. Si vous souhaitez modifier votre commande de compilation mais continuer à utiliser les adaptateurs fournis, définissez votre script de compilation dans package.json au lieu de cela, comme décrit dans App Hosting adaptateurs de framework.

Utilisez le remplacement de la commande d'exécution lorsqu'une commande spécifique que vous souhaitez utiliser pour démarrer votre application est différente de celle App Hosting-déduite.

Configurer la sortie de compilation

App Hosting optimise par défaut les déploiements de votre application 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 ce paramètre dans apphosting.yaml.

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

Le paramètre include accepte une liste de répertoires et de fichiers par rapport 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 [.] et tous les fichiers seront 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 référencer 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 actif est associée à la dernière version disponible du secret au moment de la compilation du backend. Si vous avez des exigences concernant la gestion des versions et du cycle de vie des paramètres, vous pouvez associer des versions spécifiques à Cloud Secret Manager. Par exemple, pour associer la version 5 :

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Vous pouvez créer des secrets avec la commande CLI Firebase firebase apphosting:secrets:set, et 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. Si vous le faites, vous devrez accorder des autorisations à votre App Hosting backend avec la Firebase CLI command firebase apphosting:secrets:grantaccess.

Configurer l'accès au VPC

Votre backend App Hosting peut se connecter à un réseau 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/connecteur 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.

Configuration de la sortie VPC directe (`apphosting.yaml`) :

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

Configuration du connecteur sans serveur (`apphosting.yaml`) :

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Gérer les backends

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

Firebase console : accédez à Hosting & Serverless > App Hosting, puis cliquez sur Create backend (Créer un backend) (s'il s'agit du premier backend de votre projet Firebase, cliquez sur Get started (Commencer)).

Firebase CLI : (version 13.15.4 ou ultérieure) pour créer un backend, exécutez la commande suivante à partir de la racine de votre répertoire de projet local, en fournissant l' ID de votre projet comme argument :

firebase apphosting:backends:create --project PROJECT_ID

Pour 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éfinissez la branche active.

Il s'agit de la branche de votre dépôt GitHub qui est déployée sur votre URL active. Il s'agit souvent de la branche dans laquelle les branches de fonctionnalités ou de développement sont fusionnées.
Acceptez ou refusez les déploiements automatiques.

Les déploiements automatiques sont activés par défaut. Une fois la création du backend terminée, 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, utilisez d'abord la console Firebase ou la CLI Firebase pour le supprimer, puis supprimez manuellement les éléments associés, en veillant à ne pas supprimer les ressources qui pourraient être utilisées par d'autres backends ou d'autres aspects de votre projet Firebase.

Firebase console : dans le menu Setting (Paramètres), sélectionnez Delete backend (Supprimer le backend).

Firebase CLI: : (version 13.15.4 ou ultérieure)

Exécutez la commande suivante pour supprimer le backend App Hosting. Cela désactive tous les domaines de votre backend et supprime le service associé Cloud Run :
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
```
(Facultatif) Dans l' Google Cloud onglet de la console Artifact Registry, supprimez l'image de votre backend dans "firebaseapphosting-images".
Dans Cloud Secret Manager, supprimez tous les secrets contenant "apphosting" dans leur nom, en veillant à ce que ces secrets ne soient pas utilisés par d'autres backends ou d'autres aspects de votre projet Firebase.