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

App Hosting te permite usar variables de entorno para valores de configuración no sensibles y secrets para parámetros sensibles, como claves de API, credenciales de bases de datos y tokens de servicio.

  • Variables de entorno estándar: Se usan para configuraciones de texto sin formato no sensibles (como URLs de APIs públicas, marcas de funciones o destinos de compilación). Los valores son visibles para todos los miembros del proyecto.
  • Secretos: Se usan para parámetros sensibles (como secretos de cliente de OAuth, tokens de API o contraseñas de bases de datos). Los Secrets están respaldados por Cloud Secret Manager. Los valores de los secretos están protegidos y nunca se muestran en texto sin formato en la consola de Firebase. En su lugar, la consola proporciona vínculos directos para ver y administrar los valores de los secretos directamente en Cloud Secret Manager.

Puedes definir y administrar los parámetros de entorno con dos enfoques complementarios:

  • Consola de Firebase: Agrega, edita y adjunta secretos o variables de forma dinámica con rapidez durante la creación inicial del backend o después de la implementación en la configuración del backend.
  • Primero el código (apphosting.yaml): Declara variables de entorno y referencias de secretos en el archivo de configuración de tu repositorio para las implementaciones con control de versiones, o usa apphosting.<env>.yaml para establecer valores diferentes para entornos distintos.

Consola de Firebase

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

apphosting.yaml

env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
  - variable: API_KEY
    secret: myApiKeySecret

Administra variables y secretos en la consola de Firebase

Puedes configurar variables de entorno y secretos en la consola de Firebase cuando creas un backend o en cualquier momento desde la configuración del backend. Los cambios guardados sin implementar se aplicarán en el próximo lanzamiento y no afectarán al actual.

Configura variables y secretos durante la creación del backend

Cuando creas un backend de App Hosting nuevo en la consola de Firebase, puedes configurar variables de entorno y secretos estándar durante el paso Configura tu backend del asistente de configuración:

  1. En la consola de Firebase, navega a Hosting y sin servidores > App Hosting y haz clic en Crear backend.
  2. Completa los pasos iniciales del asistente para seleccionar tu región principal y el repositorio de código.
  3. En la sección Configura tu backend, busca las tarjetas contraíbles de Variables de entorno y Secretos, en las que puedes agregar variables estándar y adjuntar secretos.
  4. Completa el asistente de creación de backend y haz clic en Finalizar e implementar.

Administra variables y secretos en la configuración del backend

Puedes ver, agregar, editar o borrar variables de entorno y secretos para backends activos desde el panel de configuración del backend:

  1. En la consola de Firebase, selecciona tu backend de App Hosting y abre Configuración > Entorno.
  2. Revisa los parámetros de configuración existentes en la tabla Variables de entorno:
    • Variables estándar: Los valores se muestran como texto sin formato en bloques de código que se pueden copiar.
    • Secrets: Se muestra como un vínculo en el que se puede hacer clic y que muestra el nombre del Secret (que abre Cloud Secret Manager en la consola de Google Cloud) junto con su versión de destino (como latest o un número de versión específico, como 2).
  3. Para agregar una variable o un Secret, sigue estos pasos:
    1. Haz clic en Agregar nueva.
    2. En el Paso 1: Selecciona el tipo, elige Variable de entorno estándar (para datos no sensibles visibles para todos los miembros del proyecto) o Secreto (para claves de API y credenciales sensibles con acceso restringido) y, luego, haz clic en Siguiente.
    3. En el Paso 2: Establece la configuración, ingresa el nombre de la Clave y el Valor de texto sin formato (para variables estándar) o selecciona el ID del Secreto y la Versión (para secretos).
    4. Guarda los cambios con una de las siguientes opciones:
      • Guardar e implementar: Actualiza de inmediato la configuración del backend y activa una nueva compilación y un lanzamiento.
      • Solo guardar (desde la flecha desplegable junto a Guardar e implementar): Guarda los cambios de configuración sin activar un lanzamiento inmediato. La configuración actualizada se aplicará en tu próxima implementación.
  4. Para editar o borrar una entrada existente, haz clic en el menú Más acciones (...) al final de la fila:
    • Selecciona Editar para modificar la clave, el valor, la asignación de secretos o la versión y, luego, haz clic en Guardar e implementar o Solo guardar.
    • Selecciona Borrar y confirma la eliminación en el cuadro de diálogo.

