Nutzerhandbuch

Sie können Simulationen mit der bereitgestellten Webdemo oder durch direkten Aufruf der REST API ausführen.

Eingabe und Ausgabe

Für Ein- und Ausgabedateien wird der Cloud Storage-Bucket aus der Terraform-Einrichtung verwendet.

Das Eingabeverzeichnis muss die Dateien metrics_config.zip und publisher_config.zip enthalten. Sie können den Pfad nach Bedarf definieren.

Der Bucket für Ausgaben enthält ein simulations-Verzeichnis, in dem jede Simulation nach ihrer ID gespeichert wird. Jedes Simulationsverzeichnis enthält einen Eingabeordner mit den kopierten Eingabedateien und einen Ausgabeordner. Der Ausgabeordner enthält den Fehlerbericht, die Logcat-Datei und die generierten Simulator-Dateien.

Webdemo verwenden

Die Plattform umfasst eine Flutter-basierte Webanwendung zu Demonstrationszwecken, mit der Sie Simulationen ansehen, erstellen und verwalten können. Sie können eine eigene Benutzeroberfläche erstellen, die auf Ihre Bedürfnisse zugeschnitten ist.

Die Demo-App wird in App Engine bereitgestellt und erfordert die Anmeldung mit einem Google-Konto. Dies wird durch eine OAuth 2.0-Client-ID geschützt, die in Ihrem Google Cloud-Projekt konfiguriert ist. Das angemeldete Konto muss über IAM-Berechtigungen zum Aufrufen der bereitgestellten Cloud Functions verfügen. Eine Anleitung zum Erteilen der erforderlichen Berechtigungen für Nutzerkonten, z. B. die Rolle „Cloud Functions Invoker“ (roles/cloudfunctions.invoker), finden Sie unter Zugriff mit IAM autorisieren.

Nutzer-Workflow

  1. Melden Sie sich mit Ihrem Google-Konto an, das über den OAuth 2.0-Vorgang authentifiziert wurde.
  2. Auf der Hauptseite können Sie sich alle Simulationen ansehen. Dazu wird die Firestore-Datenbank abgefragt, in der alle Ausführungsinformationen gespeichert sind.
  3. Rufen Sie ein Formular auf, um eine neue Simulation zu planen. Klicken Sie dazu rechts unten auf die Schaltfläche +. Sie geben mehrere Parameter an, darunter den Eingabepfad, die Build-ID und den Instanztyp. Weitere Informationen finden Sie unter Simulation erstellen.
  4. Prüfen Sie den Monitorstatus in den Aktualisierungen der Simulationsliste. Dort wird der Status der neuen Simulation angezeigt, z. B. PENDING, RUNNING, COMPLETED.
  5. Nach Abschluss einer Simulation können Sie die generierten Berichte und Artefakte ansehen. Die Eingabedateien, Ausgabedateien, Logs, Logcat und Fehlerberichte werden in Cloud Storage gespeichert.
  6. Optional: Geplante oder laufende Simulation abbrechen.

API-Nutzung

Für die Automatisierung und Integration in andere Systeme können Sie die REST API verwenden.

Der Platzhalter CLOUD_FUNCTION_URL, der im Abschnitt „Authentifizierung“ und in Endpunktdefinitionen verwendet wird, bezieht sich auf die Basis-URL der aufgerufenen Cloud Functions-Funktion. Funktions-URLs finden Sie in der Google Cloud Console auf der Seite Cloud Functions. Die URL für jede Funktion wird auf dem Tab Trigger der Seite Funktionsdetails angezeigt. Alternativ finden Sie diese URLs in den Terraform-Ausgaben, die nach dem Ausführen eines apply-Befehls ausgegeben werden.

Authentifizierung

Alle API-Anfragen müssen mit einem Identitätstoken authentifiziert werden, das die Identität des Aufrufers beweist. Die Identität (Nutzer oder Dienstkonto) muss die Berechtigungen des Cloud Functions-Aufrufers für die Zielfunktion haben.

  1. Nutzeraufruf (lokal und CLI): Wenn Sie die API von einem lokalen Computer oder einer Nicht-Google Cloud-Umgebung aufrufen, müssen Sie ein von Google ausgestelltes Identitätstoken verwenden, das für ein Nutzerkonto abgerufen wurde.

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

  2. Dienstkontoaufruf (in Google Cloud): Wenn Sie die API über eine Google Cloud-Ressource aufrufen (z. B. eine Compute Engine-VM, eine andere Cloud-Funktion oder einen Kubernetes-Cluster), verwenden Sie die Identität des angehängten Dienstkontos der Ressource. Das Token sollte vom Metadatenserver der Ressource abgerufen werden.

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

