Archivo de configuración

El archivo de configuración de Vonage Cloud Runtime (vcr.yml), proporciona información a la plataforma sobre cómo depurar y desplegar tu aplicación. Es un archivo YAML que tiene objetos que te permiten configurar dónde se implementan tus instancias, a qué aplicación de Vonage estás conectado, etc. Aquí tienes un archivo de configuración de ejemplo:

project:
    name: app
instance:
    name: dev
    runtime: nodejs22
    region: aws.use1
    application-id: 773c2b45-c20a-4d6b-8afe-24ce29ba6f92
    entrypoint: [node, index.js]
    build-script: "./build.sh"
    capabilities:
        - voice
        - messages-v1
    environment:
        - name: VONAGE_NUMBER
          value: "44700000000"
        - name: INTEGRATION_API_KEY
          secret: MY_SECRET_API_KEY
    secrets:
        - MY_SECRET_API_KEY
debug:
    name: debug
    application-id: 884c2b45-c20a-4d6b-8afe-24ce29ba6f93
    environment:
        - name: DEBUG_VONAGE_NUMBER
          value: "4471111111"
    entrypoint: [nodemon, --inspect, index.js]
    preserve-data: false

Proyecto

Un proyecto es un espacio de nombres para agrupar instancias.

Nombre

name es un identificador de cadena único para su proyecto. Puedes tener múltiples instancias dentro de un proyecto, en una relación de un proyecto a muchas instancias. Por ejemplo, una instancia para ejecutar el código de producción, una instancia para ejecutar el código de desarrollo y una instancia para la puesta en marcha.

Para tener varias instancias, cree un nuevo archivo de configuración, por ejemplo prod.ymly asegúrese de que el nombre del proyecto es el mismo. Para desplegar diferentes archivos de configuración puede pasar sus rutas de archivo a la función desplegar comando CLI.

Instancia

Una instancia es tu código ejecutándose en la plataforma Vonage Cloud Runtime. Para ejecutar tu código, la plataforma necesita información sobre dónde y cómo ejecutarlo.

Nombre

name es un identificador único en forma de cadena para tu instancia. Esto te permite distinguirlas cuando tienes varias instancias en tu proyecto. El nombre de la instancia no influye en el entorno en el que se ejecutará; esto lo controla el region.

Duración

runtime es el lenguaje con el que has escrito tu código fuente; las opciones disponibles son:

  • nodejs18
  • nodejs22
  • nodejs24
  • python3
  • python3ai
  • python314
  • go119
  • go126
  • java21
  • ruby3.3
  • php8

Región

region es donde se ejecutará la instancia. Las regiones disponibles actualmente son:

  • UE - aws.euw1
  • EE. UU. - aws.use1
  • APAC (Singapur) - aws.apse1
  • APAC (Sídney) - aws.apse2

ID de la solicitud

application-id es el ID de la aplicación de Vonage a la que se conectará la instancia, esto permitirá que Vonage Cloud Runtime configure las retrollamadas de la aplicación por ti y acceda a los números vinculados.

Punto de entrada

entrypoint Se utiliza para dar instrucciones a Vonage Cloud Runtime sobre cómo ejecutar tu aplicación. entrypoint toma un array de cadenas que luego se ejecuta para iniciar tu aplicación. Por ejemplo, para ejecutar mi aplicación yo usaría:

node index.js

Esto quedará así:

entrypoint: [node, index.js]

El primer elemento es el comando que se va a ejecutar, seguido de cualquier indicador o parámetro.

Guión de construcción

build-script le permite especificar un script para que VCR lo ejecute mientras construye su aplicación. El script de compilación se ejecuta antes de que su entrypoint se ejecuta el comando. A continuación se muestra un ejemplo de script de compilación para un proyecto de JavaScript y NPM:

#!/bin/bash npm ci --production

Capacidades

capabilities Para asignar las funciones con el mismo nombre en Vonage Applications, las opciones disponibles son:

  • voice
  • messages-v1
  • rtc

Esto permite que Vonage Cloud Runtime gestione los webhooks de estas funciones. Para recibir los webhooks, puedes utilizar la función correspondiente del SDK de Vonage Cloud Runtime. Consulta la documentación sobre el Voz, Mensajes y Conversación (RTC) para más información.

Medio ambiente

environment te permite, si lo deseas, pasar variables de entorno a tu aplicación. Vonage Cloud Runtime se encargará de insertar las variables de entorno por ti cuando ejecutes vcr debug o cuando tu aplicación se implemente en Vonage Cloud Runtime. Por ejemplo: VONAGE_NUMBER Lo anterior estaría disponible como:

