部署指南

此平台要求您将基础架构部署到 Google Cloud 项目中。

获取源代码

Cloud Telemetry Simulation 平台的源代码托管在 sdv.googlesource.com 上，需要进行身份验证，如访问工具代码库中所述。

如需访问源代码，请克隆 Cloud Telemetry Simulation 代码库：

git clone https://sdv.googlesource.com/external/cloud_telemetry_simulation-external

前提条件

如需部署平台，请确保满足以下前提条件：

• 启用了结算功能的 Google Cloud 项目。
• Web 演示版安全性：如果您部署 Web 演示版，则必须在 Google Cloud API 和服务 > 凭据中配置 OAuth 2.0 客户端 ID，以保护 App Engine 应用并限制对授权的 Google 账号的访问。
• 软件定义型汽车 (SDV) build 工件：您必须拥有自己的已编译 SDV 映像工件。此代码库中未提供这些文件。
  • cvd-host_package.tar.gz
  • sdv_core_cf-img-<version>.zip
• 权限：运行 Terraform 的用户或服务账号必须拥有足够的权限来创建配置中定义的资源（例如，项目 Editor，或具有 Compute Engine、Cloud Functions、Identity and Access Management、Cloud Storage 和其他必要服务权限的自定义角色）。
• 工具：
  • Google Cloud CLI (gcloud CLI)
  • Terraform（使用代码库中的版本）
  • Docker
  • Go（用于代码库中编排器函数的版本）

部署 Google Cloud 基础架构

部署模拟平台主要涉及两个步骤：使用 Terraform 将核心基础架构部署到 Google Cloud，以及构建模拟代理 Docker 映像并将其推送到 Artifact Registry。本部分将引导您完成基础架构部署。

输入以下变量的值，以更新此页面上的代码段：

1. 配置 Terraform 后端：创建一个名为 environments/ENVIRONMENT/backend.hcl 的文件，以指定 Terraform 在 Cloud Storage 中存储其状态文件的位置。

   # environments/ENVIRONMENT/backend.hcl
   bucket = "TF_BUCKET_NAME"
   prefix = "sdv-telemetry-simulation"
   

2. 配置项目变量：创建一个名为 environments/ ENVIRONMENT/variables.tfvars 的文件，其中包含项目的详细信息。

   # environments/ENVIRONMENT/variables.tfvars
   project_id       = "PROJECT_ID"
   default_region   = "REGION"
   default_zone     = "ZONE"
   agent_docker_image = "REGION-docker.pkg.dev/PROJECT_ID/sim-agents/simulation-agent"
       # Security: Map logical tags to SHA256 digests
   
   # Security: Map logical tags to SHA256 digests (optional)
   image_fingerprints = {
   "latest" = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
   "stable" = "sha256:88d4266fd4e6338d13b845fcf289579d209c897823b9217da3e161936f031589"
   }
   
   # Parallel Execution Limit (Default: 5)
   max_concurrent_simulations = 5
   

3. 应用 Terraform 配置：前往 infrastructure 目录，然后初始化并应用配置：

   # Initialize Terraform with your backend configuration
   terraform init -backend-config=environments/ENVIRONMENT/backend.hcl
   
   # (Optional) Preview the changes
   terraform plan --var-file=environments/ENVIRONMENT/variables.tfvars
   
   # Apply the changes to deploy the infrastructure
   terraform apply --var-file=environments/ENVIRONMENT/variables.tfvars
   

构建并推送模拟代理映像

模拟代理在 Compute Engine 虚拟机 (VM) 上运行模拟。您可以使用 SDV 制品构建它，并将其推送到 Artifact Registry。

如需构建并推送模拟代理映像，请执行以下操作：

1. 放置制品：将 cvd-host_package.tar.gz 和 sdv_core_cf-img-<version>.zip 文件复制到 simulation-agent/sdv-image-resources/ 目录中。

2. 构建并推送：前往 simulation-agent 目录，然后构建并推送映像。将映像路径替换为您在 variables.tfvars 文件中配置的路径。

   # Example using the path from the .tfvars example above
   export AGENT_IMAGE="REGION-docker.pkg.dev/PROJECT_ID/sim-agents/simulation-agent:latest"
   
   # Build the image
   docker build -t $AGENT_IMAGE .
   
   # Push the image to Artifact Registry
   docker push $AGENT_IMAGE
   

