Guía del usuario

Puedes ejecutar simulaciones con la demostración web proporcionada o llamando directamente a la API de REST.

Entrada y salida

Los archivos de entrada y salida usan el bucket de Cloud Storage de la configuración de Terraform.

El directorio de entrada debe contener archivos metrics_config.zip y publisher_config.zip. Puedes definir la ruta de acceso según sea necesario.

El bucket para los resultados contiene un directorio simulations, que almacena cada simulación por su ID. Cada directorio de simulación contiene una carpeta de entrada con los archivos de entrada copiados y una carpeta de salida. La carpeta de salida contiene el informe de errores, el archivo de logcat y los archivos del simulador generados.

Cómo usar la demostración web

La plataforma incluye una aplicación web basada en Flutter para fines de demostración que te permite ver, crear y administrar simulaciones. Te recomendamos que compiles tu propia interfaz de usuario adaptada a tus necesidades.

La app de demostración se implementa en App Engine y requiere que los usuarios accedan con una Cuenta de Google. Esto se protege con un ID de cliente de OAuth 2.0 configurado en tu proyecto de Google Cloud. La cuenta con la que se accedió debe tener permisos de IAM para invocar las funciones de Cloud Functions implementadas. Consulta Administra el acceso a Cloud Functions para obtener instrucciones sobre cómo otorgar los permisos necesarios a las cuentas de usuario, como el rol Cloud Functions Invoker (roles/cloudfunctions.invoker).

Flujo de trabajo del usuario

  1. Acceder: Accedes con tu Cuenta de Google, autenticada con el proceso de OAuth 2.0.
  2. Ver simulaciones: La página principal enumera todas las simulaciones pasadas y actuales consultando la base de datos de Firestore, que contiene toda la información de ejecución.
  3. Crear una simulación: Navegas a un formulario para programar una nueva simulación haciendo clic en el botón de acción + en la esquina inferior derecha. Proporcionas varios parámetros, como la ruta de entrada, el ID de compilación y el tipo de instancia. Para obtener más información, consulta Crea una simulación.
  4. Estado de la supervisión: La lista de simulaciones se actualiza para mostrar el estado de la nueva simulación (PENDING, RUNNING, COMPLETED, etc.).
  5. Ver resultados: Después de que se complete una simulación, puedes ver los informes y artefactos generados. Los archivos de entrada, los informes de salida, los registros, Logcat y los informes de errores se almacenan en Cloud Storage.
  6. Borra una simulación: Puedes cancelar una simulación programada o en ejecución.

Uso de la API

Para la automatización y la integración con otros sistemas, puedes usar la API de REST.

El marcador de posición CLOUD_FUNCTION_URL que se usa en la sección Autenticación y en las definiciones de extremos hace referencia a la URL base de la función de Cloud Functions que se invoca. Puedes encontrar las URLs de las funciones en la consola de Google Cloud en la página Cloud Functions. La URL de cada función se muestra en la pestaña Activador de su página Detalles de la función. Como alternativa, puedes encontrar estas URLs en los resultados de Terraform que se imprimen después de ejecutar un comando apply.

Autenticación

Todas las solicitudes a la API deben autenticarse con un token de identidad que pruebe la identidad del llamador. La identidad (usuario o cuenta de servicio) debe tener permisos de invocador de Cloud Functions en la función de destino.

  • 1. Invocación del usuario (local y CLI) Cuando invocas la API desde una máquina local o un entorno que no es de Google Cloud, debes usar un token de identidad emitido por Google que se obtuvo para una cuenta de usuario.

    TOKEN=$(gcloud auth print-identity-token)

  • 2. Invocación de la cuenta de servicio (dentro de Google Cloud) Cuando invoques la API desde un recurso de Google Cloud (p.ej., una VM de Compute Engine, otra Cloud Function o un clúster de Kubernetes), debes usar la identidad de la cuenta de servicio adjunta al recurso. El token se debe recuperar del servidor de metadatos del recurso.

    TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")

Incluye el token recuperado en el encabezado Authorization de tus solicitudes como un token de Bearer.

Extremos

Los extremos orientados al usuario de la pila de Cloud Telemetry Simulation te permiten crear y borrar simulaciones, o bien leer información de simulación de la base de datos.

Crea una simulación

