Solucionar problemas do EC2Launch v2

Esta seção mostra cenários comuns de solução de problemas para o EC2Launch v2, informações sobre como visualizar logs de eventos do Windows e saída e mensagens do log do console.

Cenários comuns de solução de problemas

Esta seção mostra cenários comuns de solução de problemas e etapas para resolução.

Cenários

• Falha no serviço ao definir o papel de parede
• Falha no serviço ao executar dados do usuário
• O serviço executa uma tarefa apenas uma vez
• Falha no serviço ao executar uma tarefa
• O serviço executa dados do usuário mais de uma vez
• As tarefas agendadas do EC2Launch v1 não conseguem ser executadas após a migração para o EC2Launch v2
• O serviço inicializa um volume do EBS que não está vazio
• A tarefa setWallpaper não está ativada, mas o papel de parede é redefinido na reinicialização
• Serviço preso no status em execução
• Um agent-config.yml inválido impede a abertura da caixa de diálogo de configurações do EC2Launch v2
• task:executeScript should be unique and only invoked once

Falha no serviço ao definir o papel de parede

Resolução

1. Verifique se %AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk existe.

2. Verifique %ProgramData%\Amazon\EC2Launch\log\agent.log para saber se ocorreram erros.

Falha no serviço ao executar dados do usuário

Causa possível: a falha no serviço pode ter ocorrido antes da execução dos dados do usuário.

Resolução

1. Verifique %ProgramData%\Amazon\EC2Launch\state\previous-state.json.

2. Veja se boot, network, preReady e postReadyLocalData foram todos marcados como sucesso.

3. Se um dos estágios falhar, verifique se há erros específicos %ProgramData%\Amazon\EC2Launch\log\agent.log.

O serviço executa uma tarefa apenas uma vez

Resolução

1. Verifique a frequência da tarefa.

2. Se o serviço já tiver sido executado após Sysprep e a frequência da tarefa estiver definida como once, a tarefa não será executada novamente.

3. Defina a frequência da tarefa como always se você quiser que ela execute a tarefa sempre que o EC2Launch v2 for executado.

Falha no serviço ao executar uma tarefa

Resolução

1. Verifique as entradas mais recentes em %ProgramData%\Amazon\EC2Launch\log\agent.log.

2. Se não ocorrerem erros, tente executar o serviço manualmente a partir de "%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run para ver se as tarefas foram bem-sucedidas.

O serviço executa dados do usuário mais de uma vez

Resolução

Os dados do usuário são tratados de forma diferente entre o EC2Launch v1 e o EC2Launch v2. O EC2Launch v1 executa dados do usuário como uma tarefa programada na instância quando persist for definido como true. Se persist estiver definido como false, a tarefa não será programada mesmo quando ela sair com uma reinicialização ou for interrompida durante a execução.

EC2Launch v2 executa dados do usuário como uma tarefa de agente e rastreia seu estado de execução. Se os dados do usuário emitirem uma reinicialização do computador ou se os dados do usuário tiverem sido interrompidos durante a execução, o estado de execução persistirá pending e os dados do usuário serão executados novamente na próxima inicialização da instância. Se você quiser impedir que o script de dados do usuário seja executado mais de uma vez, torne o script idempotente.

O exemplo a seguir de script idempotente define o nome do computador e se junta a um domínio.

<powershell>
  $name = $env:computername
  if ($name -ne $desiredName) {
	Rename-Computer -NewName $desiredName
  }
  $domain = Get-ADDomain
  if ($domain -ne $desiredDomain) 
  {
	Add-Computer -DomainName $desiredDomain
  }
  $telnet = Get-WindowsFeature -Name Telnet-Client
  if (-not $telnet.Installed)
  {
	Install-WindowsFeature -Name "Telnet-Client"
  }
</powershell>
<persist>false</persist>

As tarefas agendadas do EC2Launch v1 não conseguem ser executadas após a migração para o EC2Launch v2

Resolução

A ferramenta de migração não detecta qualquer tarefa agendada vinculada aos scripts do EC2Launch v1; portanto, ela não configura automaticamente essas tarefas no EC2Launch v2. Para configurar essas tarefas, edite o arquivo agent-config.yml ou use a caixa de diálogo de configurações do EC2Launch v2. Por exemplo, se uma instância tiver uma tarefa agendada que executa InitializeDisks.ps1, depois de executar a ferramenta de migração, você deverá especificar os volumes que deseja inicializar na caixa de diálogo de configurações do EC2Launch v2. Consulte a Etapa 6 do procedimento para Alterar configurações usando a caixa de diálogo de configurações do EC2Launch v2.