3. 更新指纹：推送新映像后，您可能需要获取其 SHA256 摘要并更新 variables.tfvars 文件中的 image_fingerprints 映射，然后重新运行 terraform apply。

   # Get the digest using gcloud
   gcloud container images describe $AGENT_IMAGE --format="value(image_summary.digest)"
   

   您的 Cloud Telemetry Simulation 平台已部署，可以接受模拟请求。

运维和问题排查

借助此解决方案，您可以使用 Google Cloud 内置的可观测性工具。它仅在每次请求和模拟执行期间消耗计算资源。

费用管理

该架构旨在通过使用无服务器资源和临时资源来提高成本效益。费用主要取决于：

• Compute Engine：按模拟虚拟机运行的时间计费。 使用 Spot 虚拟机可显著降低此费用。
• Cloud Functions：按每次调用收费。
• Cloud Storage：存储输入和输出文件以及日志时会产生费用。
• Firestore：按读取、写入和数据存储量收费。

可观测性

所有组件都与 Google Cloud 的运维套件集成。

• Logs Explorer：这是进行问题排查的主要工具。您可以按资源过滤日志：
  • Cloud Functions：检查 receive-request 或 schedule-simulation 函数的日志，以调试编排问题。
  • Compute Engine：检查虚拟机实例日志，了解启动或关闭问题。
  • 模拟代理：在 Docker 容器内运行的代理将其日志转发到 Logs Explorer。按虚拟机实例名称过滤，以查看详细的模拟进度。
• Cloud Storage：对于已完成的模拟，Cuttlefish 设备中的 logcat 和 bugreport 文件会上传到 Cloud Storage 存储分区中模拟的输出目录，从而深入了解 Android 环境的行为。

服务账号

Terraform 会创建多个服务账号，以实现安全且最低权限的环境。主要服务账号包括：

1. 执行身份（虚拟机）：

   • simulation-agent：
     • 附加到：运行模拟的 Compute Engine 虚拟机。
     • 角色：允许虚拟机上传结果并发出完成信号。
     • 权限：
       • roles/storage.objectUser：读取输入并将制品（日志、报告）上传到 Cloud Storage。
       • roles/run.invoker：对 finish-simulation 函数进行身份验证并调用该函数。

2. 编排身份（函数）：

   • read-simulations-function：
     • 附加到：read-simulation Cloud Functions 函数。
     • 权限：
       • roles/datastore.user：读取 Firestore 中的模拟记录和正在运行的虚拟机记录。

   • receive-request-function：

     • 附加到：receive-request Cloud Functions 函数。
     • 权限：
       • roles/datastore.user：在 Firestore 中创建新的 PENDING 模拟记录。
       • roles/storage.objectUser：验证 Cloud Storage 中是否存在输入文件。

   • scheduler-function：

     • 附加到：schedule-simulation Cloud Functions 函数。

     • 权限：

       -   `roles/pubsub.subscriber`: Pulls messages from the simulation
           queue.
       -   `roles/datastore.user`: Performs atomic reads and writes to the
           `running-vms` counter.
       -   `roles/compute.instanceAdmin.v1`: Creates and starts Compute
           Engine VMs.
       -   `roles/iam.serviceAccountUser`: This permission allows this
           function to assign the `simulation-agent` service account to the
           VMs it creates.
       

   • simulation-finisher-function：

     • 附加到：finish-simulation Cloud Functions 函数。
     • 权限： - roles/compute.instanceAdmin.v1：在执行完成后删除虚拟机。 - roles/datastore.user：将模拟状态更新为 COMPLETED 或 FAILED。

   • delete-simulation-function：

     • 附加到：delete-simulation Cloud Functions 函数。
     • 权限： - roles/compute.instanceAdmin.v1：在取消期间强制删除虚拟机。 - roles/datastore.user：更新已取消作业的状态。

3. 触发身份：

   • scheduler-trigger：

     • 使用方：Eventarc（事件）和 Cloud Scheduler 触发器。
     • 权限： roles/eventarc.eventReceiver 和 roles/run.invoker，用于触发编排器函数。

   • cleanup-scheduler：

     • 用途：用于清理的 Cloud Scheduler Cron 作业。
     • 权限： roles/run.invoker 以触发清理逻辑。

管理这些服务账号的 Identity and Access Management 政策是控制系统内访问权限和许可的主要方式。