Nutzerhandbuch

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

Eingabe und Ausgabe

Für Eingabe- 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 dorthin 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 inputs-Ordner mit den kopierten Eingabedateien und einen outputs-Ordner. Der Ordner outputs enthält den Fehlerbericht, die Logcat-Datei und generierte Simulatordateien.

Web-Demo verwenden

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

Die Demoanwendung wird in App Engine bereitgestellt und erfordert die Anmeldung mit einem Google-Konto. Diese wird mit einer OAuth 2.0-Client-ID geschützt, die in Ihrem Google Cloud-Projekt konfiguriert ist. Das angemeldete Konto muss IAM-Berechtigungen zum Aufrufen der bereitgestellten Cloud Functions-Funktionen haben. 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-Prozess authentifiziert wurde.
  2. Auf der Hauptseite werden alle Simulationen angezeigt. Dazu wird die Firestore-Datenbank abgefragt, die alle Ausführungsinformationen enthält.
  3. Rufen Sie ein Formular auf, um eine neue Simulation zu planen, indem Sie rechts unten auf den Aktionsbutton + klicken. 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, die den Status der neuen Simulation anzeigen, z. B. PENDING, RUNNING, COMPLETED.
  5. Nach Abschluss einer Simulation können Sie sich die generierten Berichte und Artefakte ansehen. Die Eingabedateien, Ausgabeberichte, 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. Sie finden Funktions-URLs 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 belegt. Die Identität (Nutzer- oder Dienstkonto) muss die Berechtigung „Cloud Functions-Aufrufer“ 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 (innerhalb von Google Cloud): Wenn Sie die API von einer Google Cloud-Ressource (z. B. einer Compute Engine-VM, einer anderen Cloud Functions-Funktion oder einem Kubernetes-Cluster) aufrufen, 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 im Authorization-Header Ihrer Anfragen als Bearer-Token ein.

Endpunkte

Über die für Nutzer sichtbaren Endpunkte 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 für die Ausführung.

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

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

    • file_path (String): Der Pfad im GCS-Bucket zum Ordner, der metrics_config.zip und publisher_config.zip enthält.

    • instance_type (String): Der Compute Engine-Maschinentyp. Dieser Typ muss verschachtelte Virtualisierung unterstützen, z. B. die Serien n1, n2 oder t2d. Weitere Informationen finden Sie unter Informationen 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.

  • Erfolgsantwort (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" }

  • Erfolgsantwort (200 OK): Eine Nur-Text-Nachricht (Request accepted and is being processed).

Simulationsdaten lesen

Wenn Sie Simulationsdaten lesen möchten, können Sie die Funktion simulation-reader verwenden. Diese Endpunkte verwenden die Methode GET, um Verlauf, Status und Systemkonfiguration abzurufen.

Simulationen auflisten

Ruft eine paginierte Liste von Simulationen ab, die gefiltert und sortiert werden können.

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

  • Abfrageparameter (alle optional):

    • status (String): Nach Simulationsstatus filtern (running, Simulation request received, cancelled, completed oder failed).
    • 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). Standardwert ist received_at.
    • sort_order (String): Sortierrichtung, asc oder desc. Die Standardeinstellung ist desc.
    • page_size (Ganzzahl): Anzahl der Ergebnisse pro Seite. Die Standardeinstellung 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"

  • Erfolgsantwort (200 OK):

    • Gibt ein JSON-Objekt zurück, das ein Array von Simulationen und ein optionales 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"
}
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 bieten 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

    • Erfolgsantwort (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

    • Erfolgsantwort (200 OK):

      {
  "max_running_vms": 5
}