部署指南

這個平台需要您將基礎架構部署至 Google Cloud 專案。

取得原始碼

Cloud Telemetry Simulation 平台的原始碼位於 sdv.googlesource.com，您必須按照「存取工具存放區」一文的說明進行驗證。

如要存取原始碼，請複製 Cloud Telemetry Simulation 存放區：

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

必要條件

如要部署平台，請確認符合下列必要條件：

• 已啟用計費功能的 Google Cloud 專案。
• 網頁範例安全性：部署網頁範例時，您必須在 Google Cloud 「API 和服務」>「憑證」中設定 OAuth 2.0 用戶端 ID，確保 App Engine 應用程式安全無虞，並限制只有授權的 Google 帳戶才能存取。
• 軟體定義車輛 (SDV) 建構構件：您必須擁有自行編譯的 SDV 映像檔構件。這個存放區未提供這些檔案。
  • cvd-host_package.tar.gz
  • sdv_core_cf-img-<version>.zip
• 權限：執行 Terraform 的使用者或服務帳戶必須具備足夠權限，才能建立設定中定義的資源 (例如專案編輯者，或是具備 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)"
   

   雲端遙測模擬平台已部署完畢，可接受模擬要求。

操作和疑難排解

這項解決方案可讓您使用 Google Cloud 內建的觀測工具。只有在每個要求和模擬執行期間，才會消耗運算資源。

成本管理

這項架構採用無伺服器和暫時性資源，因此具有成本效益。費用主要來自：

• Compute Engine：模擬 VM 執行時數的費用。 使用 Spot VM 可大幅降低這項費用。
• Cloud Functions：每次叫用都會產生費用。
• Cloud Storage：儲存輸入和輸出檔案及記錄時會產生費用。
• Firestore：讀取、寫入和資料儲存空間都會產生費用。

觀測能力

所有元件都與 Google Cloud 作業套件整合。

• Logs Explorer：這是主要的疑難排解工具。您可以 依資源篩選記錄：
  • Cloud Functions：檢查 receive-request 或 schedule-simulation 函式的記錄，以偵錯自動化調度管理問題。
  • Compute Engine：檢查 VM 執行個體記錄，瞭解啟動或關機問題。
  • 模擬代理程式：在 Docker 容器中執行的代理程式會將記錄轉送至 Logs Explorer。依 VM 執行個體名稱篩選，即可查看詳細的模擬進度。
• Cloud Storage：模擬完成後，Cuttlefish 裝置的 logcat 和 bugreport 檔案會上傳至 Cloud Storage bucket 中的模擬輸出目錄，深入瞭解 Android 環境的行為。

服務帳戶

Terraform 會建立多個服務帳戶，以啟用安全且具備最低權限的環境。主要服務帳戶包括：

1. 執行身分 (VM)：

   • simulation-agent：
     • 附加至：執行模擬作業的 Compute Engine VM。
     • 角色：允許 VM 上傳結果並發出完成信號。
     • 權限：
       • roles/storage.objectUser：讀取輸入內容，並將構件 (記錄、報表) 上傳至 Cloud Storage。
       • roles/run.invoker：驗證並叫用 finish-simulation 函式。

2. 自動化調度管理身分 (函式)：

   • read-simulations-function：
     • 附加至：read-simulation Cloud Function。
     • 權限：
       • roles/datastore.user：讀取 Firestore 中的模擬和執行中 VM 記錄。

   • 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：在執行完成後刪除 VM。 - 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，可觸發清除邏輯。

管理這些服務帳戶的身分與存取權管理政策，是控管系統內存取權和權限的主要方式。