Transfiere variables de archivos dotenv

Para las apps de Next.js, los archivos dotenv que contienen variables de entorno funcionan con App Hosting.

Cuando creas o actualizas un backend, puedes transferir variables de entorno desde tu archivo dotenv a la consola de Firebase copiando y pegando todo el contenido del archivo dotenv en el primer campo Clave del formulario Agregar nuevo en Configuración > Entorno.

Todas las variables de entorno copiadas de esta manera se formatean automáticamente en el formulario sin necesidad de ingresar cada una de forma individual, siempre que la entrada use el formato estándar de KEY=value:

KEY1=value1
KEY2=value2
KEY3=value3

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

Administra variables y secretos en apphosting.yaml

Para los flujos de trabajo que priorizan el código, declara variables de entorno estándar y referencias de secretos en la clave env: del archivo de configuración apphosting.yaml del repositorio de tu proyecto (consulta Crea y edita apphosting.yaml).

env:
  # Standard environment variables
  - variable: PUBLIC_API_URL
    value: https://api.example.com
    availability:
      - BUILD
      - RUNTIME
  - variable: FEATURE_FLAG_NEW_UI
    value: "true"

  # Secret references backed by Cloud Secret Manager
  - variable: DATABASE_URL
    secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
  - variable: GEMINI_API_KEY
    secret: myGeminiApiKeySecret@1

Cada entrada en env: admite los siguientes campos:

  • variable: Es el nombre de la variable de entorno expuesta al proceso de tu aplicación.
  • value: Es el valor de cadena de texto sin formato (para variables de entorno estándar).
  • secret: Es la referencia del Secret Manager de Cloud (para secretos). Puedes usar el nombre corto del Secret (como myGeminiApiKeySecret o myGeminiApiKeySecret@1 fijado) o la ruta de acceso completa del recurso (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION). Consulta Almacena parámetros de Secrets y accede a ellos para obtener más detalles.
  • availability: Controla si se puede acceder a la variable o al secreto durante la fase BUILD, en RUNTIME o en ambas.

Establece la disponibilidad de las variables

Las variables de entorno y los secretos configurados en la consola de Firebase están disponibles tanto en el momento de la compilación como en el de la ejecución. Este también es el comportamiento predeterminado para las entradas definidas en apphosting.yaml, a menos que reduzcas el alcance con la propiedad availability. En apphosting.yaml (pero no en la consola), puedes restringir una variable o un secreto solo al entorno de compilación (BUILD) o solo al entorno de ejecución (RUNTIME).

Accede a variables y secretos en el código de la aplicación

Ya sea que se configuren en la consola de Firebase o en apphosting.yaml, las variables de entorno y los secretos se exponen al entorno de ejecución de tu aplicación como variables de entorno estándar (por ejemplo, process.env en Node.js).

// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;

// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;

export async function fetchData() {
  const response = await fetch(`${apiUrl}/data`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  return response.json();
}
  • Acceso del servidor: Se puede acceder de forma segura a todas las variables de entorno y los secretos en los contextos de ejecución del servidor (como los componentes del servidor de Next.js, las rutas de API o los controladores de backend de Node.js).
  • Exposición del cliente: Para exponer variables de entorno estándar al navegador en frameworks como Next.js, asegúrate de que la clave de la variable siga las convenciones del framework (por ejemplo, con el prefijo NEXT_PUBLIC_).

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

Jerarquía de variables

Firebase App Hosting aplica tus variables de entorno y secretos en un orden de prioridad según su fuente. Los parámetros de configuración establecidos en la consola de Firebase siempre anulan los parámetros declarados en los archivos apphosting.yaml y dotenv. Si existe una variable de entorno o una clave de secreto con el mismo nombre en apphosting.yaml y en la consola de Firebase, el valor de la consola tiene prioridad durante la compilación y la ejecución del entorno de ejecución.

Este es el orden de prioridad completo:

  1. Consola de Firebase: Variables y secretos configurados en la consola
  2. apphosting.<env>.yaml: Son variables y secretos especificados en un archivo YAML específico del entorno, como apphosting.staging.yaml (consulta Implementa varios entornos).
  3. apphosting.yaml: Son las variables y los secretos especificados en el archivo apphosting.yaml.
  4. Sistema de Firebase: Son variables que establece Firebase y que contienen valores para FIREBASE_CONFIG 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).

