# Usar o agente do EC2Launch v2 para realizar tarefas durante a execução da instância EC2 Windows Todas as instâncias compatíveis do Amazon EC2 iniciadas em AMIs da AWS com o Windows Server 2022 e o Windows Server 2025 incluem o agente de inicialização do EC2Launch v2 (`EC2Launch.exe`) por padrão. Também fornecemos AMIs do Windows Server 2016 e 2019 com o EC2Launch v2 instalado como o agente padrão de execução. Essas AMIs são fornecidas além das AMIs do Windows Server 2016 e 2019 que incluem o EC2Launch v1. É possível procurar por AMIs do Windows que incluam o EC2Launch v2 por padrão inserindo o seguinte prefixo em sua pesquisa na página **AMIs** no console do Amazon EC2: `EC2LaunchV2-Windows_Server-*`. Para comparar os recursos da versão do agente de inicialização, consulte [Comparação entre os agentes de inicialização do Amazon EC2](configure-launch-agents.md#ec2launch-agent-compare). O EC2Launch v2 executa tarefas durante o startup da instância e é executado se uma instância for interrompida e iniciada posteriormente, ou reiniciada. O EC2Launch v2 também pode executar tarefas sob demanda. Algumas dessas tarefas são automaticamente habilitadas, enquanto outras precisam ser habilitadas manualmente. O serviço EC2Launch v2 é compatível com todos os recursos EC2Config e EC2Launch. Esse serviço usa um arquivo de configuração para controlar sua operação. É possível atualizar o arquivo de configuração usando uma ferramenta gráfica ou editando-o diretamente como único arquivo .yml (`agent-config.yml`). Para obter mais informações sobre localizações de arquivos, consulte [Estrutura de diretório do EC2Launch v2](#ec2launch-v2-directory). O EC2Launch v2 publica logs de eventos do Windows para ajudá-lo a solucionar erros e definir gatilhos. Para obter mais informações, consulte [Logs de eventos do Windows](ec2launchv2-troubleshooting.md#ec2launchv2-windows-event-logs). **Versões compatíveis do SO** O agente do EC2Launch v2 é compatível com as seguintes versões do sistema operacional (SO) do Windows Server abaixo: + Windows Server 2025 + Windows Server 2022 + Windows Server 2019 (canal de manutenção de longo prazo e canal semestral) + Windows Server 2016 **Tarefas que são executadas por padrão** Por padrão, o agente EC2Launch v2 executa as tarefas apresentadas a seguir uma única vez durante a primeira inicialização da instância. As tarefas são organizadas de acordo com a ordem em que são executadas durante a fase de inicialização. Fase de `Boot` + extendRootPartition Fase de `PreReady` + activateWindows + setDnsSuffix + setAdminAccount + setWallpaper Fase de `PostReady` + startSsm ## Conceitos do EC2Launch v2 É útil entender os conceitos a seguir ao considerar o EC2Launch v2. **agent-config** `agent-config`O é um arquivo localizado na pasta de configuração do EC2Launch v2. Ele inclui a configuração para os estágios de inicialização, rede, PreReady e PostReady. Este arquivo é usado para especificar a configuração de uma instância para tarefas que devem ser executadas quando a AMI é inicializada pela primeira vez ou em ocasiões posteriores. Por padrão, a instalação do EC2Launch v2 instala um arquivo `agent-config` que inclui configurações recomendadas usadas nas AMIs padrão do Amazon Windows. É possível atualizar o arquivo de configuração de modo a alterar a experiência de inicialização padrão para sua AMI especificada pelo EC2Launch v2. Para obter mais informações sobre localizações de arquivos, consulte [Estrutura de diretório do EC2Launch v2](#ec2launch-v2-directory). **Frequência** A frequência da tarefa determina quando as tarefas devem ser executadas, dependendo do contexto de inicialização. A maioria das tarefas tem apenas uma frequência permitida. É possível especificar uma frequência para as tarefas `executeScript`. Você verá as seguintes frequências no [Configuração de tarefas do EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-task-configuration). + Uma vez — a tarefa é executada uma vez, mediante a inicialização da AMI pela primeira vez (Sysprep concluído). + Sempre: a tarefa é executada toda vez que o agente de inicialização é executado. O agente de inicialização é executado quando: + uma instância inicia ou reinicia + o serviço EC2Launch é executado + `EC2Launch.exe run`O é invocado **Estágio** Um estágio é um agrupamento lógico de tarefas que o agente EC2Launch v2 executa. Algumas tarefas podem ser executadas apenas em um estágio específico. Outras podem ser executadas em vários estágios. Ao usar `agent-config.yml`, você deve especificar uma lista de estágios e uma lista das tarefas de cada estágio. O serviço executa as etapas nesta ordem: Etapa 1: Boot Etapa 2: Network Etapa 3: PreReady O Windows está pronto Após a conclusão do estágio PreReady, o serviço envia a mensagem `Windows is ready` para o console do Amazon EC2. Etapa 4: PostReady Os dados do usuário são executados durante o estágio *PostReady*. Algumas versões de script são executadas antes do estágio *PostReady* do arquivo `agent-config.yml` e outras depois, da seguinte forma: Antes do `agent-config.yml` + Dados de usuário em YAML versão 1.1 + Dados de usuário em XML Depois de `agent-config.yml` + Dados do usuário em YAML versão 1.0 (versão antiga para compatibilidade com versões anteriores) Para obter exemplos dos estágios e das tarefas, consulte [Exemplo: `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config). Ao usar dados do usuário, você deve especificar uma lista de tarefas para o agente de inicialização executar. O estágio está implícito. Para obter exemplos de tarefas, consulte [Exemplo: dados do usuário](ec2launch-v2-settings.md#ec2launch-v2-example-user-data). O EC2Launch v2 executa a lista de tarefas na ordem especificada em `agent-config.yml` e nos dados do usuário. Os estágios são executados sequencialmente. O próximo estágio começa após a conclusão do estágio anterior. As tarefas também são executadas sequencialmente. **Tarefa** É possível invocar uma tarefa para realizar uma ação em uma instância. É possível configurar tarefas no arquivo `agent-config.yml` ou por meio de dados do usuário. Para obter uma lista das tarefas disponíveis no EC2Launch v2, consulte [Tarefas do EC2Launch v2](#ec2launch-v2-tasks). Para obter o esquema e os detalhes de configuração da tarefa, consulte [Configuração de tarefas do EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-task-configuration). **Dados do usuário** Os dados do usuário são dados que podem ser configurados ao iniciar uma instância. É possível atualizar os dados do usuário para alterar de maneira dinâmica como as AMIs personalizadas ou AMIs de início rápido são configuradas. O EC2Launch v2 suporta 60 kB de comprimento de entrada de dados do usuário. Os dados do usuário incluem apenas o estágio do UserData e, portanto, são executados após o arquivo `agent-config`. É possível inserir dados do usuário ao executar uma instância usando o assistente de execução de instância ou pode modificar os dados do usuário no console do EC2. Para obter mais informações sobre como trabalhar com dados do usuário, consult [Como o Amazon EC2 lida com os dados dos usuários para instâncias do Windows](user-data.md#ec2-windows-user-data). ## Visão geral da tarefa do EC2Launch v2 O EC2Launch v2 pode executar as seguintes tarefas em cada inicialização: + Configurar papel de parede novo e opcionalmente personalizado que renderiza informações sobre a instância. + Definir os atributos para a conta de administrador criada na máquina local. + Adicionar sufixos DNS à lista de sufixos de pesquisa. Somente sufixos que ainda não existem são adicionados à lista. + Definir letras de unidade para quaisquer volumes adicionais e estendê-las para usar o espaço disponível. + Gravar arquivos da configuração no disco. + Executar scripts especificados no arquivo de configuração do EC2Launch v2 ou de `user-data`. Os scripts de `user-data` podem ser em texto simples ou compactados e fornecidos no formato base64. + Executar um programa com os argumentos fornecidos. + Definir o nome do computador. + Enviar informações de instância para o console do Amazon EC2. + Enviar a impressão digital do certificado RDP ao console do Amazon EC2. + Estenda dinamicamente a partição do sistema operacional para incluir qualquer espaço não particionado. + Executar dados do usuário. Para obter mais informações sobre como especificar os dados do usuário, consulte [Configuração de tarefas do EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-task-configuration). + Defina rotas estáticas não persistentes para alcançar o serviço de metadados e os servidores AWS KMS. + Definir partições que não sejam de inicialização como `mbr` ou `gpt`. + Iniciar o serviço Systems Manager após o Sysprep. + Otimizar as configurações do ENA. + Ativar o OpenSSH para versões posteriores do Windows. + Ativar os frames jumbo. + Defina o Sysprep para execução com o EC2Launch v2. + Publicar logs de eventos do Windows. ## Estrutura de diretório do EC2Launch v2 O EC2Launch v2 deve ser instalado nos seguintes diretórios: + Binários de serviço: `%ProgramFiles%\Amazon\EC2Launch` + Dados de serviço (configurações, arquivos de log e arquivos de estado): `%ProgramData%\Amazon\EC2Launch` **nota** Por padrão, o Windows oculta os arquivos e as pastas sob `C:\ProgramData`. Para visualizar os diretórios e arquivos do EC2Launch v2, digite o caminho no Windows Explorer ou altere as propriedades da pasta para os arquivos e as pastas ocultos. O diretório `%ProgramFiles%\Amazon\EC2Launch` contém binários e bibliotecas compatíveis. Ele inclui os seguintes subdiretórios: + `settings` + `EC2LaunchSettingsUI.exe`: interface de usuário para modificar o arquivo `agent-config.yml` + `YamlDotNet.dll`: DLL para oferecer suporte a algumas operações na interface do usuário + `tools` + `ebsnvme-id.exe`: ferramenta para examinar os metadados dos volumes do EBS na instância + `AWSAcpiSpcrReader.exe`: ferramenta para determinar a porta COM correta a ser usada + `EC2LaunchEventMessage.dll`: DLL para oferecer suporte ao registro de eventos do Windows para o EC2Launch + `service` + `EC2LaunchService.exe`: serviço do Windows executável que é iniciado quando o agente de inicialização é executado como um serviço + `EC2AgentTelemetry.dll`: DLL para dar suporte à telemetria do agente EC2 + `EC2Launch.exe`: executável principal do EC2Launch + `EC2LaunchAgentAttribution.txt`: atribuição para código usado dentro do EC2 Launch O diretório `%ProgramData%\Amazon\EC2Launch` contém os seguintes subdiretórios. Todos os dados produzidos pelo serviço, incluindo logs, configuração e estado, são armazenados neste diretório. + `config`: configuração O arquivo de configuração do serviço é armazenado neste diretório como `agent-config.yml`. Esse arquivo pode ser atualizado de modo a modificar, adicionar ou remover tarefas padrão executadas pelo serviço. A permissão para criar arquivos neste diretório é restrita à conta de administrador para evitar o escalonamento de privilégios. + `log`: logs de instância Os logs de serviço (`agent.log`), performance (`bench.log`) e telemetria (`telemetry.log`) são armazenados neste diretório. Quando `agent.log` atinge 1 MB de tamanho, ele é rotacionado automaticamente e um arquivo de backup é criado com um formato de carimbo de data/hora (por exemplo, `agent-2026-03-02T18-56-39.188.log`). Somente um arquivo de log de backup é mantido por vez. + `state`: dados de estado do serviço O estado usado pelo serviço para determinar quais tarefas devem ser executadas é armazenado aqui. Há um arquivo `.run-once` que indica se o serviço já foi executado após Sysprep (portanto, as tarefas com frequência de uma vez serão ignoradas na próxima execução). Esse subdiretório inclui `state.json` e `previous-state.json` para rastrear o status de cada tarefa. + `sysprep`: Sysprep Esse diretório contém arquivos usados para determinar quais operações executar pelo Sysprep ao criar uma AMI do Windows personalizada que pode ser reutilizada. + `wallpaper`: papel de parede As imagens de papel de parede são armazenadas nesse diretório. ## Telemetria Telemetria é informação adicional que ajuda a AWS a entender melhor suas necessidades, diagnosticar problemas e fornecer recursos para melhorar sua experiência com os Serviços da AWS. EC2Launch versão v2 `2.1.592` e, posteriormente, coletar telemetria, como métricas de uso e erros. Esses dados são coletados da instância do Amazon EC2 na qual o EC2Launch v2 é executado. Isso inclui todas as AMIs do Windows de propriedade da AWS. Os seguintes tipos de telemetria são coletados pelo EC2Launch v2: + **Informações de uso**: comandos do agente, método de instalação e frequência de execução programada. + **Erros e informações de diagnóstico**: códigos de erro da instalação do agente, códigos de erro de execução e pilhas de chamada como erro. Exemplos de dados coletados da versão 2.0.592 até a 2.1.1: ``` 2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsTelemetryEnabled=true 2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64 2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true 2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentCommandErrorCode=0 2025/07/18 22:38:52Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0 2025/07/18 22:38:52Z: EC2LaunchTelemetry: IpConflictDetectionCode=0 2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentErrorLocation=addroutes.go:49 ``` A partir da versão 2.2.63, os dados de telemetria do EC2 Agent são formatados como um objeto JSON: ``` {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... } ``` A telemetria está habilitada por padrão. É possível desativar a coleta de telemetria a qualquer momento. **Desativar telemetria em uma instância** Para desativar a telemetria para uma única instância, é possível definir uma variável de ambiente do sistema ou usar o MSI para modificar a instalação. Para desabilitar a telemetria definindo uma variável de ambiente do sistema, execute o seguinte comando como administrador: ``` setx /M EC2LAUNCH_TELEMETRY 0 ``` Para desabilitar a telemetria usando o MSI, execute o comando a seguir depois de [baixar o MSI](ec2launch-v2-install.md), ``` msiexec /i ".\AmazonEC2Launch.msi" Remove="Telemetry" /q ``` **Topics** + [Conceitos do EC2Launch v2](#ec2launch-v2-concepts) + [Visão geral da tarefa do EC2Launch v2](#ec2launch-v2-tasks) + [Estrutura de diretório do EC2Launch v2](#ec2launch-v2-directory) + [Telemetria](#ec2launch-v2-telemetry) + [Instalar a versão mais recente do EC2Launch v2](ec2launch-v2-install.md) + [Definição das configurações do EC2Launch v2 para instâncias do Windows](ec2launch-v2-settings.md) + [Definições de tarefas para tarefas de inicialização do EC2Launch v2](ec2launch-v2-task-definitions.md) + [Solucionar problemas com o agente do EC2Launch v2](ec2launchv2-troubleshooting.md) + [Históricos de versões do EC2Launch v2](ec2launchv2-versions.md)