Przewodnik użytkownika

Symulacje możesz uruchamiać za pomocą udostępnionej wersji demonstracyjnej w internecie lub przez bezpośrednie wywoływanie interfejsu API REST.

Dane wejściowe i wyjściowe

Pliki wejściowe i wyjściowe korzystają z zasobnika Cloud Storage z konfiguracji Terraform.

Katalog wejściowy musi zawierać pliki metrics_config.zip i publisher_config.zip. W razie potrzeby możesz zdefiniować ścieżkę do niego.

Zasobnik na dane wyjściowe zawiera katalog simulations, w którym każda symulacja jest przechowywana według identyfikatora. Każdy katalog symulacji zawiera folder wejściowy ze skopiowanymi plikami wejściowymi i folder wyjściowy. Folder wyjściowy zawiera raport o błędach, plik logcat i wygenerowane pliki symulatora.

Korzystanie z wersji demonstracyjnej w internecie

Platforma zawiera aplikację internetową opartą na Flutterze do celów demonstracyjnych, która umożliwia wyświetlanie, tworzenie i zarządzanie symulacjami. Zachęcamy do utworzenia własnego interfejsu użytkownika dostosowanego do Twoich potrzeb.

Aplikacja w wersji demonstracyjnej jest wdrażana w App Engine i wymaga od użytkowników zalogowania się na konto Google. Jest ona chroniona za pomocą identyfikatora klienta OAuth 2.0 skonfigurowanego w projekcie Google Cloud. Zalogowane konto musi mieć uprawnienia IAM do wywoływania wdrożonych funkcji Cloud Functions. Instrukcje dotyczące przyznawania niezbędnych uprawnień kontom użytkowników, takich jak rola Wywołujący funkcje Cloud Functions (roles/cloudfunctions.invoker), znajdziesz w artykule Zarządzanie dostępem do Cloud Functions.

Proces użytkownika

  1. Zaloguj się: zaloguj się na konto Google, uwierzytelniając się za pomocą procesu OAuth 2.0.
  2. Wyświetl symulacje: na stronie głównej wyświetlana jest lista wszystkich poprzednich i bieżących symulacji Jest ona tworzona na podstawie zapytań do bazy danych Firestore, która zawiera wszystkie informacje o wykonaniu.
  3. Utwórz symulację: aby zaplanować nową symulację, kliknij przycisk polecenia + w prawym dolnym rogu. Podaj kilka parametrów, w tym ścieżkę wejściową, identyfikator kompilacji i typ instancji. Więcej informacji znajdziesz w artykule Tworzenie symulacji.
  4. Monitoruj stan: lista symulacji jest aktualizowana, aby wyświetlać stan nowej symulacji (PENDING, RUNNING, COMPLETED, itp.).
  5. Wyświetl wyniki: po zakończeniu symulacji możesz wyświetlić wygenerowane raporty i artefakty. Pliki wejściowe, raporty wyjściowe, logi, Logcat i raporty o błędach są przechowywane w Cloud Storage.
  6. Usuń symulację: możesz anulować zaplanowaną lub uruchomioną symulację.

Korzystanie z interfejsu API

Do automatyzacji i integracji z innymi systemami możesz używać interfejsu API REST.

Symbol zastępczy CLOUD_FUNCTION_URL używany w sekcji Uwierzytelnianie i w definicjach punktów końcowych odnosi się do podstawowego adresu URL wywoływanej funkcji Cloud Functions. Adresy URL funkcji znajdziesz w konsoli Google Cloud na stronie Cloud Functions . Adres URL każdej funkcji jest widoczny na karcie Wyzwalacz na stronie Szczegóły funkcji. Możesz też znaleźć te adresy URL w danych wyjściowych Terraform, które są wyświetlane po uruchomieniu polecenia apply.

Uwierzytelnianie

Wszystkie żądania interfejsu API muszą być uwierzytelniane za pomocą tokena tożsamości , który potwierdza tożsamość wywołującego. Tożsamość (użytkownika lub konta usługi) musi mieć uprawnienia Wywołujący funkcje Cloud Functions do funkcji docelowej.

  • 1. Wywołanie przez użytkownika (lokalne i CLI) Jeśli wywołujesz interfejs API z komputera lokalnego lub środowiska innego niż Google Cloud, musisz użyć tokena tożsamości wydanego przez Google , który został uzyskany na potrzeby konta użytkownika.

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

  • 2. Wywołanie przez konto usługi (w Google Cloud) Jeśli wywołujesz interfejs API z zasobu Google Cloud (np. maszyny wirtualnej Compute Engine, innej funkcji Cloud Functions lub klastra Kubernetes), użyj tożsamości dołączonego do zasobu konta usługi. Token należy pobrać z serwera metadanych zasobu.

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

