Configura y administra los backends de App Hosting

App Hosting se diseñó para que sea fácil de usar y requiera poco mantenimiento, con parámetros de configuración predeterminados optimizados para la mayoría de los casos de uso. Al mismo tiempo, App Hosting te proporciona herramientas para administrar y configurar backends según tus necesidades específicas. En esta guía, se describen esas herramientas y procesos.

Configura y actualiza variables de entorno

A veces, es posible que necesites una configuración adicional para tu proceso de compilación. App Hosting ofrece configuración del entorno para almacenar y recuperar este tipo de datos para tu proyecto a través de la consola de Firebase y, de forma alternativa, en apphosting.yaml.

Configurar variables de entorno en la consola es la forma más rápida de comenzar. Usa apphosting.yaml si necesitas almacenar parámetros secretos y acceder a ellos, establecer variables que solo estén disponibles en el momento de la compilación o la ejecución, o compartir variables de entorno en varios entornos. Con la consola y apphosting.<env>.yaml, puedes establecer valores diferentes para diferentes entornos.

Firebase console

Captura de pantalla del diálogo de Firebase console para agregar variables de entorno

apphosting.yaml

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

Actualiza variables

Puedes agregar y editar variables de entorno en la consola de Firebase en la pestaña Configuración de un backend. Navega a View Backend >> Settings >> Environment y, luego, agrega, edita o borra variables de entorno.

Para agregar y editar variables de entorno en apphosting.yaml,, crea y edita el archivo de forma manual.

Los cambios solo se aplicarán en tu próximo lanzamiento y no afectarán el actual. Puedes guardar y crear un nuevo lanzamiento, o bien guardar las variables y realizar la implementación más adelante.

Cómo establecer la disponibilidad de las variables

Las variables de entorno creadas en Firebase console están disponibles en el tiempo de compilación y el tiempo de ejecución. Esta también es la condición predeterminada para las variables definidas en apphosting.yaml, a menos que hayas reducido ese alcance con la propiedad availability. En apphosting.yaml (pero no en la consola), puedes restringir una variable de entorno para que esté disponible solo en el entorno de compilación o solo en el entorno de ejecución.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

En el caso de las apps de Next.js, también puedes usar el prefijo NEXT_PUBLIC_ de la misma manera que lo harías en tu archivo .env para que una variable sea accesible en el navegador.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Archivos .env para Next.js

En el caso de las apps de Next.js, los archivos .env que contienen variables de entorno funcionan con App Hosting.

Cuando creas o actualizas un backend, puedes transferir variables de entorno de tu archivo .env a Firebase console. Para ello, copia y pega todo el contenido del archivo .env en el primer campo "Clave" del formulario "Agregar nuevo" en Configuración de variables de entorno.

Todas las variables de entorno copiadas de esta manera deben tener un formato ordenado en el formulario sin necesidad de ingresar cada una de forma individual, siempre y cuando la entrada tenga un formato como el siguiente:

KEY1=value1
KEY2=value2
KEY3=value3

Para un control complejo o detallado de las variables de entorno con cualquier framework, recomendamos usar apphosting.yaml.

Jerarquía de variables

Firebase App Hosting aplica tus variables en un orden de prioridad según su fuente. Por ejemplo, los valores establecidos en la consola siempre anulan o tienen prioridad sobre los valores establecidos en los archivos apphosting.yaml y dotenv.

Este es el orden completo de precedencia:

  1. Firebase console → variables establecidas en la consola
  2. apphosting.<env>.yaml → variables especificadas en un archivo YAML específico del entorno, como apphosting.staging.yaml (consulta Implementa varios entornos)
  3. apphosting.yaml → variables especificadas en el archivo apphosting.yaml
  4. Sistema de Firebase → Variables establecidas por Firebase que contienen valores para firebase_config json o firebase_webapp_config, así como variables de entorno que establecen los nombres de host y los puertos para las apps de SSR (establecidas por los adaptadores de App Hosting en bundle.yaml)

Nombres reservados y limitaciones

Las claves de variables válidas deben comenzar con una letra mayúscula y solo pueden contener letras mayúsculas, números y guiones bajos. Algunas claves de variables de entorno están reservadas para uso interno. No uses ninguna de estas claves en tus archivos de configuración:

  • Cadenas vacías ("")
  • Variables que contienen "="
  • Cualquier variable que comience con X_FIREBASE_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Llaves duplicadas

