部署指南

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

访问源代码

Cloud Telemetry Simulation 平台的源代码托管在 GitHub 上， 位于 aaos-sdv-telemetry-simulator 中。

前提条件

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

• 已启用结算功能 的 Google Cloud 项目。
• Web 演示安全性： 如果您部署 Web 演示，则必须在 Google Cloud API 和服务 > 凭据 中配置 OAuth 2.0 客户端 ID ，以保护 App Engine 应用并限制对已获授权的 Google 账号的访问。
• 软件定义型车辆 (SDV) 构建工件： 您必须拥有自己的已编译 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 后端： 创建一个文件，以指定 Terraform 在 Cloud Storage 中存储其状态文件的位置。使用以下语法为文件命名：

   environments/ENVIRONMENT/backend.hcl
   

   # 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 虚拟机上运行模拟。您可以使用 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. 执行身份 (VM)：

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

2. 编排身份（函数）：

   • read-simulations-function：
     • 关联到： read-simulation Cloud Function。
     • 权限：
       • roles/datastore.user：读取 Firestore 中的模拟和运行虚拟机记录。

   • receive-request-function：

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

   • scheduler-function：

     • 关联到： schedule-simulation Cloud Function。

     • 权限：

       -   `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 Function。
     • 权限： - roles/compute.instanceAdmin.v1：在执行完成后删除虚拟机。 - roles/datastore.user：将模拟状态更新为 COMPLETED 或 FAILED。

   • delete-simulation-function：

     • 关联到： delete-simulation Cloud Function。
     • 权限： - 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 政策是控制系统中访问权限的主要方式。