部署指南

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

访问源代码

云端遥测模拟平台的源代码托管在 GitHub 的 aaos-sdv-telemetry-simulator 中。

前提条件

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

• 已启用结算功能的 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 的用户或服务账号必须具有足够的权限，才能创建配置中定义的资源（例如，Project 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
   

   注意 ：为防止执行未经授权的映像，请定义 supported_agent_builds 映射。系统会根据此映射验证用户请求中的 build_id。

   # 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)
   supported_agent_builds = {
   "latest" = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
   "stable" = "sha256:88d4266fd4e6338d13b845fcf289579d209c897823b9217da3e161936f031589"
   }
   
   # Parallel Execution Limit (Default: 5)
   max_vm_count = 5
   

   注意 ：agent_docker_image 路径必须与您在下一部分中构建和推送的映像匹配。

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 文件中的 supported_agent_builds 映射，然后重新运行 terraform apply。

   # Get the digest using gcloud
   gcloud artifacts docker 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 中的模拟和 running-vm 记录。

   • 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 政策是控制系统内访问权限和权限的主要方式。