Configurações do EC2Launch v2
Esta seção contém informações sobre como definir configurações para o EC2Launch v2.
Os tópicos incluem:
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.
-
Execute e conecte-se à sua instância do Windows.
-
No menu Iniciar, escolha Todos os programas e navegue até as Configurações do EC2Launch.
-
Na guia Geral da caixa de diálogo Configurações do EC2Launch, é possível habilitar ou desabilitar as configurações a seguir.
-
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. -
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. -
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 seadminPasswordtype
forSpecify
.Os tipos de senha são definidos da seguinte maneira:
-
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.
-
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 emagent-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. -
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.
-
-
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.
-
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 a afinidade de CPU do Receive Side Scaling.
-
Habilitar SSH
Essa configuração habilita o OpenSSH para versões posteriores do Windows a fim de permitir a administração remota do sistema.
-
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).
-
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).
-
-
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. -
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 Visualizar tags programadas para as instâncias usando metadados da instância.
-
-
-
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çãombr
. 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.
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 arquivoagent-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çãoO 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ânciaOs 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çoO 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 incluistate.json
eprevious-state.json
para rastrear o status de cada tarefa. -
sysprep
: SysprepEsse 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 paredeAs imagens de papel de parede são armazenadas nesse diretório.
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 oprevious-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.
Tarefas e exemplos
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 |
|
EC2Launch v2 versão 2.0.1245 |
1,0 |
|
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.
Tarefas
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
-
Esta seção contém um ou mais programas para a tarefa executeProgram executar (entradas). Cada etapa pode incluir as seguintes definições configuráveis:
- 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 tarefaexecuteProgram
é 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
-
Esta seção contém um ou mais scripts para a tarefa executeScript executar (entradas). Cada etapa pode incluir as seguintes definições configuráveis:
- 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 comotrue
(detach: true
).nota
Os códigos de saída de script (incluindo
3010
) não têm efeito quandodetach
é definido comotrue
.
- Saída
-
Todas as tarefas gravam entradas do arquivo de log no arquivo
agent.log
. A saída adicional do script que a tarefaexecuteScript
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âmetrotype
da tarefaexecuteScript
, 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 unidadeC:
.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 unidadeC:
.O segundo script (
batch
) grava as informações do sistema no arquivoOutput.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
ereadonly
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 em bloco temporário do armazenamento de instância para 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 comodevices
.-
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 denominadoDataVolume2
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 Visualizar tags programadas para as instâncias usando metadados da 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.