process.env.VONAGE_NUMBER;

Vonage Cloud Runtime también inyecta algunas variables de entorno por defecto para ti. Esto incluye cosas como el ID de la aplicación de Vonage y la clave privada. Para obtener una lista completa, consulta la guía de implementación.

Secretos

Puedes hacer que la instancia tenga acceso a los secretos que ya has creado mediante la CLI de dos maneras.

Utilización de la secrets lista - el secreto se expone directamente como una variable de entorno utilizando su propio nombre:

instance:
    secrets:
        - MY_API_KEY
        - DATABASE_PASSWORD

MY_API_KEY estaría entonces disponible como process.env.MY_API_KEY.

Utilización de la environment objeto — el secreto se asigna a un nombre de variable concreto:

instance:
    environment:
        - name: API_KEY
          secret: MY_API_KEY

API_KEY estaría entonces disponible como process.env.API_KEY.

Para obtener más información sobre cómo crear y gestionar secretos, consulta la Guía sobre los secretos de Vonage Cloud Runtime.

Ruta del chequeo médico

health-check-path le permite personalizar la ruta utilizada por la plataforma para comprobar el estado de su instancia. La ruta por defecto es /_/health. El punto final debe devolver un estado HTTP 200.

instance:
    health-check-path: /_/health

Para más información sobre el requisito de chequeo médico, consulte el guía de implementación.

Seguridad

security le permite controlar el acceso a los puntos finales de su aplicación. Por defecto, todos los puntos finales son de acceso público. Puede establecer un nivel de acceso predeterminado y añadir anulaciones específicas de la ruta.

instance:
    security:
        access: private
        override:
            - path: "/webhooks/*"
              access: public
            - path: "/api/**"
              access: authenticated
              auth-method: vonage_basic

Los niveles de acceso disponibles son:

  • public - no se requiere autenticación
  • private - no accesible desde el exterior del andén
  • authenticated - requiere autenticación mediante auth-method

Sólo se admite auth-method es vonage_basic.

Los patrones de ruta admiten dos comodines:

  • * — coincide con un único segmento de ruta (p. ej., /users/*/profile)
  • ** — coincide con varios segmentos de ruta (p. ej., /api/**)

Nota: Las respuestas de los webhooks de Vonage deben configurarse en public para que la plataforma de Vonage pueda llegar a ellos.

Escala

scaling te permite controlar el número mínimo y máximo de réplicas que la plataforma ejecutará para tu instancia.

instance:
    scaling:
        min-scale: 1
        max-scale: 5

Configuración min-scale a 1 o superior mantiene al menos una réplica en funcionamiento en todo momento, lo que evita los arranques en frío. El valor mínimo por defecto es 0 (escala a cero en reposo).

Dominios

domains le permite configurar uno o más nombres de dominio personalizados para su instancia. Antes de añadir un dominio, cree un registro DNS CNAME que apunte a custom.[region].runtime.vonage.cloud.

instance:
    domains:
        - api.myapp.example.com

Depurar

El objeto de depuración brinda información a la CLI de Vonage Cloud Runtime sobre cómo ejecutar tu aplicación en modo de depuración. Para obtener más información sobre depuración, consulta la sección Guía de depuración de Vonage Cloud Runtime.

Nombre

name le permite dar un nombre a su depurador para que la URL de depuración generada sea estática, en lugar de aleatoria cuando se inicia el depurador.

ID de la solicitud

Esto te permite especificar un ID de aplicación de Vonage distinto al de tu instancia.

Medio ambiente

environment en la sección de depuración funciona igual que entorno de instanciapero sólo se aplica cuando se ejecuta vcr debug. Esto le permite utilizar diferentes variables de entorno localmente sin afectar a su instancia desplegada.

debug:
    environment:
        - name: LOG_LEVEL
          value: "debug"
        - name: API_KEY
          secret: DEV_API_KEY

Punto de entrada

entrypoint para depuración funciona igual que el punto de entrada de la instancia. Esto te ofrece la flexibilidad de disponer de un flujo de trabajo de depuración independiente que, por ejemplo, incluya un observador de archivos para reiniciar la aplicación cuando se realicen cambios:

nodemon --inspect index.js

Queda así:

entrypoint: [nodemon, --inspect, index.js]

Conservar los datos

preserve-data te permite conservar los datos almacenados con Estado de la instancia entre ejecuciones del depurador. Por defecto, está desactivado.