Cómo crear y editar apphosting.yaml

Para la configuración avanzada, como secretos o parámetros de configuración del tiempo de ejecución, como límites de simultaneidad, CPU y memoria, deberás crear y editar el archivo apphosting.yaml en el directorio raíz de tu app. Este archivo admite referencias a secretos administrados con Cloud Secret Manager, lo que hace que sea seguro registrarlo en el control de origen.

Para crear apphosting.yaml, ejecuta el siguiente comando:

firebase init apphosting

Esto crea un archivo apphosting.yaml inicial básico con un ejemplo de configuración (comentado). Después de la edición, un archivo apphosting.yaml típico podría verse de la siguiente manera, con la configuración del servicio Cloud Run del backend, algunas variables de entorno y algunas referencias a secretos administrados por 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

En el resto de esta guía, se proporciona más información y contexto sobre estos parámetros de configuración de ejemplo.

Configura los parámetros del servicio Cloud Run

Con la configuración de apphosting.yaml, puedes configurar cómo se aprovisiona tu servicio de Cloud Run. Los parámetros de configuración disponibles para el servicio Cloud Run se proporcionan en el objeto runConfig:

  • cpu: Es la cantidad de CPU que se usan para cada instancia de procesamiento (el valor predeterminado es 0).
  • memoryMiB: Cantidad de memoria asignada a cada instancia de procesamiento en MiB (el valor predeterminado es 512)
  • maxInstances: Es la cantidad máxima de contenedores que se pueden ejecutar a la vez (el valor predeterminado es 100 y se administra por cuota).
  • minInstances: Es la cantidad de contenedores que siempre deben estar activos (el valor predeterminado es 0).
  • concurrency: Es la cantidad máxima de solicitudes que puede recibir cada instancia de procesamiento (el valor predeterminado es 80).

Ten en cuenta la importante relación entre cpu y memoryMiB: La memoria se puede establecer en cualquier valor entero entre 128 y 32768, pero aumentar el límite de memoria puede requerir aumentar los límites de la CPU:

  • Más de 4 GiB requiere al menos 2 CPU
  • Más de 8 GiB requiere al menos 4 CPUs
  • Más de 16 GiB requiere al menos 6 CPU
  • Más de 24 GiB requiere al menos 8 CPU

Del mismo modo, el valor de cpu afecta la configuración de simultaneidad. Si estableces un valor inferior a 1 CPU, debes establecer la simultaneidad en 1, y la CPU solo se asignará durante el procesamiento de solicitudes.

Cómo anular las secuencias de comandos de compilación y ejecución

App Hosting infiere el comando de compilación y de inicio de tu app según el framework detectado. Si deseas usar un comando de compilación o inicio personalizado, puedes anular los valores predeterminados de App Hosting en apphosting.yaml.

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

La anulación del comando de compilación tiene prioridad sobre cualquier otro comando de compilación, inhabilita los adaptadores de framework de tu app y deshabilita cualquier optimización específica del framework que proporcione App Hosting. Es mejor usarlo cuando los adaptadores no admiten bien las funciones de tu app. Si quieres cambiar tu comando de compilación, pero seguir usando los adaptadores que proporcionamos, configura tu secuencia de comandos de compilación en package.json, como se describe en Adaptadores del framework de App Hosting.

Usa la anulación del comando de ejecución cuando haya un comando específico que quieras usar para iniciar tu app que sea diferente del comando inferido por App Hosting.

Configura el resultado de la compilación

App Hosting optimiza las implementaciones de tu app de forma predeterminada borrando los archivos de salida sin usar, según lo indica el framework. Si deseas optimizar aún más el tamaño de implementación de tu app o ignorar las optimizaciones predeterminadas, puedes anular esta configuración en apphosting.yaml.

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

El parámetro include admite una lista de directorios y archivos relativos al directorio raíz de la app que son necesarios para implementarla. Si quieres asegurarte de que se conserven todos los archivos, establece include en [.] y se implementarán todos los archivos.

Almacena parámetros secretos y accede a ellos

La información sensible, como las claves de API, debe almacenarse como secretos. Puedes hacer referencia a secretos en apphosting.yaml para evitar registrar información sensible en el control de origen.

