Guía del usuario

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

INPUT y OUTPUT

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 inputs con los archivos de entrada copiados y una carpeta outputs. La carpeta outputs contiene el informe de errores, el archivo logcat y los archivos generados del simulador.

Usa la demostración web

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

La app de demostración se implementa en App Engine y requiere que accedas 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 que accedió debe tener permisos de IAM para invocar las Cloud Functions implementadas. Consulta Autoriza el acceso con IAM para obtener instrucciones sobre cómo otorgar los permisos necesarios a las cuentas de usuario, como el rol de invocador de Cloud Functions (roles/cloudfunctions.invoker).

Flujo de trabajo del usuario

  1. Accede con tu Cuenta de Google, autenticada con el proceso de OAuth 2.0.
  2. Visualiza las simulaciones en la página principal, que enumera todas las simulaciones consultando la base de datos de Firestore, que contiene toda la información de ejecución.
  3. Navega a un formulario para programar una simulación nueva haciendo clic en el botón de acción + en la esquina inferior derecha. Debes proporcionar varios parámetros, como la ruta de acceso de entrada, el ID de compilación y el tipo de instancia. Para obtener más información, consulta Crea una simulación.
  4. Verifica el estado del monitor en las actualizaciones de la lista de simulaciones, que muestran el estado de la simulación nueva, por ejemplo, PENDING, RUNNING, COMPLETED.
  5. Una vez que se complete una simulación, consulta 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. Opcional: Cancela 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 Cloud Function 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 demuestre la identidad del emisor. La identidad (cuenta de usuario o 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 invoques la API desde una máquina local o un entorno que no sea de Google Cloud, debes usar un token de identidad emitido por Google que se haya obtenido 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 (por ejemplo, una VM de Compute Engine, otra Cloud Function o un clúster de Kubernetes), usa la identidad de la cuenta de servicio adjunta del 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 Bearer.

Extremos

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

Crea una simulación

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

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

  • 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 (string): Es la etiqueta de la imagen de Docker del agente que se usará, por ejemplo,latest.

    • 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 correcta (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Borra 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): Es un mensaje de texto sin formato (Request accepted and is being processed).

Lee los datos de la simulación

Para leer los datos de la 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.

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 consulta (todos opcionales):

    • status (cadena): Filtra por estado de la simulación (running, Simulation request received, cancelled, completed o failed).
    • owner (cadena): Filtra por el correo electrónico del propietario.
    • sort_by (string): Es el campo por el que se ordenará (received_at, status_updated_at, started_at). El valor predeterminado es received_at.
    • sort_order (cadena): Es la dirección de ordenamiento, asc o desc. La configuración predeterminada es desc.
    • page_size (número entero): Es la cantidad de resultados por página. La configuración predeterminada es 20.
    • page_token (cadena): Es el 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 correcta (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"
}
Obtener una simulación específica

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

  • Extremo:

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

  • Respuesta correcta (200 OK): Devuelve 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
}
Obtén métricas y configuración del sistema

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

  • Obtener recuento de ejecuciones: Devuelve el recuento de simulaciones en ejecución.

    • Extremo:

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

    • Respuesta correcta (200 OK):

      {
  "count": 0
}

  • Obtener el máximo de VMs simultáneas: Devuelve la cantidad máxima configurada de VMs que se ejecutan de forma simultánea.

    • Extremo:

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

    • Respuesta correcta (200 OK):

      {
  "max_running_vms": 5
}