Dołącz pobrany token do nagłówka Authorization w żądaniach jako token Bearer.

Punkty końcowe

Punkty końcowe stosu symulacji telemetrii w chmurze, z których korzystają użytkownicy, umożliwiają tworzenie i usuwanie symulacji oraz odczytywanie informacji o symulacji z bazy danych.

Tworzenie symulacji

Ten punkt końcowy tworzy nowe żądanie symulacji i planuje jego wykonanie.

  • Punkt końcowy: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

  • Treść żądania:

    {
  "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 (ciąg znaków): tag obrazu Dockera agenta, który ma być używany (np. „latest”). Ważne: musi on odpowiadać tagowi zdefiniowanemu w mapie dozwolonych obrazów infrastruktury (np. „latest”, „stable”). Jeśli w Terraform jest zdefiniowana mapa SHA256, system odrzuca nieznane tagi.
    • file_path (ciąg znaków): ścieżka w zasobniku GCS do folderu zawierającego pliki metrics_config.zip i publisher_config.zip.
    • instance_type (ciąg znaków): typ maszyny Compute Engine. Ten typ musi obsługiwać zagnieżdżoną wirtualizację, np. serie n1, n2 lub t2d. Więcej informacji znajdziesz w omówieniu zagnieżdżonej wirtualizacji.
    • owner (ciąg znaków): adres e-mail użytkownika, który inicjuje symulację.
    • max_simulation_time (liczba całkowita): maksymalny czas w sekundach , przez jaki ma działać symulacja.
    • max_report_count (liczba całkowita): liczba raportów telemetrii, po których symulacja się kończy.

  • Odpowiedź o powodzeniu (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Usuwanie symulacji

Ten punkt końcowy anuluje oczekującą lub uruchomioną symulację i usuwa powiązane z nią zasoby.

  • Punkt końcowy: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Nagłówki:
    • Content-Type: application/json

  • Treść żądania:

    { "id": "sim-a1b2c3d4e5f6" }

  • Odpowiedź o powodzeniu (200 OK): pusty obiekt JSON {}.

Odczytywanie danych symulacji

Aby odczytać dane symulacji, możesz korzystać z funkcji simulation-reader. Te punkty końcowe używają metody GET do pobierania historii, stanu i konfiguracji systemu.

1. Wyświetlanie listy symulacji

Pobiera stronicowaną listę symulacji z obsługą filtrowania i sortowania.

  • Punkt końcowy: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Parametry zapytania (wszystkie opcjonalne):

    • status (ciąg znaków): filtr według stanu symulacji (running, Simulation request received, cancelled lub completed).
    • owner (ciąg znaków): filtr według adresu e-mail właściciela.
    • sort_by (ciąg znaków): pole, według którego ma być sortowana lista (received_at, status_updated_at, started_at). Domyślnie jest to received_at.
    • sort_order (ciąg znaków): kierunek sortowania, asc lub desc. Domyślnie jest to desc.
    • page_size (liczba całkowita): liczba wyników na stronie. Domyślna wartość to 20.
    • page_token (ciąg znaków): token do pobierania następnej strony wyników.

  • Przykładowe żądanie:

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

  • Odpowiedź o powodzeniu (200 OK):

    • Zwraca obiekt JSON zawierający tablicę symulacji i opcjonalny token next_page_token.
    {
  "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. Pobieranie konkretnej symulacji

Pobiera pełne szczegóły konkretnej symulacji według jej identyfikatora.

  • Punkt końcowy:

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

  • Odpowiedź o powodzeniu (200 OK): zwraca obiekt JSON zawierający szczegóły żądanej symulacji.

    {
  "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. Pobieranie danych i konfiguracji systemu

Te punkty końcowe umożliwiają uzyskanie informacji o bieżącym obciążeniu i konfiguracji infrastruktury symulacji.

  • Get Running Count: zwraca liczbę uruchomionych symulacji.

    • Punkt końcowy:

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

    • Odpowiedź o powodzeniu (200 OK):

      {
  "count": 0
}

  • Get Max Concurrent VMs: zwraca skonfigurowaną maksymalną liczbę równoczesnych uruchomionych maszyn wirtualnych.

    • Punkt końcowy:

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

    • Odpowiedź o powodzeniu (200 OK):

      {
  "max_running_vms": 5
}