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 de cadena único para su instancia. Esto le permite diferenciar cuando tiene múltiples instancias en su proyecto. El nombre de la instancia no tiene relación con el entorno en el que se ejecutará, esto se controla mediante el parámetro region.

Tiempo de ejecución

runtime es el lenguaje con el que ha construido su 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
  • US - aws.use1
  • APAC (Singapur) - aws.apse1
  • APAC (Sydney) - aws.apse2

ID de aplicación

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 comandos 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 se convertirá:

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. A continuación se muestra un script de compilación de ejemplo para un proyecto JavaScript y NPM:

#!/bin/bash npm ci --production

Capacidades

capabilities a las capacidades con el mismo nombre en Vonage Applications, las opciones disponibles son:

  • voice
  • messages-v1
  • rtc

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

Medio ambiente

environment te permite pasar opcionalmente variables de entorno a tu aplicación. Vonage Cloud Runtime inyectará las variables de entorno por ti cuando ejecutes vcr debug o cuando tu aplicación se implemente en Vonage Cloud Runtime. Así, por ejemplo, VONAGE_NUMBER de arriba 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 implantación.

Secretos

Puede exponer los secretos que ha creado con la CLI a la instancia 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 disponible como process.env.MY_API_KEY.

Utilización de la environment objeto - el secreto se asigna a un nombre de variable específico:

instance:
    environment:
        - name: API_KEY
          secret: MY_API_KEY

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

Para obtener más información sobre la creación y gestión de secretos, consulte la página Guía de 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 endpoint 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 implantació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 (por ejemplo /users/*/profile)
  • ** - coincide con varios segmentos de ruta (por ejemplo /api/**)

Nota: Los webhook callbacks de Vonage deben estar configurados como public para que la plataforma de Vonage pueda llegar a ellos.

Escala

scaling le permite controlar el número mínimo y máximo de réplicas que la plataforma ejecutará para su 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, evitando arranques en frío. El 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 aplicación

Esto te permite especificar un ID de aplicación de Vonage separado 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 instancia. Esto le da la flexibilidad de tener un flujo de trabajo de depuración separado, por ejemplo, incluyendo un observador de archivos para reiniciar la aplicación cuando se realizan cambios:

nodemon --inspect index.js

Se convierte:

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

Conservar datos

preserve-data permite conservar los datos almacenados con Estado de la instancia entre ejecuciones del depurador. Es falso por defecto.