Panduan Pengguna

Anda dapat menjalankan simulasi menggunakan Demo Web yang disediakan atau dengan memanggil REST API secara langsung.

Input dan Output

File input dan output menggunakan bucket Cloud Storage dari penyiapan Terraform.

Direktori input harus berisi file metrics_config.zip dan publisher_config.zip. Anda dapat menentukan jalur ke file tersebut sesuai kebutuhan.

Bucket untuk output berisi direktori simulations, yang menyimpan setiap simulasi berdasarkan ID-nya. Setiap direktori simulasi berisi folder input dengan file input yang disalin dan folder output. Folder output berisi laporan bug, file logcat, dan file simulator yang dihasilkan.

Menggunakan Demo Web

Platform ini mencakup aplikasi web berbasis Flutter untuk tujuan demonstrasi yang memungkinkan Anda melihat, membuat, dan mengelola simulasi. Anda dianjurkan untuk membuat antarmuka pengguna sendiri yang disesuaikan dengan kebutuhan Anda.

Aplikasi demo di-deploy ke App Engine dan mewajibkan pengguna untuk login dengan Akun Google. Hal ini dilindungi menggunakan Client ID OAuth 2.0 yang dikonfigurasi di project Google Cloud Anda. Akun yang login harus memiliki izin IAM untuk memanggil Cloud Functions yang di-deploy. Lihat Mengelola akses ke Cloud Functions untuk mengetahui petunjuk tentang pemberian izin yang diperlukan ke akun pengguna, seperti peran Cloud Functions Invoker (roles/cloudfunctions.invoker).

Alur Kerja Pengguna

  1. Login: Anda login dengan Akun Google Anda, yang diautentikasi menggunakan proses OAuth 2.0.
  2. Melihat simulasi: Halaman utama mencantumkan semua simulasi sebelumnya dan saat ini dengan membuat kueri database Firestore, yang menyimpan semua informasi eksekusi.
  3. Buat simulasi: Anda membuka formulir untuk menjadwalkan simulasi baru dengan mengklik tombol tindakan + di pojok kanan bawah. Anda memberikan beberapa parameter, termasuk jalur input, ID build, dan jenis instance. Untuk mengetahui informasi selengkapnya, lihat Membuat Simulasi.
  4. Pantau status: Daftar simulasi diperbarui untuk menampilkan status simulasi baru (PENDING, RUNNING, COMPLETED, dll.).
  5. Melihat hasil: Setelah simulasi selesai, Anda dapat melihat laporan dan artefak yang dihasilkan. File input, laporan output, log, Logcat, dan Laporan bug disimpan di Cloud Storage.
  6. Menghapus simulasi: Anda dapat membatalkan simulasi terjadwal atau yang sedang berjalan.

Penggunaan API

Untuk otomatisasi dan integrasi dengan sistem lain, Anda dapat menggunakan REST API.

Placeholder CLOUD_FUNCTION_URL yang digunakan di bagian Authentication dan dalam definisi endpoint merujuk ke URL dasar Cloud Function yang dipanggil. Anda dapat menemukan URL fungsi di konsol Google Cloud pada halaman Cloud Functions; URL untuk setiap fungsi ditampilkan di tab Pemicu pada halaman Detail fungsi. Atau, Anda dapat menemukan URL ini di output Terraform yang dicetak setelah menjalankan perintah apply.

Autentikasi

Semua permintaan API harus diautentikasi dengan Token Identitas yang membuktikan identitas pemanggil. Identitas (pengguna atau akun layanan) harus memiliki izin Cloud Functions Invoker pada fungsi target.

  • 1. Pemanggilan Pengguna (Lokal dan CLI) Saat memanggil API dari mesin lokal atau lingkungan non-Google Cloud, Anda harus menggunakan Token Identitas yang dikeluarkan Google yang diperoleh untuk akun pengguna.

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

  • 2. Pemanggilan Akun Layanan (Dalam Google Cloud) Saat memanggil API dari resource Google Cloud (misalnya, VM Compute Engine, Cloud Function lain, atau cluster Kubernetes), Anda harus menggunakan identitas Akun Layanan terlampir resource. Token harus diambil dari server metadata resource.

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