Variables de entorno propagadas automáticamente

App Hosting propaga automáticamente algunas variables de entorno. Entre ellas, se incluyen las que propaga Google Cloud y las variables de entorno específicas de Firebase cuando se configura appId en el backend durante la configuración:

  • FIREBASE_CONFIG: (disponible en los entornos de compilación y de ejecución) Proporciona la siguiente información de configuración del proyecto de Firebase:

    {
      "databaseURL": "https://DATABASE_NAME.firebaseio.com",
      "storageBucket": "PROJECT_ID.firebasestorage.app",
      "projectId": "PROJECT_ID"
    }
    

    Esta configuración se aplica automáticamente cuando inicializas el SDK de Firebase Admin sin argumentos.

  • FIREBASE_WEBAPP_CONFIG: (disponible solo en el entorno de compilación) Proporciona la siguiente información de configuración del proyecto de Firebase:

    {
      "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"
    }</span>
    

    El SDK de JS de Firebase verifica automáticamente esta variable de entorno FIREBASE_WEBAPP_CONFIG en una secuencia de comandos posterior a la instalación durante la compilación, lo que también te permite inicializar el SDK de cliente sin argumentos.

Consulta Inicializa automáticamente el SDK de Firebase Admin y los SDKs web para obtener más detalles sobre cómo usar estas variables de entorno para inicializar los SDKs.

Ten en cuenta que los valores de tu configuración real de Firebase corresponderán a los recursos específicos que aprovisionaste en tu proyecto.

Jerarquía de variables

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

Este es el orden de prioridad completo:

  1. Consola de Firebase: Variables configuradas en la consola
  2. apphosting.<env>.yaml: Son variables especificadas en un archivo YAML específico del entorno, como apphosting.staging.yaml (consulta Implementa varios entornos).
  3. apphosting.yaml: Son las variables especificadas en el archivo apphosting.yaml.
  4. Sistema de Firebase: Son variables que establece Firebase y 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 variables de entorno definidas en el contrato de entorno de ejecución del contenedor de Cloud Run están reservadas y no se pueden configurar.

Las variables de entorno que proporciona el entorno, además de las que se configuran automáticamente, podrían cambiar en futuras versiones del entorno de ejecución. Como práctica recomendada, te sugerimos que no dependas de ninguna variable de entorno que no hayas configurado de forma explícita ni la modifiques, y que consideres agregar un prefijo a cualquier variable de entorno con una clave única para evitar conflictos.

Algunas claves de variables de entorno están reservadas para uso interno. No uses ninguna de las siguientes claves en los archivos de configuración:

  • Cadenas vacías ("")
  • Claves que contienen "="
  • Claves que comienzan con X_FIREBASE_, X_GOOGLE_ o CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Claves duplicadas

Crea y edita apphosting.yaml

Para realizar una configuración avanzada, como secretos o parámetros de configuración del entorno de ejecución, como la simultaneidad, la CPU y los límites de 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 verificarlo en el control de código fuente.

Para crear apphosting.yaml, ejecuta el siguiente comando:

firebase init apphosting

Esto crea un archivo apphosting.yaml básico de inicio con una configuración de ejemplo (comentada). Después de editarlo, un archivo apphosting.yaml típico podría verse como el siguiente, 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 para estos parámetros de configuración de ejemplo.

Establece la configuración del servicio de Cloud Run

Con la configuración de apphosting.yaml, puedes configurar cómo se aprovisiona tu servicio de Cloud Run. La configuración disponible para el servicio Cloud Run se proporciona en el objeto runConfig:

Ten en cuenta que cpu, memoryMiB y concurrency tienen límites interdependientes (por ejemplo, las configuraciones de memoria más altas requieren límites de CPU mínimos más altos, y las CPU fraccionarias requieren una simultaneidad de 1). Consulta la documentación de Cloud Run sobre los límites de CPU y los límites de memoria para conocer los rangos válidos y las combinaciones requeridas.

Anula 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 las optimizaciones específicas del framework que proporciona App Hosting. Se recomienda usarlo cuando los adaptadores no admiten bien las funciones de tu app. Si quieres cambiar el comando de compilación, pero seguir usando los adaptadores proporcionados, configura la 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, como lo indica el framework. Si quieres optimizar aún más el tamaño de implementación de tu app o ignorar las optimizaciones predeterminadas, puedes anular esto en apphosting.yaml.

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