O serviço inicializa um volume do EBS que não está vazio

Resolução

Antes de inicializar um volume, o EC2Launch v2 tenta detectar se ele está vazio. Se um volume não estiver vazio, ele ignorará a inicialização. Quaisquer volumes detectados como não vazios não são inicializados. Um volume é considerado vazio se seus primeiros 4 KiB estiverem vazios ou se o volume não tiver um layout de unidade reconhecível pelo Windows. Um volume que foi inicializado e formatado em um sistema Linux não tem um layout de unidade reconhecível pelo Windows, por exemplo MBR ou GPT. Portanto, ele será considerado vazio e será inicializado. Se você quiser preservar esses dados, não confie na detecção de unidade vazia do EC2Launch v2. Em vez disso, especifique os volumes que você gostaria de inicializar na caixa de diálogo de configurações do EC2Launch v2 (consulte a etapa 6) ou no agent-config.yml.

A tarefa setWallpaper não está ativada, mas o papel de parede é redefinido na reinicialização

A tarefa 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. Remover a tarefa setWallpaper não exclui esse arquivo de atalho. Exclua esse arquivo manualmente ou excluí-lo usando um script.

O caminho do atalho é:

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

Resolução

Exclua esse arquivo manualmente ou exclua-o usando um script.

Exemplo de script PowerShell para excluir arquivo de atalho

foreach ($userDir in (Get-ChildItem "C:\Users" -Force -Directory).FullName)
{
	$startupPath = Join-Path $userDir -ChildPath "AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup"
	if (Test-Path $startupPath)
	{
		$wallpaperSetupPath = Join-Path $startupPath -ChildPath "setwallpaper.lnk"
		if (Test-Path $wallpaperSetupPath)
		{
			Remove-Item $wallpaperSetupPath -Force -Confirm:$false
		}
	}
}

Serviço preso no status em execução

Descrição

O EC2Launch v2 é bloqueado com mensagens de log (agent.log) semelhantes às seguintes:

2022-02-24 08:08:58 Info: *****************************************************************************************
2022-02-24 08:08:58 Info: EC2Launch Service starting
2022-02-24 08:08:58 Info: Windows event custom log exists: Amazon EC2Launch
2022-02-24 08:08:58 Info: ACPI SPCR table not supported. Bailing Out
2022-02-24 08:08:58 Info: Serial port is in use. Waiting for Serial Port...
2022-02-24 08:09:00 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:02 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:04 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:06 Info: ACPI SPCR table not supported. Use default console port.

Possível causa

O SAC está habilitado e usando a porta serial. Para mais informações, consulte Use SAC to troubleshoot your Windows instance (Usar o SAC para solucionar problemas de instâncias do Windows).

Resolução

Tente as seguintes etapas para resolver esse problema:

• Desative o serviço que está usando a porta serial.

• Se quiser que o serviço continue usando a porta serial, crie scripts personalizados para executar tarefas do agente de execução e invoque-os como tarefas agendadas.

Um agent-config.yml inválido impede a abertura da caixa de diálogo de configurações do EC2Launch v2

Descrição

As configurações do EC2Launch v2 tentam analisar o arquivo agent-config.yml antes de abrir a caixa de diálogo. Se o arquivo de configuração YAML não seguir o esquema compatível, a caixa de diálogo exibirá o seguinte erro:

Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.

Resolução

1. Verifique se o arquivo de configuração segue o esquema compatível.

2. Para começar do zero, copie o arquivo de configuração padrão no agent-config.yml. Você pode usar o exemplo agent-config.yml fornecido na seção Configuração da tarefa.

3. Também é possível recomeçar excluindo o agent-config.yml. As configurações do EC2Launch v2 geram um arquivo de configuração vazio.

task:executeScript should be unique and only invoked once

Descrição

Não é possível repetir uma tarefa na mesma etapa.

Resolução

Algumas tarefas devem ser inseridas como uma matriz, como executeScript e executeProgram. Para obter um exemplo de como escrever o script como uma matriz, consulte executeScript.

Logs de eventos do Windows

O EC2Launch v2 publica logs de eventos do Windows para eventos importantes, como a inicialização do serviço, o Windows pronto, e o sucesso e a falha da tarefa. Identificadores de eventos identificam exclusivamente um evento específico. Cada evento contém informações de estágio, tarefa e nível e uma descrição. É possível definir gatilhos para eventos específicos usando o identificador de eventos.