Sertakan token yang diambil di header Authorization permintaan Anda sebagai token Bearer.

Endpoint

Endpoint yang menghadap pengguna dari stack Cloud Telemetry Simulation memungkinkan Anda membuat dan menghapus simulasi atau membaca informasi simulasi dari database.

Membuat Simulasi

Endpoint ini membuat permintaan simulasi baru dan menjadwalkannya untuk dieksekusi.

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

  • Isi Permintaan:

    {
  "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): Tag image Docker agen yang akan digunakan (misalnya, "latest"). Penting: Nilai ini harus cocok dengan tag yang ditentukan dalam peta gambar yang diizinkan infrastruktur (misalnya, "latest", "stable"). Sistem menolak tag yang tidak dikenal jika peta SHA256 ditentukan di Terraform.
    • file_path (string): Jalur dalam bucket GCS ke folder yang berisi metrics_config.zip dan publisher_config.zip.
    • instance_type (string): Jenis mesin Compute Engine. Jenis ini harus mendukung virtualisasi bertingkat, seperti seri n1, n2, atau t2d. Untuk mengetahui informasi selengkapnya, lihat ringkasan virtualisasi bertingkat.
    • owner (string): Email pengguna yang memulai simulasi.
    • max_simulation_time (bilangan bulat): Waktu maksimum dalam detik yang dijalankan simulasi.
    • max_report_count (integer): Jumlah laporan telemetri setelah simulasi selesai.

  • Respons Berhasil (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Menghapus Simulasi

Endpoint ini membatalkan simulasi yang tertunda atau sedang berjalan dan menghapus resource terkaitnya.

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

  • Isi Permintaan:

    { "id": "sim-a1b2c3d4e5f6" }

  • Respons Berhasil (200 OK): Objek JSON kosong {}.

Membaca Data Simulasi

Untuk membaca data simulasi, Anda dapat berinteraksi dengan fungsi simulation-reader. Endpoint ini menggunakan metode GET untuk mengambil histori, status, dan konfigurasi sistem.

1. Mencantumkan simulasi

Mengambil daftar simulasi yang di-pagination dengan dukungan untuk pemfilteran dan pengurutan.

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

  • Parameter Kueri (semua opsional):

    • status (string): Memfilter menurut status simulasi (running, Simulation request received, cancelled, atau completed).
    • owner (string): Memfilter menurut email pemilik.
    • sort_by (string): Kolom yang akan diurutkan (received_at, status_updated_at, started_at). Defaultnya adalah received_at.
    • sort_order (string): Arah pengurutan, asc atau desc. Nilai defaultnya adalah desc.
    • page_size (integer): Jumlah hasil per halaman. Defaultnya adalah 20.
    • page_token (string): Token untuk mengambil halaman hasil berikutnya.

  • Contoh Permintaan:

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

  • Respons Berhasil (200 OK):

    • Menampilkan objek JSON yang berisi array simulasi dan next_page_token opsional.
    {
  "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. Mendapatkan simulasi tertentu

Mengambil detail lengkap simulasi tertentu berdasarkan ID-nya.

  • Endpoint:

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

  • Respons Berhasil (200 OK): Menampilkan objek JSON yang berisi detail simulasi yang diminta.

    {
  "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. Mendapatkan metrik dan konfigurasi sistem

Endpoint ini memberikan insight tentang beban dan konfigurasi infrastruktur simulasi saat ini.

  • Dapatkan Jumlah Berjalan: Menampilkan jumlah simulasi yang sedang berjalan.

    • Endpoint:

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

    • Respons Berhasil (200 OK):

      {
  "count": 0
}

  • Mendapatkan VM Serentak Maksimum: Menampilkan jumlah maksimum VM yang berjalan serentak yang dikonfigurasi.

    • Endpoint:

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

    • Respons berhasil (200 OK):

      {
  "max_running_vms": 5
}