Nutzerhandbuch

Sie können Simulationen mit der bereitgestellten Webdemo ausführen oder die REST API direkt aufrufen.

Ein- 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 Verzeichnis simulations, in dem jede Simulation anhand 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 generierte Simulatordateien.

Webdemo verwenden

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

Die Demo-App wird in App Engine bereitgestellt und erfordert, dass sich Nutzer mit einem Google-Konto anmelden. Sie ist mit einer OAuth 2.0-Client-ID geschützt, die in Ihrem Google Cloud-Projekt konfiguriert ist. Das angemeldete Konto muss IAM-Berechtigungen haben, um die bereitgestellten Cloud Functions-Funktionen aufzurufen. Unter Zugriff auf Cloud Functions verwalten finden Sie eine Anleitung zum Gewähren der erforderlichen Berechtigungen für Nutzerkonten, z. B. die Rolle Cloud Functions-Aufrufer (roles/cloudfunctions.invoker).

Nutzerworkflow

  1. Anmelden: Sie melden sich mit Ihrem Google-Konto an und werden mit dem OAuth 2.0-Verfahren authentifiziert.
  2. Simulationen ansehen: Auf der Hauptseite werden alle bisherigen und aktuellen Simulationen aufgelistet. Dazu wird die Firestore-Datenbank abgefragt, die alle Ausführungs informationen enthält.
  3. Simulation erstellen: Sie rufen ein Formular auf, um eine neue Simulation zu planen. Klicken Sie dazu rechts unten auf die Aktionsschaltfläche +. Sie geben mehrere Parameter an, darunter den Eingabepfad, die Build-ID und den Instanztyp. Weitere Informationen finden Sie unter Simulation erstellen.
  4. Status beobachten: Die Liste der Simulationen wird aktualisiert und zeigt den Status der neuen Simulation an (PENDING, RUNNING, COMPLETED, usw.).
  5. Ergebnisse ansehen: Nach Abschluss einer Simulation können Sie die generierten Berichte und Artefakte ansehen. Die Eingabedateien, Ausgabeprotokolle, Logs, Logcat und Fehlerberichte werden in Cloud Storage gespeichert.
  6. Simulation löschen: Sie können eine geplante oder laufende Simulation abbrechen.

API-Nutzung

Für die Automatisierung und Integration mit anderen Systemen können Sie die REST API verwenden.

Der Platzhalter CLOUD_FUNCTION_URL der im Abschnitt Authentifizierung und in den 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 können Sie diese URLs in den Terraform-Ausgaben finden, 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 nachweist. Die Identität (Nutzer- oder Dienstkonto) muss für die Zielfunktion die Berechtigung Cloud Functions-Aufrufer 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 von einer Google Cloud-Ressource aufrufen (z.B. einer Compute Engine-VM, einer anderen Cloud Functions-Funktion oder einem Kubernetes-Cluster), sollten Sie die Identität des angehängten Dienstkontos der Ressource verwenden. 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 im 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

Dieser Endpunkt erstellt eine neue Simulationsanfrage und plant sie zur Ausführung.

  • 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 des Agents (z.B. „latest“). Wichtig: Dieses Tag muss mit einem Tag übereinstimmen, das in der Zulässige Image-Zuordnung der Infrastruktur definiert ist (z.B. „latest“, „stable“). Das System lehnt unbekannte Tags ab, wenn in Terraform eine SHA256-Zuordnung definiert ist.
    • 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 unter Verschachtelte Virtualisierung – Übersicht.
    • 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

Dieser Endpunkt bricht eine ausstehende oder laufende Simulation ab und löscht die zugehörigen Ressourcen.

  • 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.

1. Simulationen auflisten

Ruft eine paginierte Liste von Simulationen ab, die gefiltert und sortiert werden kann.

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

  • Abfrageparameter (alle optional):

    • status (String): Nach 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). Der Standardwert ist received_at.
    • sort_order (String): Sortierrichtung, asc oder desc. Der Standardwert 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 mit einem Array von Simulationen und einem optionalen next_page_token zurück.
    {
  "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. 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
}

3. Systemmesswerte und -konfiguration abrufen

Diese Endpunkte geben Einblick in 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
}

  • Maximale Anzahl gleichzeitiger VMs abrufen: Gibt die konfigurierte maximale Anzahl gleichzeitig ausgeführter VMs zurück.

    • Endpunkt:

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

    • Erfolgreiche Antwort (200 OK):

      {
  "max_running_vms": 5
}