Este extremo crea una nueva solicitud de simulación y la programa para su ejecución.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

  • Cuerpo de la solicitud:

    {
  "build_id": "latest",
  "file_path": "inputs/my-test-case/",
  "instance_type": "n1-standard-8",
  "owner": "user@example.com",
  "max_simulation_time": 300,
  "max_report_count": 5
}
    • build_id (cadena): Es la etiqueta de la imagen de Docker del agente que se usará (p.ej., "latest"). Importante: Debe coincidir con una etiqueta definida en el mapa de imágenes permitido de la infraestructura (p.ej., "latest", "stable"). El sistema rechaza las etiquetas desconocidas si se define un mapa SHA256 en Terraform.
    • file_path (cadena): Es la ruta de acceso dentro del bucket de GCS a la carpeta que contiene metrics_config.zip y publisher_config.zip.
    • instance_type (cadena): Es el tipo de máquina de Compute Engine. Este tipo debe admitir la virtualización anidada, como las series n1, n2 o t2d. Para obtener más información, consulta la descripción general de la virtualización anidada.
    • owner (cadena): Es el correo electrónico del usuario que inicia la simulación.
    • max_simulation_time (número entero): Es el tiempo máximo en segundos que se ejecuta la simulación.
    • max_report_count (número entero): Es la cantidad de informes de telemetría después de los cuales finaliza la simulación.

  • Respuesta de éxito (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Cómo borrar una simulación

Este extremo cancela una simulación pendiente o en ejecución, y borra sus recursos asociados.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Encabezados:
    • Content-Type: application/json

  • Cuerpo de la solicitud:

    { "id": "sim-a1b2c3d4e5f6" }

  • Respuesta correcta (200 OK): Un objeto JSON vacío {}.

Cómo leer los datos de simulación

Para leer los datos de simulación, puedes interactuar con la función simulation-reader. Estos extremos usan el método GET para recuperar el historial, el estado y la configuración del sistema.

1. Enumera simulaciones

Recupera una lista paginada de simulaciones con compatibilidad para filtrar y ordenar.

  • Endpoint: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Parámetros de búsqueda (todos opcionales):

    • status (cadena): Filtra por estado de simulación (running, Simulation request received, cancelled o completed).
    • owner (cadena): Filtra por el correo electrónico del propietario.
    • sort_by (cadena): Campo por el que se ordenará (received_at, status_updated_at, started_at). El valor predeterminado es received_at.
    • sort_order (cadena): Dirección de ordenamiento, asc o desc. El valor predeterminado es desc.
    • page_size (número entero): Es la cantidad de resultados por página. El valor predeterminado es 20.
    • page_token (cadena): Es un token para recuperar la siguiente página de resultados.

  • Ejemplo de solicitud:

    curl -H "Authorization: Bearer $TOKEN"
"https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"

  • Respuesta de éxito (200 OK):

    • Devuelve un objeto JSON que contiene un array de simulaciones y un next_page_token opcional.
    {
  "simulations": [
    {
      "id": "1234-abcd",
      "owner": "some@email.com",
      "status": "completed",
      "status_updated_at": "2025-12-05T14:50:00.952Z",
      "received_at": "2025-12-05T14:46:43.106Z",
      "started_at": "2025-12-05T14:47:05.848Z",
      "ended_at": "0001-01-01T00:00:00Z",
      "instance_id": "sim-1234-abcd",
      "ip": "10.156.15.230",
      "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
      "instance_type": "n1-standard-8",
      "file_path": "gs://your-project-simulation_files/path/",
      "max_simulation_time": 60,
      "max_report_count": 1
    },
    {
      "id": "5678-efgh",
      "owner": "some@email.com",
      "status": "completed",
      "status_updated_at": "2025-11-07T14:49:54.25Z",
      "received_at": "2025-11-07T14:46:54.959Z",
      "started_at": "2025-11-07T14:47:13.714Z",
      "ended_at": "0001-01-01T00:00:00Z",
      "instance_id": "sim-5678-efgh",
      "ip": "10.156.15.221",
      "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
      "instance_type": "n1-standard-8",
      "file_path": "gs://your-project-simulation_files/path/",
      "max_simulation_time": 60,
      "max_report_count": 1
    }
  ],
  "next_page_token": "M7bydGsAptLncj8SOCb1"
}

2. Obtén una simulación específica

Recupera los detalles completos de una simulación específica por su ID.

  • Endpoint:

    GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]

  • Respuesta correcta (200 OK): Muestra un objeto JSON que contiene los detalles de la simulación solicitada.

    {
  "id": "1234-abcd",
  "owner": "some@email.com",
  "status": "completed",
  "status_updated_at": "2025-12-05T14:50:00.952Z",
  "received_at": "2025-12-05T14:46:43.106Z",
  "started_at": "2025-12-05T14:47:05.848Z",
  "ended_at": "0001-01-01T00:00:00Z",
  "instance_id": "sim-1234-abcd",
  "ip": "10.156.15.230",
  "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
  "instance_type": "n1-standard-8",
  "file_path": "gs://your-project-simulation_files/path/",
  "max_simulation_time": 60,
  "max_report_count": 1
}

3. Obtén la configuración y las métricas del sistema

Estos extremos proporcionan información sobre la carga y la configuración actuales de la infraestructura de simulación.

  • Get Running Count: Devuelve el recuento de simulaciones en ejecución.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count

    • Respuesta de éxito (200 OK):

      {
  "count": 0
}

  • Get Max Concurrent VMs: Devuelve la cantidad máxima configurada de VMs en ejecución simultánea.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms

    • Respuesta de éxito (200 OK):

      {
  "max_running_vms": 5
}