El parámetro include toma una lista de directorios y archivos relacionados con el 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 de Secrets y accede a ellos

La información sensible, como las claves de API, se debe almacenar como Secrets. Puedes adjuntar Secrets a tu backend en la consola de Firebase o hacer referencia a ellos en apphosting.yaml para evitar que se verifique información sensible en el control de código fuente.

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

env:
  - variable: API_KEY
    secret: myApiKeySecret

Los secretos en Secret Manager de Cloud pueden tener varias versiones. De forma predeterminada, el valor de un parámetro de secreto disponible para tu backend activo se fija en la versión más reciente disponible 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 en la consola de Firebase o en apphosting.yaml. Por ejemplo, para fijar la versión 5 en apphosting.yaml, haz lo siguiente:

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Puedes crear Secrets con el comando firebase apphosting:secrets:set de la CLI de Firebase 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.

Otorga acceso a Cloud Secret Manager

Para que App Hosting recupere valores de secretos durante los lanzamientos de compilación y del entorno de ejecución, la cuenta de servicio de backend de App Hosting debe tener permiso para acceder a Cloud Secret Manager.

Si creas Secrets con la consola de Secret Manager de Cloud o la CLI de gcloud en lugar de firebase apphosting:secrets:set, otorga acceso a tu backend con la CLI de Firebase:

firebase apphosting:secrets:grantaccess SECRET_NAME

Como alternativa, puedes otorgar el rol de descriptor de acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) al agente de servicio de App Hosting (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) o a la cuenta de servicio del entorno de ejecución de tu backend con la CLI de gcloud:

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

Acceso a la consola y permisos basados en roles

La consola de Firebase restringe de forma dinámica las funciones de administración de entornos y Secret Manager según los permisos de IAM del usuario:

  • Rol de visualizador: Los usuarios con permisos de proyecto de solo lectura pueden ver los parámetros de configuración existentes, pero no pueden realizar cambios.
    • Durante la creación del backend, el botón Crear backend está inhabilitado.
    • En Configuración > Entorno del backend, el botón Agregar nuevo está inhabilitado y los menús de fila Más acciones (...) están ocultos.
  • Faltan permisos de Secret Manager: Los usuarios que no tienen permisos de IAM para interactuar con Cloud Secret Manager ven un mensaje de advertencia en la consola (Pídele permiso al propietario del proyecto para agregar secretos):
    • Durante la creación del backend, la tarjeta Secretos está inhabilitada.
    • En la Configuración del backend > Entorno, la opción Secreto se inhabilita cuando haces clic en Agregar nuevo, y algunas de las opciones del menú de fila Más acciones (...) se ocultan en las entradas de secretos existentes.

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 de red o conector completamente calificado, o un ID. El uso de IDs permite la portabilidad entre los entornos de etapa de pruebas y producción 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

Los comandos para la administración básica de los backends de App Hosting se proporcionan en la consola de Firebase y en la CLI de Firebase. En esta sección, se describen algunas de las tareas de administración más comunes, como la creación y la 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.

Consola de Firebase: Navega a Hosting y Serverless > App Hosting y, luego, haz clic en Crear backend (si este es el primer backend de tu proyecto de Firebase, haz clic en Comenzar).

CLI de Firebase: (v13.15.4 o posterior) Para crear un backend, ejecuta el siguiente comando desde la raíz del directorio de tu proyecto local y proporciona el ID del proyecto 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 (el valor predeterminado es /).

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

  • Configura 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 combinan las ramas de funciones o de desarrollo.

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

  • Selecciona tu entorno de ejecución. De forma predeterminada, se preselecciona la versión más reciente recomendada de Node.js.

    • Configura las actualizaciones automáticas de imágenes base (ABIU). La ABIU está habilitada de forma predeterminada y aplica automáticamente parches de seguridad a tu entorno subyacente. Puedes inhabilitar la ABIU seleccionando "No especificado" para tu entorno de ejecución.

Borrar un backend

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

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

Firebase CLI: (v13.15.4 o posterior)

  1. Ejecuta el siguiente comando para borrar el backend 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 tengan "apphosting" en el nombre, teniendo especial cuidado de asegurarte de que otros backends o aspectos de tu proyecto de Firebase no los usen.