Руководство пользователя

Вы можете запустить симуляцию, используя предоставленную веб-демонстрацию или напрямую вызвав REST API.

Входные и выходные данные

Входные и выходные файлы используют сегмент Cloud Storage из настройки Terraform.

В каталоге входных данных должны быть файлы metrics_config.zip и publisher_config.zip. Вы можете указать путь к нему.

Сегмент для выходных данных содержит каталог simulations, в котором хранятся симуляции, упорядоченные по идентификаторам. Каждый каталог симуляции содержит папку inputs со скопированными входными файлами и папку outputs. Папка outputs содержит отчет об ошибке, файл logcat и сгенерированные файлы симулятора.

Использовать веб-демо

Платформа включает веб-приложение на основе Flutter для демонстрационных целей, которое позволяет просматривать, создавать симуляции и управлять ими. Рекомендуем создать собственный пользовательский интерфейс, соответствующий вашим потребностям.

Демонстрационное приложение развернуто в App Engine и требует входа в аккаунт Google. Для защиты используется идентификатор клиента OAuth 2.0, настроенный в облачном проекте Google Cloud. У аккаунта, в который выполнен вход, должны быть разрешения IAM на вызов развернутых функций Cloud Functions. Инструкции о том, как предоставить аккаунтам пользователей необходимые разрешения, например роль Cloud Functions Invoker (roles/cloudfunctions.invoker), можно найти в статье Авторизация доступа с помощью IAM.

Действия пользователя

  1. Войдите в аккаунт Google, используя аутентификацию OAuth 2.0.
  2. Просматривать симуляции на главной странице, где перечислены все симуляции, запрашивая базу данных Firestore, которая содержит всю информацию о выполнении.
  3. Чтобы запланировать новую имитированную атаку, нажмите на командную кнопку + в правом нижнем углу. Вы указываете несколько параметров, включая путь ввода, идентификатор сборки и тип экземпляра. Подробнее о том, как создать симуляцию…
  4. Проверьте статус моделирования в списке. Он может быть, например, таким: PENDING, RUNNING, COMPLETED.
  5. После завершения моделирования просмотрите созданные отчеты и артефакты. Входные файлы, выходные отчеты, журналы, Logcat и отчеты об ошибках хранятся в Cloud Storage.
  6. При необходимости отмените запланированную или выполняющуюся симуляцию.

Использование API

Для автоматизации и интеграции с другими системами можно использовать REST API.

Плейсхолдер CLOUD_FUNCTION_URL, используемый в разделе аутентификации и в определениях конечных точек, относится к базовому URL вызываемой функции Cloud Functions. URL функций можно найти в консоли Google Cloud на странице Cloud Functions. URL каждой функции указан на вкладке Trigger (Триггер) на странице Function details (Сведения о функции). Эти URL также можно найти в выходных данных Terraform, которые выводятся после выполнения команды apply.

Аутентификация

Все запросы к API должны быть аутентифицированы с помощью токена, подтверждающего личность вызывающего абонента. У идентификатора (пользователя или сервисного аккаунта) должны быть разрешения Cloud Functions Invoker для целевой функции.

  1. Вызов пользователем (локальный и CLI). При вызове API с локального компьютера или из среды, не относящейся к Google Cloud, необходимо использовать токен идентификации, выданный Google для аккаунта пользователя.

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

  2. Вызов сервисного аккаунта (в Google Cloud). При вызове API из ресурса Google Cloud (например, виртуальной машины Compute Engine, другой функции Cloud Functions или кластера Kubernetes) используйте идентификационные данные прикрепленного к ресурсу сервисного аккаунта. Токен должен быть получен с сервера метаданных ресурса.

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

Включите полученный токен в заголовок Authorization ваших запросов в качестве токена Bearer.

Конечные точки

Пользовательские конечные точки стека Cloud Telemetry Simulation позволяют создавать и удалять симуляции, а также считывать информацию о них из базы данных.

Создать симуляцию

Эта конечная точка создает новый запрос на моделирование и планирует его выполнение.

  • Конечная точка: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-requests

  • Тело запроса:

    {
  "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 (строка) – тег образа Docker агента, который нужно использовать, например latest.

    • file_path (строка) – путь к папке, содержащей metrics_config.zip и publisher_config.zip, в сегменте GCS.

    • instance_type (строка) – тип машины Compute Engine. Этот тип должен поддерживать вложенную виртуализацию, например серии n1, n2 или t2d. Подробную информацию можно найти в обзоре вложенной виртуализации.

    • owner (строка) – адрес электронной почты пользователя, который инициировал симуляцию.

    • max_simulation_time (целое число) – максимальное время в секундах, в течение которого выполняется симуляция.

    • max_report_count (целое число) – количество отчетов телеметрии, после которого симуляция завершается.

  • Ответ об успешном выполнении (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Как удалить симуляцию

Эта конечная точка отменяет ожидающую или выполняющуюся симуляцию и удаляет связанные с ней ресурсы.

  • Конечная точка: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Заголовки:
    • Content-Type: application/json

  • Тело запроса:

    { "id": "sim-a1b2c3d4e5f6" }

  • Ответ об успешном выполнении (200 OK): обычное текстовое сообщение (Request accepted and is being processed).

Как читать данные моделирования

Чтобы прочитать данные симуляции, вы можете взаимодействовать с функцией simulation-reader. Эти конечные точки используют метод GET для получения истории, статуса и конфигурации системы.

Как получить список симуляций

Возвращает разбитый на страницы список симуляций с поддержкой фильтрации и сортировки.

  • Конечная точка: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Параметры запроса (необязательные):

    • status (строка): фильтр по статусу симуляции (running, Simulation request received, cancelled, completed или failed).
    • owner (строка): фильтр по адресу электронной почты владельца.
    • sort_by (строка) – поле, по которому выполняется сортировка (received_at, status_updated_at, started_at). По умолчанию используется received_at.
    • sort_order (строка) – порядок сортировки: asc или desc. Значение по умолчанию – desc.
    • page_size (целое число) – количество результатов на странице. Значение по умолчанию – 20.
    • page_token (строка) – токен для получения следующей страницы результатов.

  • Пример запроса:

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

  • Ответ об успешном выполнении (200 OK):

    • Возвращает объект JSON, содержащий массив симуляций и необязательный параметр 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"
}
Как получить определенную симуляцию

Получает полные сведения об определенной симуляции по ее идентификатору.

  • Конечная точка:

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

  • Успешный ответ (200 OK). Возвращает объект JSON, содержащий сведения о запрошенном моделировании.

    {
  "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
}
Получение показателей и конфигурации системы

Эти конечные точки предоставляют информацию о текущей нагрузке и конфигурации инфраструктуры симуляции.

  • Get running count (Получить количество запущенных симуляций). Возвращает количество запущенных симуляций.

    • Конечная точка:

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

    • Ответ об успешном выполнении (200 OK):

      {
  "count": 0
}

  • Получить максимальное количество одновременно работающих виртуальных машин. Возвращает настроенное максимальное количество одновременно работающих виртуальных машин.

    • Конечная точка:

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

    • Ответ об успешном выполнении (200 OK):

      {
  "max_running_vms": 5
}