Fügen Sie das abgerufene Token in den Authorization-Header Ihrer Anfragen als Bearer-Token ein.

Endpunkte

Mit den nutzerorientierten Endpunkten des Cloud Telemetry Simulation-Stacks können Sie Simulationen erstellen und löschen oder Simulationsinformationen aus der Datenbank lesen.

Simulation erstellen

Mit diesem Endpunkt wird eine neue Simulationsanfrage erstellt und zur Ausführung geplant.

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

  • Anfragetext:

    {
  "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): Das Tag des zu verwendenden Docker-Images für den Agenten, z. B. latest.

    • file_path (String): Der Pfad im GCS-Bucket zum Ordner mit metrics_config.zip und publisher_config.zip.

    • instance_type (String): Der Compute Engine-Maschinentyp. Dieser Typ muss die verschachtelte Virtualisierung unterstützen, z. B. die Serien n1, n2 oder t2d. Weitere Informationen finden Sie in der Übersicht zur verschachtelten Virtualisierung.

    • owner (String): Die E-Mail-Adresse des Nutzers, der die Simulation initiiert.

    • max_simulation_time (Ganzzahl): Die maximale Zeit in Sekunden, die die Simulation ausgeführt wird.

    • max_report_count (Ganzzahl): Die Anzahl der Telemetrieberichte, nach denen die Simulation beendet wird.

  • Erfolgreiche Antwort (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Simulation löschen

Mit diesem Endpunkt wird eine ausstehende oder laufende Simulation abgebrochen und die zugehörigen Ressourcen werden gelöscht.

  • Endpunkt:POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Header:
    • Content-Type: application/json

  • Anfragetext:

    { "id": "sim-a1b2c3d4e5f6" }

  • Erfolgreiche Antwort (200 OK): Ein leeres JSON-Objekt {}.

Simulationsdaten lesen

Um Simulationsdaten zu lesen, können Sie mit der Funktion simulation-reader interagieren. Diese Endpunkte verwenden die Methode GET, um Verlauf, Status und Systemkonfiguration abzurufen.

Simulationen auflisten

Ruft eine paginierte Liste von Simulationen ab, die Filterung und Sortierung unterstützt.

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

  • Abfrageparameter (alle optional):

    • status (String): Nach dem Simulationsstatus filtern (running, Simulation request received, cancelled oder completed).
    • owner (String): Nach der E-Mail-Adresse des Inhabers filtern.
    • sort_by (String): Feld, nach dem sortiert werden soll (received_at, status_updated_at, started_at). Standardmäßig wird nach received_at sortiert.
    • sort_order (String): Sortierrichtung, asc oder desc. Die Standardeinstellung ist desc.
    • page_size (Ganzzahl): Anzahl der Ergebnisse pro Seite. Der Standardwert ist 20.
    • page_token (string): Token zum Abrufen der nächsten Ergebnisseite.

  • Beispielanfrage:

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

  • Erfolgreiche Antwort (200 OK):

    • Gibt ein JSON-Objekt zurück, das ein Array von Simulationen und einen optionalen next_page_token enthält.
    {
  "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"
}
Eine bestimmte Simulation abrufen

Ruft die vollständigen Details einer bestimmten Simulation anhand ihrer ID ab.

  • Endpunkt:

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

  • Erfolgreiche Antwort (200 OK): Gibt ein JSON-Objekt mit den Details der angeforderten Simulation zurück.

    {
  "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
}
Systemmesswerte und ‑konfiguration abrufen

Diese Endpunkte geben Aufschluss über die aktuelle Last und Konfiguration der Simulationsinfrastruktur.

  • Laufende Anzahl abrufen:Gibt die Anzahl der laufenden Simulationen zurück.

    • Endpunkt:

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

    • Erfolgreiche Antwort (200 OK):

      {
  "count": 0
}

  • Get max concurrent VMs:Gibt die konfigurierte maximale Anzahl von gleichzeitig ausgeführten VMs zurück.

    • Endpunkt:

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

    • Erfolgreiche Antwort (200 OK):

      {
  "max_running_vms": 5
}