Os IDs de evento fornecem informações sobre um evento e identificam alguns eventos de forma exclusiva. O dígito menos significativo de um ID de evento indica a gravidade de um evento.

Evento	Dígito menos significativo
Success	. . .0
Informational	. . .1
Warning	. . .2
Error	. . .3

Os eventos relacionados ao serviço, gerados quando o serviço é iniciado ou interrompido, incluem um identificador de evento de um dígito.

Evento	Identificador de um dígito
Success	0
Informational	1
Warning	2
Error	3

As mensagens de evento para eventos do EC2LaunchService.exe começam com Service:. As mensagens de evento para eventos do EC2Launch.exe não começam com Service:.

Os IDs de evento de quatro dígitos incluem informações sobre o estado, a tarefa e a gravidade de um evento.

Tópicos

• Formato de ID do evento
• Exemplos de ID de evento
• Esquema de log de eventos do Windows

Formato de ID do evento

A tabela a seguir mostra o formato de um identificador de eventos do EC2Launch v2.

3	2 1	0
S	T	L

As letras e números na tabela representam o tipo de evento e as definições a seguir.

Tipo de evento	Definição
S (Estágio)	0 - Mensagem de nível de serviço 1 - Inicialização 2 - Rede 3 - PreReady 5 - O Windows está pronto 6 - PostReady 7 - Dados do usuário
T (Tarefa)	As tarefas representadas pelos dois valores correspondentes são diferentes para cada estágio. Para visualizar a lista completa de eventos, consulte Esquema de log de eventos do Windows.
L (Nível do evento)	0 - Êxito 1 - Informativo 2 - Aviso 3 - Erro

Exemplos de ID de evento

Veja a seguir alguns exemplos de IDs de evento.

• 5000 - o Windows está pronto para ser usado

• 3010 - êxito ao ativar a tarefa do Windows no estágio PreReady

• 6013 - A tarefa Definir papel de parede no estágio PostReady Local Data encontrou um erro

Esquema de log de eventos do Windows

MessageId/ID do evento	Mensagem do evento
. . .0	Success
. . .1	Informational
. . .2	Warning
. . .3	Error
x	EC2Launch service-level logs
0	EC2Launch service exited successfully
1	EC2Launch service informational logs
2	EC2Launch service warning logs
3	EC2Launch service error logs
10	Replace state.json with previous-state.json
100	Serial Port
200	Sysprep
300	PrimaryNic
400	Metadata
x000	Stage (1 digit), Task (2 digits), Status (1 digit)
1000	Boot
1010	Boot - extend_root_partition
2000	Network
2010	Network - add_routes
3000	PreReady
3010	PreReady - activate_windows
3020	PreReady - install_egpu_manager
3030	PreReady - set_monitor_on
3040	PreReady - set_hibernation
3050	PreReady - set_admin_account
3060	PreReady - set_dns_suffix
3070	PreReady - set_wallpaper
3080	PreReady - set_update_schedule
3090	PreReady - output_log
3100	PreReady - enable_open_ssh
5000	Windows is Ready to use
6000	PostReadyLocalData
7000	PostReadyUserData
6010/7010	PostReadyLocal/UserData - set_wallpaper
6020/7020	PostReadyLocal/UserData - set_update_schedule
6030/7030	PostReadyLocal/UserData - set_hostname
6040/7040	PostReadyLocal/UserData - execute_program
6050/7050	PostReadyLocal/UserData - execute_script
6060/7060	PostReadyLocal/UserData - manage_package
6070/7070	PostReadyLocal/UserData - initialize_volume
6080/7080	PostReadyLocal/UserData - write_file
6090/7090	PostReadyLocal/UserData - start_ssm
7100	PostReadyUserData - enable_open_ssh
6110/7110	PostReadyLocal/UserData - enable_jumbo_frames

Saída do log do console do EC2Launch v2

Esta seção contém uma saída de log do console de exemplo para EC2Launch v2 e lista todas as mensagens de erro de log do console do EC2Launch v2 para ajudar você a solucionar problemas. Para obter mais informações sobre a saída do console da instância e como acessá-la, consulte Saída do console da instância.

Outputs

• Saída do log do console do EC2Launch v2
• Mensagens de log do console do EC2Launch v2

Saída do log do console do EC2Launch v2

