Guida dell'utente

Puoi eseguire le simulazioni utilizzando la demo web fornita o chiamando direttamente l'API REST.

Input e output

I file di input e output utilizzano il bucket Cloud Storage della configurazione di Terraform.

La directory di input deve contenere i file metrics_config.zip e publisher_config.zip. Puoi definire il percorso in base alle esigenze.

Il bucket per gli output contiene una directory simulations, che archivia ogni simulazione in base al relativo ID. Ogni directory di simulazione contiene una cartella di input con i file di input copiati e una cartella di output. La cartella di output contiene il report sui bug, il file logcat e i file del simulatore generati.

Utilizzare la demo web

La piattaforma include un'applicazione web basata su Flutter a scopo dimostrativo che consente di visualizzare, creare e gestire le simulazioni. Ti invitiamo a creare la tua interfaccia utente personalizzata in base alle tue esigenze.

L'app demo viene sottoposta a deployment in App Engine e richiede agli utenti di accedere con un Account Google. È protetta utilizzando un ID client OAuth 2.0 configurato nel tuo progetto Google Cloud. L'account con cui hai eseguito l'accesso deve disporre delle autorizzazioni IAM per richiamare le Cloud Functions di cui è stato eseguito il deployment. Per istruzioni su come concedere le autorizzazioni necessarie agli account utente, ad esempio il ruolo Invoker di Cloud Functions (roles/cloudfunctions.invoker), consulta Gestire l'accesso a Cloud Functions.

Flusso di lavoro utente

  1. Accedi: accedi con il tuo Account Google, autenticato utilizzando il processo OAuth 2.0.
  2. Visualizza le simulazioni: la pagina principale elenca tutte le simulazioni passate e attuali eseguendo query sul database Firestore, che contiene tutte le informazioni di esecuzione.
  3. Crea una simulazione: vai a un modulo per pianificare una nuova simulazione facendo clic sul pulsante di azione + nell'angolo in basso a destra. Fornisci diversi parametri, tra cui il percorso di input, l'ID build e il tipo di istanza. Per ulteriori informazioni, vedi Creare una simulazione.
  4. Monitora lo stato: l'elenco delle simulazioni viene aggiornato per mostrare lo stato della nuova simulazione (PENDING, RUNNING, COMPLETED, e così via).
  5. Visualizza i risultati: al termine di una simulazione, puoi visualizzare i report e gli artefatti generati. I file di input, i report di output, i log, Logcat e i report sui bug vengono archiviati in Cloud Storage.
  6. Elimina una simulazione: puoi annullare una simulazione pianificata o in esecuzione.

Utilizzo delle API

Per l'automazione e l'integrazione con altri sistemi, puoi utilizzare l'API REST.

Il segnaposto CLOUD_FUNCTION_URL utilizzato nella sezione Autenticazione e nelle definizioni degli endpoint si riferisce all' URL di base della Cloud Function richiamata. Puoi trovare gli URL delle funzioni nella console Google Cloud nella pagina Cloud Functions ; l'URL di ogni funzione viene visualizzato nella scheda Trigger della pagina Dettagli funzione. In alternativa, puoi trovare questi URL negli output di Terraform stampati dopo l'esecuzione di un comando apply.

Autenticazione

