Em 2026, para nos alinharmos ao nosso modelo de desenvolvimento estável e garantir a estabilidade da plataforma para o ecossistema, vamos publicar o código-fonte no AOSP no segundo e quarto trimestres. Para criar e contribuir com o AOSP, use android-latest-release. A ramificação de manifesto android-latest-release sempre vai referenciar a versão mais recente enviada ao AOSP. Para mais informações, consulte Mudanças no AOSP.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Guia de implantação

A plataforma de simulação de telemetria do Cloud exige que você implante a infraestrutura no projeto do Google Cloud.

Acessar o código-fonte

O código-fonte da plataforma de simulação de telemetria do Cloud está hospedado no GitHub, em aaos-sdv-telemetry-simulator.

Pré-requisitos

Para implantar a plataforma, verifique se você atende aos seguintes pré-requisitos:

Um projeto na nuvem do Google Cloud com o faturamento ativado.
Segurança da demonstração na Web: se você implantar a demonstração na Web, configure um ID do cliente OAuth 2.0 em APIs e serviços > Credenciais do Google Cloud para proteger o aplicativo do App Engine e restringir o acesso a Contas do Google autorizadas.
Artefatos de build de veículo definido por software (SDV): você precisa ter seus próprios artefatos de imagem de SDV compilados. Eles não são fornecidos neste repositório.
- cvd-host_package.tar.gz
- sdv_core_cf-img-<version>.zip
Permissões: o usuário ou a conta de serviço que executa o Terraform precisa ter permissões suficientes para criar os recursos definidos na configuração (por exemplo, Editor do projeto ou um papel personalizado com permissões para o Compute Engine, o Cloud Functions, o Identity and Access Management, o Cloud Storage e outros serviços necessários).
Ferramentas:
- CLI do Google Cloud (gcloud CLI)
- Terraform (versão usada no repositório)
- Docker
- Go (versão usada para funções de orquestrador no repositório)

Implantar a infraestrutura em nuvem do Google Cloud

A implantação da plataforma de simulação envolve duas etapas principais: usar o Terraform para implantar a infraestrutura principal no Google Cloud e criar e enviar a imagem Docker do agente de simulação para o Artifact Registry. Esta seção orienta você na implantação da infraestrutura.

Insira valores para as seguintes variáveis para atualizar os snippets de código nesta página:

Configure o back-end do Terraform: crie um arquivo para especificar onde o Terraform armazena o arquivo de estado no Cloud Storage. Nomeie o arquivo usando esta sintaxe:
```
environments/ENVIRONMENT/backend.hcl
```
```
# environments/ENVIRONMENT/backend.hcl
bucket = "TF_BUCKET_NAME"
prefix = "sdv-telemetry-simulation"
```

Configurar variáveis do projeto: crie um arquivo com os detalhes do seu projeto. Nomeie o arquivo usando esta sintaxe:

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)
supported_agent_builds = {
"latest" = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"stable" = "sha256:88d4266fd4e6338d13b845fcf289579d209c897823b9217da3e161936f031589"
}

# Parallel Execution Limit (Default: 5)
max_vm_count = 5

Aplique a configuração do Terraform: acesse o diretório infrastructure, inicialize e aplique a configuração:

# 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

Criar e enviar a imagem do agente de simulação

O agente de simulação executa a simulação na máquina virtual (VM) do Compute Engine. Você a cria com seus artefatos de SDV e a envia para o Artifact Registry.

Para criar e enviar a imagem do agente de simulação:

Colocar artefatos: copie os arquivos cvd-host_package.tar.gz e sdv_core_cf-img-<version>.zip para o diretório simulation-agent/sdv-image-resources/.

Criar e enviar: navegue até o diretório simulation-agent, crie e envie a imagem. Substitua o caminho da imagem pelo que você configurou no arquivo 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

Atualizar impressões digitais: depois de enviar uma nova imagem, talvez seja necessário receber o resumo SHA256 dela e atualizar o mapa supported_agent_builds no arquivo variables.tfvars. Em seguida, execute novamente terraform apply.
```
# Get the digest using gcloud
gcloud artifacts docker images describe $AGENT_IMAGE --format="value(image_summary.digest)"
```
Sua plataforma de simulação de telemetria do Cloud foi implantada e está pronta para aceitar solicitações de simulação.