Los parámetros de tipo secret representan parámetros de cadena que tienen un valor almacenado en Cloud Secret Manager. En lugar de derivar el valor directamente, los parámetros secretos comprueban la existencia en Cloud Secret Manager y cargan los valores durante el lanzamiento.

  -   variable: API_KEY
      secret: myApiKeySecret

Los secretos en Cloud Secret Manager pueden tener varias versiones. De forma predeterminada, el valor de un parámetro secreto disponible para tu backend activo se fija en la versión disponible más reciente del secreto en el momento en que se compiló el backend. Si tienes requisitos para el control de versiones y la administración del ciclo de vida de los parámetros, puedes fijar versiones específicas con Cloud Secret Manager. Por ejemplo, para fijar la versión 5, haz lo siguiente:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Puedes crear secretos con el comando de la CLI firebase apphosting:secrets:set, y se te pedirá que agregues los permisos necesarios. Este flujo te brinda la opción de agregar automáticamente la referencia del secreto a apphosting.yaml.

Para usar el conjunto completo de funciones de Cloud Secret Manager, puedes usar la consola de Cloud Secret Manager. Si lo haces, deberás otorgar permisos a tu backend de App Hosting con el comando de la CLI firebase apphosting:secrets:grantaccess.

Configura el acceso a la VPC

Tu backend de App Hosting puede conectarse a una red de nube privada virtual (VPC). Para obtener más información y un ejemplo, consulta Conecta Firebase App Hosting a una red de VPC.

Usa la asignación vpcAccess en tu archivo apphosting.yaml para configurar el acceso. Usa un nombre o un ID de conector o red completamente calificado. El uso de IDs permite la portabilidad entre entornos de producción y de pruebas con diferentes conectores o redes.

Configuración de salida de VPC directa (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

Configuración del conector sin servidores (apphosting.yaml):

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

Administra backends

En la CLI de Firebase y la consola de Firebase, se proporcionan comandos para la administración básica de los backends de App Hosting. En esta sección, se describen algunas de las tareas de administración más comunes, como la creación y eliminación de backends.

Crear un backend

Un backend de App Hosting es la colección de recursos administrados que App Hosting crea para compilar y ejecutar tu app web.

Firebase console: En el menú Compilar, selecciona App Hosting y, luego, Crear backend (si es el primer backend de tu proyecto de Firebase, selecciona Comenzar).

CLI: (versión 13.15.4 o posterior) Para crear un backend, ejecuta el siguiente comando desde la raíz del directorio del proyecto local y proporciona tu projectID como argumento:

firebase apphosting:backends:create --project PROJECT_ID

Tanto para la consola como para la CLI, sigue las indicaciones para elegir una región, configurar una conexión de GitHub y establecer estos parámetros de configuración de implementación básicos:

  • Establece el directorio raíz de tu app (/ de forma predeterminada).

    Por lo general, es donde se encuentra el archivo package.json.

  • Establece la rama activa

    Esta es la rama de tu repositorio de GitHub que se implementa en tu URL publicada. A menudo, es la rama en la que se fusionan las ramas de desarrollo o de funciones.

  • Aceptar o rechazar los lanzamientos automáticos

    Los lanzamientos automáticos están habilitados de forma predeterminada. Cuando se complete la creación del backend, puedes elegir que tu app se implemente en App Hosting de inmediato.

  • Asigna un nombre a tu backend.

Borrar un backend

Para quitar por completo un backend, primero usa la CLI de Firebase o la consola de Firebase para borrarlo y, luego, quita de forma manual los recursos relacionados. Ten especial cuidado de no borrar ningún recurso que puedan usar otros backends o aspectos de tu proyecto de Firebase.

Firebase console: En el menú Configuración, selecciona Borrar backend.

CLI: (versión 13.15.4 o posterior)

  1. Ejecuta el siguiente comando para borrar el backend de App Hosting. Esto inhabilita todos los dominios de tu backend y borra el servicio de Cloud Run asociado:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (Opcional) En la pestaña de la consola de Google Cloud para Artifact Registry, borra la imagen de tu backend en "firebaseapphosting-images".

  3. En Cloud Secret Manager, borra los secretos que contengan "apphosting" en el nombre, asegurándote de que otros backends o aspectos de tu proyecto de Firebase no usen estos secretos.