Tutte le richieste API devono essere autenticate con un token ID che dimostri l'identità del chiamante. L'identità (utente o service account) deve disporre delle autorizzazioni Invoker di Cloud Functions sulla funzione di destinazione.

  • 1. Richiamo utente (locale e CLI) Quando richiami l'API da una macchina locale o da un ambiente non Google Cloud, devi utilizzare un token ID emesso da Google ottenuto per un account utente.

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

  • 2. Richiamo del service account (all'interno di Google Cloud) Quando richiami l'API da una risorsa Google Cloud (ad es. una VM Compute Engine, un'altra Cloud Function o un cluster Kubernetes), devi utilizzare l'identità del service account collegato alla risorsa. Il token deve essere recuperato dal server di metadati della risorsa.

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

Includi il token recuperato nell'intestazione Authorization delle richieste come token Bearer.

Endpoint

Gli endpoint rivolti agli utenti dello stack di simulazione di telemetria cloud consentono di creare ed eliminare simulazioni o leggere le informazioni di simulazione dal database.

Creare una simulazione

Questo endpoint crea una nuova richiesta di simulazione e la pianifica per l'esecuzione.

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

  • Corpo della richiesta:

    {
  "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 (stringa): il tag dell'immagine Docker dell'agente da utilizzare (ad es. "latest"). Importante: deve corrispondere a un tag definito nella mappa delle immagini consentite dell'infrastruttura (ad es. "latest", "stable"). Se in Terraform è definita una mappa SHA256, il sistema rifiuta i tag sconosciuti.
    • file_path (stringa): il percorso all'interno del bucket GCS della cartella contenente metrics_config.zip e publisher_config.zip.
    • instance_type (stringa): il tipo di macchina Compute Engine. Questo tipo deve supportare la virtualizzazione nidificata, ad esempio le serie n1, n2 o t2d. Per ulteriori informazioni, vedi la panoramica della virtualizzazione nidificata.
    • owner (stringa): l'indirizzo email dell'utente che avvia la simulazione.
    • max_simulation_time (intero): il tempo massimo in secondi di esecuzione della simulazione.
    • max_report_count (intero): il numero di report di telemetria dopo il quale la simulazione termina.

  • Risposta di successo (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Eliminare una simulazione

Questo endpoint annulla una simulazione in attesa o in esecuzione ed elimina le risorse associate.

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

  • Corpo della richiesta:

    { "id": "sim-a1b2c3d4e5f6" }

  • Risposta di successo (200 OK): un oggetto JSON vuoto {}.

Leggere i dati di simulazione

Per leggere i dati di simulazione, puoi interagire con la funzione simulation-reader. Questi endpoint utilizzano il metodo GET per recuperare la cronologia, lo stato e la configurazione del sistema.

1. Elencare le simulazioni

Recupera un elenco paginato di simulazioni con supporto per il filtraggio e l'ordinamento.

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

  • Parametri di query (tutti facoltativi):

    • status (stringa): filtra in base allo stato della simulazione (running, Simulation request received, cancelled o completed).
    • owner (stringa): filtra in base all'indirizzo email del proprietario.
    • sort_by (stringa): campo in base al quale ordinare (received_at, status_updated_at, started_at). Il valore predefinito è received_at.
    • sort_order (stringa): direzione di ordinamento, asc o desc. Il valore predefinito è desc.
    • page_size (intero): numero di risultati per pagina. Il valore predefinito è 20.
    • page_token (stringa): token per recuperare la pagina successiva dei risultati.

  • Richiesta di esempio:

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

  • Risposta di successo (200 OK):

    • Restituisce un oggetto JSON contenente un array di simulazioni e un next_page_token facoltativo.
    {
  "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. Recuperare una simulazione specifica

Recupera i dettagli completi di una simulazione specifica in base al relativo ID.

  • Endpoint:

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

  • Risposta di successo (200 OK): restituisce un oggetto JSON contenente i dettagli della simulazione richiesta.

    {
  "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. Recuperare le metriche e la configurazione del sistema

Questi endpoint forniscono informazioni sul carico e sulla configurazione attuali dell'infrastruttura di simulazione.

  • Recuperare il conteggio parziale: restituisce il conteggio delle simulazioni in esecuzione.

    • Endpoint:

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

    • Risposta di successo (200 OK):

      {
  "count": 0
}

  • Recuperare il numero massimo di VM simultanee: restituisce il numero massimo configurato di VM in esecuzione simultanea.

    • Endpoint:

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

    • Risposta di successo (200 OK):

      {
  "max_running_vms": 5
}