Configurações do EC2Launch v2 - Amazon Elastic Compute Cloud
Alterar configurações usando a caixa de diálogo de configurações do EC2Launch v2Estrutura de diretório do EC2Launch v2Configurar o EC2Launch v2 com a CLIConfiguração de tarefas do EC2Launch v2Códigos de saída e reinicializações do EC2Launch v2EC2Launch v2 e Sysprep

Configurações do EC2Launch v2

Esta seção contém informações sobre como definir configurações para o EC2Launch v2.

Alterar configurações usando a caixa de diálogo de configurações do EC2Launch v2

O procedimento a seguir descreve como usar a caixa de diálogo de configurações do EC2Launch v2 para habilitar ou desabilitar configurações.

nota

Se você configurar de forma imprópria tarefas personalizadas no arquivo agent-config.yml e tentar abrir a caixa de diálogo de configurações Amazon EC2Launch, receberá um erro. Por obter um exemplo de esquema, consulte Exemplo: agent-config.yml.

  1. Execute e conecte-se à sua instância do Windows.

  2. No menu Iniciar, escolha Todos os programas e navegue até as Configurações do EC2Launch.

    Aplicação de configurações do EC2 Launch.

  3. Na guia Geral da caixa de diálogo Configurações do EC2Launch, é possível habilitar ou desabilitar as configurações a seguir.

    1. Definir o nome do computador

      Se essa configuração estiver habilitada (por padrão, ela fica desabilitada), o nome do host atual será comparado com o nome de host desejado em cada inicialização. Se os nomes de host não corresponderem, o nome do host será redefinido e o sistema, opcionalmente, reinicializa para ficar com o novo nome de host. Se um nome de host personalizado não for especificado, ele será gerado usando o endereço IPv4 privado formatado hexadecimal, por exemplo, ip-AC1F4E6. Para impedir a modificação de um nome de host existente, não habilite essa configuração.

    2. Estender o volume de inicialização

      Essa configuração amplia dinamicamente o Disk 0/Volume 0 para incluir qualquer espaço não particionado. Isso pode ser útil quando a instância for inicializada a partir de um volume do dispositivo raiz com tamanho personalizado.

    3. Definir a conta do administrador

      Quando habilitado, é possível definir os atributos de nome de usuário e senha para a conta de administrador criada em sua máquina local. Se esse recurso não estiver habilitado, uma conta de administrador não será criada no sistema após o Sysprep. Forneça uma senha em adminPassword somente se adminPasswordtype for Specify.

      Os tipos de senha são definidos da seguinte maneira:

      1. Random

        O EC2Launch gera uma senha e criptografa-a usando a chave de usuário. O sistema desativa essa configuração depois da execução da instância, portanto, essa senha persistirá se a instância for reinicializada ou parada e iniciada.

      2. Specify

        O EC2Launch usa a senha especificada em adminPassword. Se a senha não atender aos requisitos de sistema, o EC2Launch gera uma senha aleatória. A senha é armazenada em agent-config.yml como texto não criptografado e será excluída depois que Sysprep definir a senha do administrador. O EC2Launch criptografa a senha usando a chave de usuário.

      3. Do not set

        O EC2Launch usa a senha especificada no arquivo unattend.xml. Se você não especificar uma senha em unattend.xml, a conta de administrador será desativada.

    4. Iniciar o serviço SSM

      Quando selecionado, o serviço Systems Manager é habilitado para começar após o Sysprep. O EC2Launch v2 executa todas as tarefas descritas anteriormente e o SSM Agent processa recursos do Systems Manager, como Run Command e State Manager.

      É possível usar Run Command para atualizar suas instâncias existentes e usar a versão mais recente do serviço do EC2Launch v2 e do SSM Agent. Para obter mais informações, consulte Atualizar o SSM Agent usando o Run Command no Guia do usuário do AWS Systems Manager.

    5. Otimizar ENA

      Quando selecionadas, as configurações do ENA são definidas para garantir que as configurações Receive Side Scaling (Receber dimensionamento lateral) e Receive Queue Depth (Receber profundidade da fila) sejam otimizadas para a AWS. Para ter mais informações, consulte Configurar afinidade de CPU RSS.

    6. Habilitar SSH

      Essa configuração habilita o OpenSSH para versões posteriores do Windows a fim de permitir a administração remota do sistema.

    7. Ativar os frames jumbo

      Selecione para ativar frames jumbo. Os frames jumbo podem ter efeitos não intencionais sobre suas comunicações de rede, portanto, certifique-se de entender como eles afetarão seu sistema antes de ativá-los. Para obter mais informações sobre os frames jumbo, consulte Frames jumbo (9001 MTU).

    8. Preparar para imagens

      Selecione se deseja que sua instância do EC2 seja desligada com ou sem Sysprep. Quando quiser executar o Sysprep com o EC2Launch v2, escolha Shutdown with Sysprep (Desligar com Sysprep).

  4. Na guia Sufixo DNS, é possível selecionar se deseja adicionar uma lista de sufixos DNS para resolução DNS de servidores em execução no EC2, sem fornecer o nome de domínio totalmente qualificado. Os sufixos DNS podem conter as variáveis $REGION e $AZ. Somente sufixos que ainda não existem serão adicionados à lista.

    Aplicação de configurações do EC2 Launch.

  5. Na guia Papel de parede, você pode configurar o papel de parede da instância com uma imagem de fundo e especificar os detalhes da instância a serem exibidos no papel de parede. O Amazon EC2 gera os detalhes toda vez que você faz login.

    Você pode configurar o papel de parede com os seguintes controles.

    • Exibir detalhes da instância no papel de parede: essa caixa de seleção ativa ou desativa a exibição de detalhes da instância no papel de parede.

    • Caminho da imagem (.jpg): especifique o caminho até a imagem a ser usada como plano de fundo do papel de parede.

    • Selecionar atributos a serem exibidos no papel de parede: marque as caixas de seleção dos detalhes da instância que você deseja que apareçam no papel de parede. Desmarque as caixas de seleção dos detalhes da instância selecionados anteriormente que você deseja remover do papel de parede.

    • Exibir tags de instância no papel de parede: selecione uma das seguintes configurações para exibir tags de instância no papel de parede:

      • Nenhuma: não exiba nenhuma tag de instância no papel de parede.

      • Mostrar todas: exiba todas as tags de instância no papel de parede.

      • Mostrar filtradas: exibe as tags de instância especificadas no papel de parede. Quando você selecionar essa configuração, será possível adicionar tags de instância que você deseje exibir no seu papel de parede na caixa Filtro de tag de instância.

        nota

        Você deve habilitar as tags nos metadados para mostrá-las no papel de parede. Para obter mais informações sobre tags e metadados da instância, consulte Trabalho com tags de instância em metadados de instância.

    Guia Papel de parede nas configurações de inicialização do EC2.

  6. Na guia Volumes, selecione se deseja inicializar os volumes anexados à instância. A ativação define letras de unidade para quaisquer volumes adicionais e estende-as para usar o espaço disponível. Se você selecionar Todos, todos os volumes de armazenamento serão inicializados. Se você selecionar Dispositivos, somente os dispositivos especificados na lista serão inicializados. É preciso inserir cada dispositivo a ser inicializado. Use os dispositivos listados no console do EC2, por exemplo, xvdb ou /dev/nvme0n1. A lista suspensa exibe os volumes de armazenamento anexados à instância. Para inserir um dispositivo que não está anexado à instância, insira-o no campo de texto.

    Nome, Letra e Partição são campos opcionais. Se nenhum valor for especificado para Partição, os volumes de armazenamento com mais de 2 TB serão inicializados com o tipo de partição gpt e os com menos de 2 TB serão inicializados com o tipo de partição mbr. Se os dispositivos estiverem configurados e um dispositivo não NTFS contiver uma tabela de partição ou os primeiros 4 KB do disco contiverem dados, o disco será ignorado e a ação será registrada.

    Aplicação de configurações do EC2 Launch.

