Usar o agente do EC2Launch v2 para realizar tarefas durante a execução da instância EC2 Windows - Amazon Elastic Compute Cloud
Conceitos do EC2Launch v2Visão geral da tarefa do EC2Launch v2Estrutura de diretório do EC2Launch v2Telemetria

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 que são executadas em AMIs da AWS com o Windows Server 2022 incluem o agente de execuçã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.

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). Os binários de serviço ficam localizados no diretório %ProgramFiles%\Amazon\EC2Launch.

O EC2Launch v2 publica logs de eventos do Windows para ajudá-lo a solucionar erros e definir gatilhos. Para ter mais informações, consulte Logs de eventos do Windows.

O agente do EC2Launch v2 é compatível com as seguintes versões do sistema operacional (SO) do Windows Server abaixo:

Versões compatíveis do SO

  • Windows Server 2022

  • Windows Server 2019 (canal de manutenção de longo prazo e canal semestral)

  • Windows Server 2016

Conceitos do EC2Launch v2

É útil entender os conceitos a seguir ao considerar o EC2Launch v2.

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. Para obter o esquema e os detalhes de configuração da tarefa, consulte Configuração de tarefas do EC2Launch v2.

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.

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.

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.

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. Você pode especificar uma frequência para as tarefas executeScript.

Você verá as seguintes frequências no Configuração de tarefas do EC2Launch v2.

  • 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

    • O EC2Launch.exe run é invocado

agent-config

O agent-config é 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.

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, consulteComo o Amazon EC2 lida com os dados dos usuários para instâncias do Windows.

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.

  • 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.

  • 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 do serviço (agent.log), o console (console.log), a performance (bench.log), os erros (err.log) e a telemetria (telemetry.log) são armazenados neste diretório. Os arquivos de log são anexados a execuções subsequentes do serviço.

  • 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.0.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 pelo:

2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsUserDataScheduledPerBoot=true
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandCode=1
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandErrorCode=5
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallCode=2
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallErrorCode=0

A telemetria está habilitada por padrão. É possível desativar a coleta de telemetria a qualquer momento. Se a telemetria estiver ativada, o EC2Launch v2 enviará dados de telemetria sem notificações adicionais do cliente.

Visibilidade de telemetria

Quando a telemetria está habilitada, ela aparece na saída do console do Amazon EC2 da seguinte maneira:

2021/07/15 21:44:12Z: Telemetry: <Data>
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, 

msiexec /i ".\AmazonEC2Launch.msi" Remove="Telemetry" /q
Mais tópicos do EC2Launch v2