Operações e solução de problemas

Essa solução permite usar as ferramentas integradas do Google Cloud para observabilidade. Ele consome recursos de computação apenas por solicitação e durante a execução da simulação.

Gerenciamento de custo

A arquitetura foi projetada para ser econômica usando recursos sem servidor e temporários. Os custos são determinados principalmente por:

Compute Engine: faturado pelo tempo em que as VMs de simulação estão em execução. O uso de VMs spot pode reduzir significativamente esse custo.
Cloud Functions: faturado por invocação.
Cloud Storage: faturado pelo armazenamento de arquivos e registros de entrada e saída.
Firestore: faturado por leituras, gravações e armazenamento de dados.

Observabilidade

Todos os componentes são integrados ao pacote de operações do Google Cloud.

Análise de registros: é a principal ferramenta para solucionar problemas. É possível filtrar registros por recurso:
- Cloud Functions: verifique os registros das funções receive-request ou schedule-simulation para depurar problemas de orquestração.
- Compute Engine: verifique os registros da instância de VM para identificar problemas de inicialização ou encerramento.
- Agente de simulação: o agente em execução no contêiner do Docker encaminha os registros para a Análise de Registros. Filtre pelo nome da instância de VM para ver o progresso detalhado da simulação.
Cloud Storage: para simulações concluídas, os arquivos logcat e bugreport do dispositivo Cuttlefish são enviados para o diretório de saída da simulação no bucket do Cloud Storage, fornecendo insights detalhados sobre o comportamento do ambiente do Android.

Contas de serviço

O Terraform cria várias contas de serviço para permitir um ambiente seguro e de privilégio mínimo. As principais contas de serviço incluem:

Identidade de execução (VM):
- simulation-agent:
  - Anexado a: as VMs do Compute Engine que executam a simulação.
  - Papel: permite que a VM faça upload de resultados e sinalize a conclusão.
  - Permissões:
    - roles/storage.objectUser: lê entradas e faz upload de artefatos (registros, relatórios) para o Cloud Storage.
    - roles/run.invoker: autentica e invoca a função finish-simulation.
Identidades de orquestração (funções):
- read-simulations-function:
  - Anexado a: a função do Cloud read-simulation.
  - Permissões:
    - roles/datastore.user: lê registros de simulação e de VM em execução no Firestore.
- receive-request-function:
  - Anexado a: a função do Cloud receive-request.
  - Permissões:
    - roles/datastore.user: cria novos registros de simulação do PENDING no Firestore.
    - roles/storage.objectUser: verifica a existência de arquivos de entrada no Cloud Storage.
- scheduler-function:
  - Anexado a: a função do Cloud schedule-simulation.
  - Permissões:
    - roles/pubsub.subscriber: extrai mensagens da fila de simulação.
    - roles/datastore.user: realiza leituras e gravações atômicas no contador running-vms.
    - roles/compute.instanceAdmin.v1: cria e inicia VMs do Compute Engine.
    - roles/iam.serviceAccountUser: permite que essa função atribua a conta de serviço simulation-agent às VMs que ela cria.
- simulation-finisher-function:
  - Anexado a: a função do Cloud finish-simulation.
  - Permissões:
    - roles/compute.instanceAdmin.v1: exclui a VM após a conclusão da execução.
    - roles/datastore.user: atualiza o status da simulação para COMPLETED ou FAILED.
- delete-simulation-function:
  - Anexado a: a função do Cloud delete-simulation.
  - Permissões:
    - roles/compute.instanceAdmin.v1: exclui máquinas virtuais à força durante o cancelamento.
    - roles/datastore.user: atualiza o status dos jobs cancelados.
Identidades do gatilho:
- scheduler-trigger:
  - Usado por: gatilhos do Eventarc (eventos) e do Cloud Scheduler.
  - Permissões: roles/eventarc.eventReceiver e roles/run.invoker para acionar as funções do orquestrador.
- cleanup-scheduler:
  - Usado por: o cron job do Cloud Scheduler para limpeza.
  - Permissões: roles/run.invoker para acionar a lógica de limpeza.

Gerenciar as políticas do Identity and Access Management para essas contas de serviço é a principal maneira de controlar o acesso e as permissões no sistema.