Veja a seguir um exemplo de arquivo de configuração YAML criado a partir das configurações inseridas no diálogo EC2Launch.

version: 1.0
config:
  - stage: boot
	tasks:
      - task: extendRootPartition
  - stage: preReady
    tasks:
      - task: activateWindows
        inputs:
          activation:
            type: amazon
      - task: setDnsSuffix
        inputs:
          suffixes:
            - $REGION.ec2-utilities.amazonaws.com
      - task: setAdminAccount
        inputs:
          password:
            type: random
      - task: setWallpaper
        inputs:
          path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
          attributes:
            - hostName
            - instanceId
            - privateIpAddress
            - publicIpAddress
            - instanceSize
            - availabilityZone
            - architecture
            - memory
            - network
  - stage: postReady
    tasks:
      - task: startSsm

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) e os erros (error.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.

Configurar o EC2Launch v2 com a CLI

É possível usar a Interface de Linhas de Comando (CLI) para definir suas configurações do EC2Launch e gerenciar o serviço. A seção a seguir contém descrições e informações de uso dos comandos da CLI que podem ser usados para gerenciamento do EC2Launch v2.

collect-logs

Coleta arquivos de log para o EC2Launch, compacta os arquivos e os coloca em um diretório especificado.

Exemplo

ec2launch collect-logs -o C:\Mylogs.zip

Uso

ec2launch collect-logs [flags]

Sinalizadores

-h, --help

ajuda para collect-logs

-o, --output string

caminho para arquivos de log de saída compactados

get-agent-config

Imprime agent-config.yml no formato especificado (JSON ou YAML). Se nenhum formato for especificado, agent-config.yml será impresso no formato especificado anteriormente.

Exemplo

ec2launch get-agent-config -f json

Exemplo 2

Os seguintes comandos do PowerShell mostram como editar e salvar o arquivo agent-config no formato JSON.

$config = & "$env:ProgramFiles/Amazon/EC2Launch/EC2Launch.exe" --format json | ConvertFrom-Json
$jumboFrame =@"
{
   "task": "enableJumboFrames"
}
"@
$config.config | %{if($_.stage -eq 'postReady'){$_.tasks += (ConvertFrom-Json -InputObject $jumboFrame)}}
$config | ConvertTo-Json -Depth 6 | Out-File -encoding UTF8
$env:ProgramData/Amazon/EC2Launch/config/agent-config.yml

Uso

ec2launch get-agent-config [flags]

Sinalizadores

-h, --help

ajuda para get-agent-config

-f, --format string

formato de saída do arquivo agent-config: json, yaml

list-volumes

Lista todos os volumes de armazenamento anexados à instância, incluindo volumes temporários e do EBS.

Exemplo

ec2launch list-volumes

Uso

ec2launch list-volumes

Sinalizadores

-h, --help

ajuda para list-volumes

reset

O objetivo principal dessa tarefa é redefinir o agente para a próxima vez que ele for executado. Para fazer isso, o comando reset exclui todos os dados de estado do agente do EC2Launch v2 do EC2Launch diretório local (consulte Estrutura de diretório do EC2Launch v2). Opcionalmente, a redefinição exclui os logs do serviço e do Sysprep.

O comportamento do script depende do modo em que o agente executa os scripts: em linha ou desanexados.

Em linha (padrão)

O agente EC2Launch v2 executa os scripts um de cada vez (detach: false) Essa é a configuração padrão.

nota

Quando seu script em linha emite um  comando reset ou sysprep, ele é executado imediatamente e redefine o agente. A tarefa atual é concluída e, em seguida, o agente é desligado sem executar mais nenhuma tarefa.

Por exemplo, se a tarefa que emite o comando tivesse sido seguida por uma tarefa startSsm (incluída por padrão após a execução dos dados do usuário), a tarefa não executaria e o serviço Systems Manager nunca seria iniciado.

Desanexados

O agente do EC2Launch v2 executa scripts simultaneamente com outras tarefas (detach: true).

nota

Quando seu script desanexado emite um comando reset ou sysprep, esses comandos aguardam a conclusão do agente antes de serem executados. As tarefas após executeScript ainda serão executadas.

Exemplo

ec2launch reset -c

Uso

ec2launch reset [flags]

Sinalizadores

-c, --clean

limpa os logs da instância antes de reset

-h, --help

ajuda para reset

run

Executa o EC2Launch v2.

Exemplo

ec2launch run

Uso

ec2launch run [flags]

Sinalizadores

-h, --help

ajuda para run

status

Obtém o status do agente EC2Launch v2. Opcionalmente, bloqueia o processo até que o agente seja concluído. O código de saída do processo determina o estado do agente:

  • 0: o agente foi executado de forma bem-sucedida.

  • 1: o agente foi executado e apresentou falha.

  • 2: o agente ainda está em execução.

  • 3: o agente está em um estado desconhecido. O estado do agente é não está em execução ou foi interrompido.

  • 4: ocorreu um erro ao tentar recuperar o estado do agente.

  • 5: o agente não está em execução e o status da última execução conhecida é desconhecido. Isso pode significar uma das seguintes opções:

    • tanto o state.json quanto o previous-state.json foram excluídos.

    • o previous-state.json está corrompido.

    Este é o estado do agente após executar o comando reset.

Exemplo:

ec2launch status -b

Uso

ec2launch status [flags]

Sinalizadores

-b,--block

bloqueia o processo até que o agente conclua a execução

-h,--help

ajuda para status

sysprep

O objetivo principal dessa tarefa é redefinir o agente para a próxima vez que ele for executado. Para fazer isso, o comando sysprep redefine o estado do agente, atualiza o arquivo unattend.xml, desabilita o RDP e executa o Sysprep.

O comportamento do script depende do modo em que o agente executa os scripts: em linha ou desanexados.

Em linha (padrão)

O agente EC2Launch v2 executa os scripts um de cada vez (detach: false) Essa é a configuração padrão.

nota

Quando seu script em linha emite um  comando reset ou sysprep, ele é executado imediatamente e redefine o agente. A tarefa atual é concluída e, em seguida, o agente é desligado sem executar mais nenhuma tarefa.

Por exemplo, se a tarefa que emite o comando tivesse sido seguida por uma tarefa startSsm (incluída por padrão após a execução dos dados do usuário), a tarefa não executaria e o serviço Systems Manager nunca seria iniciado.

Desanexados

O agente do EC2Launch v2 executa scripts simultaneamente com outras tarefas (detach: true).

nota

Quando seu script desanexado emite um comando reset ou sysprep, esses comandos aguardam a conclusão do agente antes de serem executados. As tarefas após executeScript ainda serão executadas.

Exemplo:

ec2launch sysprep

Uso

ec2launch sysprep [flags]

Sinalizadores

-c,--clean

limpa os logs da instância antes de sysprep

-h,--help

ajuda para Sysprep

-s,--shutdown

desliga a instância após sysprep

validar

Valida o arquivo agent-config C:\ProgramData\Amazon\EC2Launch\config\agent-config.yml.

Exemplo

ec2launch validate

Uso

ec2launch validate [flags]

Sinalizadores

-h , --help

ajuda para validate

versão

Obtém a versão executável.

Exemplo

ec2launch version

Uso

ec2launch version [flags]

Sinalizadores

-h, --help

ajuda para version

wallpaper

Define o novo papel de parede para o caminho de papel de parede fornecido (arquivo .jpg) e exibe os detalhes da instância selecionada.

Sintaxe

ec2launch wallpaper ^
--path="C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg" ^
--all-tags ^
--attributes=hostName,instanceId,privateIpAddress,publicIpAddress,instanceSize,availabilityZone,architecture,memory,network

Entradas

Parâmetros
--allowed-tags [tag-name-1, tag-name-n]

(Opcional) Matriz JSON codificada em Base64 de nomes de tags de instância para exibição no papel de parede. Você pode usar essa tag ou --all-tags, mas não ambas.

--attributes attribute-string-1, attribute-string-n

(Opcional) uma lista separada por vírgulas de strings de atributo wallpaper para aplicar configurações ao papel de parede.

[--path | -p] path-string

(Obrigatório) Especifica o caminho do arquivo da imagem do plano de fundo do wallpaper.

Sinalizadores
--all-tags

(Opcional) Exibe todas as tags de instância no papel de parede. Você pode usar essa tag ou --allowed-tags, mas não ambas.

[--help | -h]

Exibe a ajuda referente ao comando wallpaper.

Configuração de tarefas do EC2Launch v2

Esta seção inclui o esquema, tarefas, detalhes e exemplos de configuração para agent-config.yml e dados do usuário.

Esquema: agent-config.yml

Veja a estrutura do arquivo agent-config.yml abaixo. Não é possível repetir uma tarefa na mesma etapa. Para obter as propriedades da tarefa, consulte as descrições da tarefa a seguir.

Estrutura do documento: agent-config.yml

JSON

{
	"version": "1.0",
	"config": [
		{
			"stage": "string",
			"tasks": [
				{
					"task": "string",
					"inputs": {
						...
					}
				},
				...
			]
		},
		...
	]
}

YAML

version: 1.0
config:
- stage: string
  tasks:
  - task: string
	inputs:
	  ...
  ...
...

Exemplo: agent-config.yml

O exemplo a seguir mostra as configurações do arquivo de configuração agent-config.yml.

version: 1.0
config:
- stage: boot
  tasks:
  - task: extendRootPartition
- stage: preReady
  tasks:
  - task: activateWindows
    inputs:
      activation:
        type: amazon
  - task: setDnsSuffix
    inputs:
      suffixes:
      - $REGION.ec2-utilities.amazonaws.com
  - task: setAdminAccount
    inputs:
      password:
        type: random
  - task: setWallpaper
    inputs:
      path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
      attributes:
      - hostName
      - instanceId
      - privateIpAddress
      - publicIpAddress
      - instanceSize
      - availabilityZone
      - architecture
      - memory
      - network
- stage: postReady
  tasks:
  - task: startSsm

Esquema: dados do usuário

Os exemplos de JSON e YAML a seguir mostram a estrutura do documento para dados do usuário. O Amazon EC2 analisa cada tarefa nomeada na matriz tasks que você especifica no documento. Cada tarefa tem seu próprio conjunto de propriedades e requisitos. Para obter detalhes, consulte Definições de tarefa.

nota

Uma tarefa só deve aparecer uma vez na matriz de tarefas de dados do usuário.

Estrutura do documento: dados do usuário

JSON

{
	"version": "1.1",
	"tasks": [
		{
			"task": "string",
			"inputs": {
				...
			},
		},
		...
	]
}

YAML

version: 1.1
tasks:
- task: string
  inputs:
    ...
...

Exemplo: dados do usuário

Para obter mais informações sobre as funções de usuário, consulte Como o Amazon EC2 lida com os dados dos usuários para instâncias do Windows.

O exemplo de documento YAML a seguir mostra um script do PowerShell que o EC2Launch v2 executa como dados do usuário para criar um arquivo.

version: 1.1
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: powershell
    runAs: localSystem
    content: |-
      New-Item -Path 'C:\PowerShellTest.txt' -ItemType File

É possível usar um formato XML para os dados do usuário que seja compatível com as versões anteriores do agente de inicialização. O EC2Launch v2 executa o script como uma tarefa executeScript no estágio UserData. Para atender ao comportamento do EC2Launch v1 e do EC2Config, o script de dados do usuário é executado por padrão como um processo anexado/em linha.

Você pode adicionar tags opcionais para personalizar a execução do seu script. Por exemplo, para executar o script de dados do usuário quando a instância é reinicializada, além de uma vez quando a instância é iniciada, é possível usar a seguinte tag:

<persist>true</persist>

Exemplo:

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<persist>true</persist>

É possível especificar um ou mais argumentos do PowerShell com tag <powershellArguments>. Se nenhum argumento for passado, o EC2Launch v2 adicionará o seguinte argumento por padrão: -ExecutionPolicy Unrestricted.

Exemplo:

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<powershellArguments>-ExecutionPolicy Unrestricted -NoProfile -NonInteractive</powershellArguments>

Para executar um script de dados de usuário XML como um processo separado, adicione a seguinte tag aos dados do usuário.

<detach>true</detach>

Exemplo:

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<detach>true</detach>
nota

A tag de desanexação não é compatível com agentes de inicialização anteriores.

Log de alterações: dados do usuário

A tabela a seguir lista as alterações nos dados do usuário e as faz referência cruzada à versão do agente EC2Launch v2 aplicável.

Versão de dados do usuário Detalhes Introduzida em
1.1

  • As tarefas de dados do usuário são executadas antes do estágio PostReady no arquivo de configuração do agente.

  • Executa dados do usuário antes de iniciar o Systems Manager Agent (mesmo comportamento do EC2Launch v1 e do EC2Config).*

 EC2Launch v2 versão 2.0.1245
1,0

  • Será descontinuada.

  • As tarefas de dados do usuário são executadas depois do estágio PostReady no arquivo de configuração do agente. Isso não é compatível com versões anteriores do EC2Launch v1.

  • Impactado por uma condição de corrida entre o início do Systems Manager Agent e as tarefas de dados do usuário.

 EC2Launch v2 versão 2.0.0

* Quando usado com o arquivo agent-config.yml padrão.

Definições de tarefa

Cada tarefa tem seu próprio conjunto de propriedades e requisitos. Para obter detalhes, consulte as tarefas individuais que você deseja incluir no documento.

activateWindows

Ativa o Windows em relação a um conjunto de servidores de AWS KMS. A ativação será ignorada se a instância for detectada como traga a sua própria licença (BYOL).

Frequência — uma vez

AllowedStages — [PreReady]

Entradas —

activation: (mapa)

type: (string) tipo de ativação a usar, defina como amazon

Exemplo

task: activateWindows
inputs:
  activation:
    type: amazon

enableJumboFrames

Habilita frames jumbo, que aumentam a MTU (unidade de transmissão máxima) do adaptador de rede. Para ter mais informações, consulte Frames jumbo (9001 MTU).

Frequência — sempre

AllowedStages — [PostReady, UserData]

Entradas — nenhuma

Exemplo

task: enableJumboFrames

enableOpenSsh

Habilita o Windows OpenSSH e adiciona a chave pública da instância à pasta de chaves autorizadas.

Frequência — uma vez

AllowedStages — [PreReady, UserData]

Entradas — nenhuma

Exemplo

O exemplo a seguir mostra como habilitar o OpenSSH em uma instância e adicionar a chave pública da instância à pasta de chaves autorizadas. Essa configuração funciona somente em instâncias que executam o Windows Server 2019 e versões posteriores.

task: enableOpenSsh

executeProgram

Executa um programa com argumentos opcionais e uma frequência especificada.

Estágios: você pode executar a tarefa executeProgram durante os estágios PreReady, PostReady e UserData.

Frequência: configurável. Consulte Entradas.

Entradas

Você pode configurar os parâmetros de runtime seguinte forma:

frequência (string)

(Obrigatório) Especifique exatamente um dos seguintes valores:

  • once

  • always

caminho (string)

(Obrigatório) O caminho do arquivo para que o executável seja executado.

argumentos (lista de strings)

(Opcional) Uma lista de argumentos separados por vírgula para fornecer ao programa como entrada.

runAs (string)

(Obrigatório) Deve ser definido como localSystem

Saída

Todas as tarefas gravam entradas do arquivo de log no arquivo agent.log. A saída adicional da tarefa executeProgram é armazenada separadamente em uma pasta com nome dinâmico, da seguinte forma:

%LocalAppData%\Temp\EC2Launch#########\outputfilename.tmp

O caminho exato para os arquivos de saída está incluído no arquivo agent.log, por exemplo:

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\ExecuteProgramInputs.tmp
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
Arquivos de saída para a tarefa executeProgram
ExecuteProgramInputs.tmp

Contém o caminho para o executável e todos os parâmetros de entrada que a tarefa executeProgram transmite para ele quando é executada.

Output.tmp

Contém a saída de runtime do programa que a tarefa executeProgram executa.

Err.tmp

Contém as mensagens de erro de runtime do programa que a tarefa executeProgram executa.

Exemplos

Os exemplos a seguir mostram como executar um arquivo executável de um diretório local em uma instância com a tarefa executeProgram.

Exemplo 1: configurar executável com um argumento

Este exemplo mostra uma tarefa executeProgram que executa um executável de configuração no modo silencioso.

task: executeProgram
inputs:
- frequency: always
  path: C:\Users\Administrator\Desktop\setup.exe
  arguments: ['-quiet']
Exemplo 2: VLC executável com dois argumentos

Este exemplo mostra uma tarefa executeProgram que executa um arquivo VLC executável com dois argumentos transmitidos como parâmetros de entrada.

task: executeProgram
inputs:
- frequency: always
  path: C:\vlc-3.0.11-win64.exe 
  arguments: ['/L=1033','/S']
  runAs: localSystem

executeScript

Executa um script com argumentos opcionais e uma frequência especificada. O comportamento do script depende do modo em que o agente executa os scripts: em linha ou desanexados.

Em linha (padrão)

O agente EC2Launch v2 executa os scripts um de cada vez (detach: false) Essa é a configuração padrão.

nota

Quando seu script em linha emite um  comando reset ou sysprep, ele é executado imediatamente e redefine o agente. A tarefa atual é concluída e, em seguida, o agente é desligado sem executar mais nenhuma tarefa.

Por exemplo, se a tarefa que emite o comando tivesse sido seguida por uma tarefa startSsm (incluída por padrão após a execução dos dados do usuário), a tarefa não executaria e o serviço Systems Manager nunca seria iniciado.

Desanexados

O agente do EC2Launch v2 executa scripts simultaneamente com outras tarefas (detach: true).

nota

Quando seu script desanexado emite um comando reset ou sysprep, esses comandos aguardam a conclusão do agente antes de serem executados. As tarefas após executeScript ainda serão executadas.

Estágios: você pode executar a tarefa executeScript durante os estágios PreReady, PostReady e UserData.

Frequência: configurável. Consulte Entradas.

Entradas

Você pode configurar os parâmetros de runtime seguinte forma:

frequência (string)

(Obrigatório) Especifique exatamente um dos seguintes valores:

  • once

  • always

tipo (string)

(Obrigatório) Especifique exatamente um dos seguintes valores:

  • batch

  • powershell

argumentos (lista de strings)

(Opcional) Uma lista de argumentos de string a serem transmitidos ao shell. Esse parâmetro não é compatível com type: batch. Se nenhum argumento for passado, o EC2Launch v2 adicionará o seguinte argumento por padrão: -ExecutionPolicy Unrestricted.

conteúdo (string)

(Obrigatório) Conteúdo de script

runAs (string)

(Obrigatório) Especifique exatamente um dos seguintes valores:

  • admin

  • localSystem

desanexar (booleano)

(Opcional) O agente do EC2Launch v2 assume como padrão a execução de um script por vez (detach: false). Para executar o script simultaneamente com outras tarefas, defina o valor como true (detach: true).

nota

Os códigos de saída de script (incluindo 3010) não têm efeito quando detach é definido como true.

Saída

Todas as tarefas gravam entradas do arquivo de log no arquivo agent.log. A saída adicional do script que a tarefa executeScript executa é armazenada separadamente em uma pasta com nome dinâmico, da seguinte forma:

%LocalAppData%\Temp\EC2Launch#########\outputfilename.ext

O caminho exato para os arquivos de saída está incluído no arquivo agent.log, por exemplo:

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\UserScript.ps1
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
Arquivos de saída para a tarefa executeScript
UserScript.ext

Contém o script que a tarefa executeScript executou. A extensão do arquivo depende do tipo de script especificado no parâmetro type da tarefa executeScript, da seguinte forma:

  • Se o tipo for batch, então a extensão do arquivo será .bat.

  • Se o tipo for powershell, então a extensão do arquivo será .ps1.

Output.tmp

Contém a saída de runtime do script que a tarefa executeScript executa.

Err.tmp

Contém as mensagens de erro de runtime do script que a tarefa executeScript executa.

Exemplos

Os exemplos a seguir mostram como executar um script em linha com a tarefa executeScript.

Exemplo 1: arquivo de texto de saída Hello world

Este exemplo mostra uma tarefa executeScript que executa um script do PowerShell para criar um arquivo de texto "Hello world" na unidade C:.

task: executeScript
inputs:
- frequency: always
  type: powershell
  runAs: admin
  content: |-
    New-Item -Path 'C:\PowerShellTest.txt' -ItemType File
    Set-Content 'C:\PowerShellTest.txt' "Hello world"
Exemplo 2: execução de dois scripts

Este exemplo mostra que a tarefa executeScript pode executar mais de um script, e o tipo de script não precisa necessariamente corresponder.

O primeiro script (type: powershell) grava um resumo dos processos atualmente em execução na instância em um arquivo de texto localizado na unidade C:.

O segundo script (batch) grava as informações do sistema no arquivo Output.tmp.

task: executeScript
inputs:
- frequency: always
  type: powershell
  content: |
    Get-Process | Out-File -FilePath C:\Process.txt
  runAs: localSystem
- frequency: always
  type: batch
  content: |
    systeminfo
Exemplo 3: configuração do sistema idempotente com reinicializações

Este exemplo mostra uma tarefa executeScript que executa um script idempotente para realizar a seguinte configuração do sistema com uma reinicialização entre cada etapa:

  • Renomear o computador.

  • Juntar o computador ao domínio.

  • Habilitar Telnet.

O script garante que cada operação seja executada apenas uma vez. Isso evita um loop de reinicialização e torna o script idempotente.

task: executeScript
inputs:
- frequency: always
  type: powershell
  runAs: localSystem
  content: |-
    $name = $env:ComputerName
     if ($name -ne $desiredName) {
       Rename-Computer -NewName $desiredName
       exit 3010
     }
     $domain = Get-ADDomain
     if ($domain -ne $desiredDomain) 
     {
       Add-Computer -DomainName $desiredDomain
       exit 3010
     }
    $telnet = Get-WindowsFeature -Name Telnet-Client
    if (-not $telnet.Installed)
    {
      Install-WindowsFeature -Name "Telnet-Client"
      exit 3010 
    }

extendRootPartition

Estende o volume raiz para usar todo o espaço disponível no disco.

Frequência — uma vez

AllowedStages — [Boot]

Entradas — nenhuma

Exemplo 

task: extendRootPartition

initializeVolume

Inicializa volumes vazios que estão anexados à instância para que eles sejam ativados e particionados. O agente de inicialização ignorará a inicialização se detectar que o volume não está vazio. Um volume será considerado vazio se os primeiros 4 KiB estiverem vazios ou se o volume não tiver um layout de unidade reconhecível pelo Windows.

O parâmetro de entrada letter sempre é aplicado quando essa tarefa é executada, quer a unidade tenha sido inicializada ou não.

A tarefa initializeVolume realiza as ações a seguir.

  • Defina os atributos de disco offline e readonly como falsos.

  • Crie uma partição. Se nenhum tipo de partição for especificado no parâmetro de entrada partition, os seguintes padrões serão aplicados:

    • Se o tamanho do disco for menor do que 2 TB, defina o tipo de partição com mbr.

    • Se o tamanho do disco for 2 TB ou mais, defina o tipo de partição com gpt.

  • Formate o volume como NTFS.

  • Defina o rótulo do volume como se segue:

    • Use o valor name do parâmetro de entrada, se especificado.

    • Se o volume for efêmero e nenhum nome estiver especificado, defina o rótulo do volume como Temporary Storage Z.

  • Se o volume for efêmero (SSD ou HDD, não Amazon EBS), crie um arquivo Important.txt na raiz do volume com o seguinte conteúdo:

    This is an 'Instance Store' disk and is provided at no additional charge.

*This disk offers increased performance since it is local to the host
*The number of Instance Store disks available to an instance vary by instance type
*DATA ON THIS DRIVE WILL BE LOST IN CASES OF IMPAIRMENT OR STOPPING THE INSTANCE. PLEASE ENSURE THAT ANY IMPORTANT DATA IS BACKED UP FREQUENTLY

For more information, please refer to: Armazenamento de instâncias do Amazon EC2.

  • Defina a letra da unidade como o valor especificado no parâmetro de entrada letter.

Estágios: você pode executar a tarefa initializeVolume durante os estágios PostReady e UserData.

Frequência: sempre.

Entradas

Você pode configurar os parâmetros de runtime seguinte forma:

dispositivos (lista de mapas)

(Condicional) Configuração de cada dispositivo iniciado pelo agente de inicialização. É obrigatório quando o parâmetro de entrada initialize está definido como devices.

  • dispositivo (string, obrigatório): identifica o dispositivo durante a criação da instância. Por exemplo, xvdb, xvdf ou \dev\nvme0n1.

  • letra (string, opcional): um caractere. A letra de unidade a ser atribuída.

  • nome (string, opcional): o nome do volume a ser atribuído.

  • partição (string, opcional): especifique um dos seguintes valores para o tipo de partição a ser criada ou deixe o agente de inicialização usar o padrão de acordo com o tamanho do volume:

    • mbr

    • gpt

inicializar (string)

(Obrigatório) Especifique exatamente um dos seguintes valores:

  • all

  • devices

Exemplos

Os exemplos a seguir mostram exemplos de configurações de entrada para a tarefa initializeVolume.

Exemplo 1: inicializar dois volumes em uma instância

Este exemplo mostra uma tarefa initializeVolume que inicializa dois volumes secundários em uma instância. O dispositivo denominado DataVolume2 no exemplo é efêmero.

task: initializeVolume
inputs:
  initialize: devices
  devices:
  - device: xvdb
    name: DataVolume1
    letter: D
    partition: mbr
  - device: /dev/nvme0n1
    name: DataVolume2
    letter: E
    partition: gpt
Exemplo 2: inicializar volumes do EBS anexados a uma instância

Este exemplo mostra uma tarefa initializeVolume que inicializa todos os volumes vazios do EBS que estão conectados à instância.

task: initializeVolume
inputs:
  initialize: all

optimizeEna

Otimiza as configurações do ENA com base no tipo de instância atual; pode reinicializar a instância.

Frequência — sempre

AllowedStages — [PostReady, UserData]

Entradas — nenhuma

Exemplo 

task: optimizeEna

setAdminAccount

Define atributos para a conta de administrador padrão criada na máquina local.

Frequência — uma vez

AllowedStages — [PreReady]

Entradas —

name: (string) nome da conta de administrador

password: (mapa)

type: (string) estratégia para definir a senha como static, random ou doNothing

data: (string) armazena dados se o campo type for estático

Exemplo

task: setAdminAccount
inputs:
  name: Administrator
  password:
    type: random

setDnsSuffix

Adiciona sufixos DNS à lista de sufixos de pesquisa. Somente sufixos que ainda não existem são adicionados à lista. Para obter mais informações sobre como os agentes de inicialização definem os sufixos DNS, consulte Configuração do sufixo DNS para agentes de inicialização do Windows.

Frequência — sempre

AllowedStages — [PreReady]

Entradas —

suffixes: (lista de strings) lista de um ou mais sufixos DNS válidos; variáveis de substituição válidas são $REGION e $AZ

Exemplo

task: setDnsSuffix
inputs:
  suffixes:
  - $REGION.ec2-utilities.amazonaws.com

setHostName

Define o nome do host do computador como uma string personalizada ou, se o hostName não for especificado, o endereço IPv4 privado.

Frequência — sempre

AllowedStages — [PostReady, UserData]

Entradas —

hostName: (string) nome do host opcional, que deve ser formatado conforme o seguinte.

  • Ele deve ter 15 caracteres ou menos

  • Ele deve conter apenas caracteres alfanuméricos (a-z, A-Z, 0-9) e hífen (-).

  • Ele não deve consistir inteiramente em caracteres numéricos.

reboot: (booliano) indica se uma reinicialização é permitida quando o nome de host é alterado

Exemplo

task: setHostName
inputs:
  reboot: true

setWallpaper

Cria o arquivo de atalho setwallpaper.lnk na pasta de startup de cada usuário existente, exceto para Default User. Esse arquivo de atalho é executado quando o usuário faz login pela primeira vez após a inicialização da instância. Ele configura a instância com um papel de parede personalizado que exibe os atributos da instância.

O caminho de arquivo de atalho é:

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk
nota

Quando você remover a tarefa setWallpaper, não exclua esse arquivo de atalho. Para ter mais informações, consulte A tarefa setWallpaper não está ativada, mas o papel de parede é redefinido na reinicialização.

Estágios: é possível configurar o papel de parede durante os estágios PreReady e UserData.

Frequência: always

Configuração do papel de parede

Você pode usar as definições a seguir para configurar o papel de parede.

Entradas

Parâmetros de entrada que você fornece e atributos que você pode definir para configurar o papel de parede:

atributos (lista de strings)

(Opcional) Você pode adicionar um ou mais dos seguintes atributos ao papel de parede:

  • architecture

  • availabilityZone

  • hostName

  • instanceId

  • instanceSize

  • memory

  • network

  • privateIpAddress

  • publicIpAddress

instanceTags

(Opcional) Você pode usar exatamente uma das seguintes opções para essa configuração.

  • AllTags (string): adicione todas as tags de instância ao papel de parede.

    instanceTags: AllTags

  • InstanceTags (lista de strings): especifique uma lista de nomes de tags de instância para adicionar ao papel de parede. Por exemplo:

    instanceTags:
  - Tag 1
  - Tag 2
caminho (string)

(Obrigatório) O caminho do nome do arquivo da imagem local no formato .jpg a ser usada como imagem do papel de parede.

Exemplo

O exemplo a seguir mostra as entradas da configuração do papel de parede que definem o caminho do arquivo da imagem de fundo do papel de parede, junto com as tags de instância denominadas Tag 1 e Tag 2, e os atributos que incluem o nome do host, o ID da instância e os endereços IP públicos e privados da instância.

task: setWallpaper
inputs:
  path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
  attributes:
  - hostName
  - instanceId
  - privateIpAddress
  - publicIpAddress
  instanceTags:
  - Tag 1
  - Tag 2
nota

Você deve habilitar as tags nos metadados para mostrá-las no papel de parede. Para obter mais informações sobre tags e metadados da instância, consulte Trabalho com tags de instância em metadados de instância.

startSsm

Iniciar o serviço Systems Manager (SSM) após o Sysprep.

Frequência — sempre

AllowedStages — [PostReady, UserData]

Entradas — nenhuma

Exemplo

task: startSsm

sysprep

Redefine o estado do serviço, atualiza unattend.xml, desativa o RDP e executa Sysprep. Esta tarefa só é executada depois que todas as outras tarefas forem concluídas

Frequência — uma vez

AllowedStages — [UserData]

Entradas —

clean: (booliano) limpa os logs de instância antes de executar o Sysprep

shutdown: (booliano) desliga a instância depois de executar o Sysprep

Exemplo

task: sysprep
inputs:
  clean: true
  shutdown: true

writeFile

Grava um arquivo em um destino.

Frequência — visualizar Entradas

AllowedStages — [PostReady, UserData]

Entradas —

frequency: (string) once ou always

destination: (string) caminho no qual gravar o conteúdo

content: (string) texto a gravar no destino

Exemplo

task: writeFile
inputs:
- frequency: once
  destination: C:\Users\Administrator\Desktop\booted.txt
  content: Windows Has Booted

Códigos de saída e reinicializações do EC2Launch v2

É possível usar EC2Launch v2 para definir como os códigos de saída são manipulados por seus scripts. Por padrão, o código de saída do último comando executado em um script é relatado como o código de saída de todo o script. Por exemplo, se um script incluir três comandos e o primeiro comando falhar, mas os seguintes forem bem-sucedidos, o status de execução será relatado como success porque o comando final foi bem-sucedido.

Se quiser que um script reinicialize uma instância, você deverá especificar exit 3010 em seu script, mesmo quando a reinicialização for a última etapa do script. O exit 3010 instrui o EC2Launch v2 a reiniciar a instância e chamar o script novamente até que ele retorne um código de saída que não seja 3010 ou até que a contagem máxima de reinicializações seja atingida. O EC2Launch v2 permite um máximo de 5 reinicializações por tarefa. Se você tentar reiniciar uma instância a partir de um script usando um mecanismo diferente, como Restart-Computer, o status de execução do script será inconsistente. Por exemplo, ele pode ficar preso em um loop de reinicialização ou não executar a reinicialização.

Se você estiver usando um formato de dados de usuário XML compatível com agentes mais antigos, os dados do usuário poderão ser executados mais vezes do que o pretendido. Para obter mais informações, consulte O serviço executa dados do usuário mais de uma vez na seção Solução de problemas.

EC2Launch v2 e Sysprep

O serviço EC2Launch v2 executa o Sysprep, uma ferramenta da Microsoft que permite a criação de uma AMI personalizada do Windows que pode ser reutilizada. Quando o EC2Launch v2 acessa o Sysprep, ela usa os arquivos em %ProgramData%\Amazon\EC2Launch para determinar quais operações devem ser executadas. É possível editar esses arquivos indiretamente usando a caixa de diálogo Configurações do EC2Launch ou diretamente usando um editor de YAML ou um editor de texto. Contudo, há algumas configurações avançadas que não estão disponíveis na caixa de diálogo Configurações do EC2Launch, portanto, é necessário editar as entradas diretamente.

Se você criar AMIs com base em uma instância depois de atualizar suas configurações, as configurações novas serão aplicadas a qualquer instância executada pela nova AMI. Para obter informações sobre como criar uma AMI, consulte Criação de uma AMI baseada no Amazon EBS.