Veja a seguir um exemplo de saída de log do console para EC2Launch v2.

2023/11/30 20:18:53Z: Windows sysprep configuration complete.
2023/11/30 20:18:57Z: Message: Waiting for access to metadata...
2023/11/30 20:18:57Z: Message: Meta-data is now available.
2023/11/30 20:18:57Z: AMI Origin Version: 2023.11.15
2023/11/30 20:18:57Z: AMI Origin Name: Windows_Server-2022-English-Full-Base
2023/11/30 20:18:58Z: OS: Microsoft Windows NT 10.0.20348
2023/11/30 20:18:58Z: OsVersion: 10.0
2023/11/30 20:18:58Z: OsProductName: Windows Server 2022 Datacenter
2023/11/30 20:18:58Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500
2023/11/30 20:18:58Z: OsCurrentBuild: 20348
2023/11/30 20:18:58Z: OsReleaseId: 2009
2023/11/30 20:18:58Z: Language: en-US
2023/11/30 20:18:58Z: TimeZone: UTC
2023/11/30 20:18:58Z: Offset: UTC +0000
2023/11/30 20:18:58Z: Launch: EC2 Launch v2.0.1643
2023/11/30 20:18:58Z: AMI-ID: ami-1234567890abcdef1
2023/11/30 20:18:58Z: Instance-ID: i-1234567890abcdef0
2023/11/30 20:18:58Z: Instance Type: c5.large
2023/11/30 20:19:00Z: Driver: AWS NVMe Driver v1.5.0.33
2023/11/30 20:19:00Z: SubComponent: AWS NVMe Driver v1.5.0.33; EnableSCSIPersistentReservations: 0
2023/11/30 20:19:00Z: Driver: AWS PV Driver Package v8.4.3
2023/11/30 20:19:01Z: Driver: Amazon Elastic Network Adapter v2.6.0.0
2023/11/30 20:19:01Z: RDPCERTIFICATE-SUBJECTNAME: EC2AMAZ-SO1T009
2023/11/30 20:19:01Z: RDPCERTIFICATE-THUMBPRINT: 1234567890ABCDEF1234567890ABCDEF1234567890
2023/11/30 20:19:09Z: SSM: Amazon SSM Agent v3.2.1705.0
2023/11/30 20:19:13Z: Username: Administrator
2023/11/30 20:19:13Z: Password: <Password>
1234567890abcdef1EXAMPLEPASSWORD
</Password>
2023/11/30 20:19:14Z: User data format: no_user_data	
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2023/11/30 20:19:14Z: Message: Windows is Ready to use

Mensagens de log do console do EC2Launch v2

Veja a seguir uma lista de todas as mensagens de log do console do EC2Launch v2.

Message: Error EC2Launch service is stopping. {error message}
 Error setting up EC2Launch agent folders
 See instance logs for detail
 Error stopping service
 Error initializing service
Message: Windows sysprep configuration complete
Message: Invalid administrator username: {invalid username}
Message: Invalid administrator password
Username: {username}
Password: <Password>{encrypted password}</Password>
AMI Origin Version: {amiVersion}
AMI Origin Name: {amiName}
Microsoft Windows NT {currentVersion}.{currentBuildNumber}
OsVersion: {currentVersion}
OsProductName: {productName}
OsBuildLabEx: {buildLabEx}
OsCurrentBuild: {currentBuild}
OsReleaseId: {releaseId}
Language: {language}
TimeZone: {timeZone}
Offset: UTC {offset}
Launch agent: EC2Launch {BuildVersion}
AMI-ID: {amiId}
Instance-ID: {instanceId}
Instance Type: {instanceType}
RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
SqlServerBilling: {sql billing}
SqlServerInstall: {sql patch leve, edition type}
Driver: AWS NVMe Driver {version}
Driver: Inbox NVMe Driver {version}
Driver: AWS PV Driver Package {version}
Microsoft-Hyper-V is installed.
Unable to get service status for vmms
Microsoft-Hyper-V is {status}
SSM: Amazon SSM Agent {version}
AWS VSS Version: {version}
Message: Windows sysprep configuration complete
Message: Windows is being configured. SysprepState is {state}
Windows is still being configured. SysprepState is {state}
Message: Windows is Ready to use
Message: Waiting for meta-data accessibility...
Message: Meta-data is now available.
Message: Still waiting for meta-data accessibility...
Message: Failed to find primary network interface...retrying...
User data format: {format}