# Solución de problemas con el agente EC2Launch v2 En esta sección, se muestran escenarios de solución de problemas comunes para EC2Launch v2, información sobre cómo ver los registros de eventos de Windows y los mensajes y la salida del registro de la consola. **Topics** + [Escenarios habituales](#ec2launchv2-troubleshooting-scenarios) + [Registros de eventos de Windows](#ec2launchv2-windows-event-logs) + [Salida del registro de la consola de EC2Launch v2](#ec2launchv2-console-output) ## Situaciones comunes de solución de problemas En esta sección se muestran las situaciones comunes de solución de problemas y los pasos para la resolución. **Topics** + [El servicio no puede configurar el fondo de pantalla](#ec2launchv2-troubleshooting-wallpaper) + [El servicio no puede ejecutar datos de usuario](#ec2launchv2-troubleshooting-user-data) + [El servicio ejecuta una tarea sólo una vez](#ec2launchv2-troubleshooting-task-once) + [El servicio no puede ejecutar una tarea](#ec2launchv2-troubleshooting-task-failed) + [El servicio ejecuta datos de usuario más de una vez](#ec2launchv2-troubleshooting-user-data-more-than-once) + [Las tareas programadas de EC2Launch v1 no se pueden ejecutar después de la migración a EC2Launch v2](#ec2launchv2-troubleshooting-scheduled-tasks-migration) + [El servicio inicializa un volumen EBS que no está vacío](#ec2launchv2-troubleshooting-ebs-initialize) + [`setWallpaper`La tarea no está habilitada pero el fondo de pantalla se restablece al reiniciar](#ec2launchv2-troubleshooting-wallpaper-resets) + [Servicio atascado en estado de ejecución](#ec2launchv2-troubleshooting-service-stuck-running) + [`agent-config.yml` no válido impide que se abra el cuadro de diálogo de configuración de EC2Launch v2](#ec2launchv2-troubleshooting-invalid-agent-config) + [`task:executeScript should be unique and only invoked once`](#ec2launchv2-troubleshooting-executescript) ### El servicio no puede configurar el fondo de pantalla **Resolución** 1. Compruebe que `%AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk` existe. 1. Compruebe `%ProgramData%\Amazon\EC2Launch\log\agent.log` si se ha producido algún error. ### El servicio no puede ejecutar datos de usuario **Causa posible**: el servicio puede haber devuelto un error antes de ejecutar los datos de usuario. **Resolución** 1. Compruebe `%ProgramData%\Amazon\EC2Launch\state\previous-state.json`. 1. Compruebe si `boot`, `network`, `preReady` y `postReadyLocalData` se han marcado como éxito. 1. Si una de las etapas devolvió un error, compruebe si hay errores específicos en `%ProgramData%\Amazon\EC2Launch\log\agent.log`. ### El servicio ejecuta una tarea sólo una vez **Resolución** 1. Compruebe la frecuencia de la tarea. 1. Si el servicio ya se ejecutó después de Sysprep y la frecuencia de la tarea está establecida en `once`, la tarea no se ejecutará de nuevo. 1. Configure la frecuencia de la tarea como `always` si desea que se ejecute cada vez que se ejecute EC2Launch v2. ### El servicio no puede ejecutar una tarea **Resolución** 1. Compruebe las últimas entradas en `%ProgramData%\Amazon\EC2Launch\log\agent.log`. 1. Si no se han producido errores, pruebe a ejecutar el servicio manualmente desde `"%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run` para ver si las tareas se realizan correctamente. ### El servicio ejecuta datos de usuario más de una vez **Resolución** Los datos de usuario se gestionan de forma diferente entre EC2Launch v1 y EC2Launch v2. EC2Launch v1 ejecuta los datos de usuario como una tarea programada en la instancia cuando configura `persist` como `true`. Si `persist` se establece en `false`, la tarea no está programada incluso cuando se cierra con un reinicio o se interrumpe mientras se ejecuta. EC2Launch v2 ejecuta los datos de usuario como una tarea de agente y realiza un seguimiento de su estado de ejecución. Si los datos de usuario emiten un reinicio del equipo o si los datos de usuario se interrumpieron durante la ejecución, el estado de ejecución persiste como `pending` y los datos de usuario se ejecutarán de nuevo en el siguiente arranque de la instancia. Si deseas evitar que el script de datos del usuario se ejecute más de una vez, haz que el script sea idempotente. El siguiente ejemplo de scripts idempotentes establece el nombre del equipo y se une a un dominio. ``` $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" } false ``` ### Las tareas programadas de EC2Launch v1 no se pueden ejecutar después de la migración a EC2Launch v2 **Resolución** La herramienta de migración no detecta ninguna tarea programada que esté vinculada a scripts de EC2Launch v1; por lo tanto, no configura automáticamente dichas tareas en EC2Launch v2. Para configurar dichas tareas, edita el archivo [`agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) o utiliza el [Cuadro de diálogo configuración de EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-ui). Por ejemplo, si una instancia tiene una tarea programada que ejecuta `InitializeDisks.ps1`, después de ejecutar la herramienta de migración debe especificar los volúmenes que desea iniciar en el cuadro de diálogo configuración de EC2Launch v2. Consulte el paso 6 del procedimiento para [Cambiar la configuración mediante el cuadro de diálogo de configuración de EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-ui). ### El servicio inicializa un volumen EBS que no está vacío **Resolución** Antes de inicializar un volumen, EC2Launch v2 intenta detectar si está vacío. Si un volumen no está vacío, omite la inicialización. Los volúmenes que se detecten como no vacíos no se inicializan. Un volumen se considera vacío si los primeros 4 KB de un volumen están vacíos, o si un volumen no tiene un [diseño de unidad reconocible por Windows](https://learn.microsoft.com/en-us/windows/win32/api/winioctl/ns-winioctl-drive_layout_information_ex). Un volumen que se inicializó y formateó en un sistema Linux no tiene un diseño de unidad reconocible por Windows, por ejemplo MBR o GPT. Por lo tanto, se considerará vacío e inicializado. Si desea conservar estos datos, no dependa de la detección de unidades vacías de EC2Launch v2. En lugar de ello, especifique los volúmenes que desea inicializar en el [cuadro de diálogo de configuración de EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-ui) (consulte el paso 6) o en [`agent-config.yml`](ec2launch-v2-task-definitions.md#ec2launch-v2-initializevolume). ### `setWallpaper`La tarea no está habilitada pero el fondo de pantalla se restablece al reiniciar La tarea `setWallpaper` crea el archivo de acceso directo `setwallpaper.lnk` en la carpeta de startup de cada usuario existente. Este archivo de acceso directo se ejecuta cuando el usuario inicia sesión por primera vez después del arranque de la instancia. Configura la instancia con un fondo de pantalla personalizado que muestra los atributos de la instancia. Tenga en cuenta que quitar la tarea `setWallpaper` no elimina este archivo de acceso directo. Elimine manualmente este archivo o mediante un script. La ruta del acceso directo es: `$env:SystemDrive/Users//AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk` **Resolución** Elimine manualmente este archivo o mediante un script. **Ejemplo de script de PowerShell para eliminar un archivo de acceso directo** ``` 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 } } } ``` ### Servicio atascado en estado de ejecución **Descripción** EC2Launch v2 se bloquea y presenta mensajes de registro (`agent.log`) similares a los siguientes: ``` 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. ``` **Causa posible** SAC está habilitado y utiliza el puerto serie. Para obtener más información, consulte [Usar SAC para solucionar problemas de su instancia de Windows](troubleshoot-using-serial-console.md#troubleshooting-sac). **Resolución** Pruebe los siguientes pasos para resolver este problema: + Desactive el servicio que esté utilizando el puerto serie. + Si desea que el servicio siga utilizando el puerto serie, escriba scripts personalizados para realizar tareas del agente de inicialización e invóquelas como tareas programadas. ### `agent-config.yml` no válido impide que se abra el cuadro de diálogo de configuración de EC2Launch v2 **Descripción** La configuración de EC2Launch v2 intenta analizar el archivo `agent-config.yml` antes de abrir el cuadro de diálogo. Si el archivo de configuración YAML no sigue el esquema admitido, el cuadro de diálogo mostrará el siguiente error: `Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.` **Resolución** 1. Compruebe que el archivo de configuración sigue el [esquema admitido](ec2launch-v2-settings.md#ec2launch-v2-schema-agent-config). 1. Si desea comenzar desde cero, copie el archivo de configuración predeterminado en `agent-config.yml`. Puede utilizar el [ejemplo `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config) que se proporciona en la sección Task Configuration (Configuración de tareas). 1. También puede comenzar de nuevo eliminando `agent-config.yml`. La configuración de EC2Launch v2 genera un archivo de configuración vacío. ### `task:executeScript should be unique and only invoked once` **Descripción** No es posible repetir una tarea en la misma etapa. **Resolución** Algunas tareas deben introducirse como una matriz, como [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript) y [**executeProgram**](ec2launch-v2-task-definitions.md#ec2launch-v2-executeprogram). Para ver un ejemplo de cómo escribir el script como una matriz, consulte [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript). ## Registros de eventos de Windows EC2Launch v2 publica registros de eventos de Windows para eventos importantes, como el inicio del servicio, la preparación de Windows para empezar a funcionar y el éxito y el error de la tarea. Los identificadores de eventos identifican de forma única un evento en particular. Cada evento contiene información de etapa, tarea y nivel, así como una descripción. Puede establecer desencadenadores para eventos específicos mediante el identificador de evento. Los ID de eventos proporcionan información sobre un evento e identifican de forma única algunos eventos. El dígito menos significativo de un ID de evento indica la gravedad de un evento. | Evento | Dígito menos significativo | | --- | --- | | Success | . . .0 | | Informational | . . .1 | | Warning | . . .2 | | Error | . . .3 | Los eventos relacionados con el servicio que se generan cuando se inicia o se detiene el servicio incluyen un identificador de evento de un solo dígito. | Evento | Identificador de un solo dígito | | --- | --- | | Success | 0 | | Informational | 1 | | Warning | 2 | | Error | 3 | Los mensajes de eventos para eventos `EC2LaunchService.exe` comienzan por `Service:`. Los mensajes de eventos para eventos `EC2Launch.exe` no comienzan por `Service:`. Los ID de eventos de cuatro dígitos incluyen información sobre la fase, la tarea y la gravedad de un evento. **Topics** + [Formato de ID de evento](#ec2launchv2-windows-event-logs-format) + [Ejemplos de ID de evento](#ec2launchv2-windows-event-logs-id-examples) + [Esquema de registro de eventos de Windows](#ec2launch-v2-windows-event-logs-schema) ### Formato de ID de evento La siguiente tabla muestra el formato del identificador de un evento de EC2Launch v2. | 3 | 2 1 | 0 | | --- | --- | --- | | S | T | L | Las letras y números de la tabla representan el tipo de evento y las definiciones siguientes. | Tipo de evento | Definición | | --- | --- | | S (Etapa) | 0 - Mensaje de nivel de servicio 1 - Arranque 2 - Red 3 - Pre-Ready 5 - Windows está listo 6 - PostReady 7 - Datos de usuario | | T (Tarea) | Las tareas representadas por los dos valores correspondientes son distintas para cada etapa. Para ver la lista completa de eventos, consulte [Esquema de registro de eventos de Windows](#ec2launch-v2-windows-event-logs-schema). | | L (Nivel del evento) | 0 - Éxito 1 - Informativo 2 - Advertencia 3 - Error | ### Ejemplos de ID de evento A continuación se presentan identificadores de evento de ejemplo. + `5000`: Windows está listo para usar + `3010`: la tarea de activación de Windows en la etapa PreReady se ha realizado correctamente + `6013`: la tarea Establecer fondo de pantalla en la etapa PostReady Local Data encontró un error ### Esquema de registro de eventos de Windows | ID de mensaje/evento | Mensaje de 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\$1root\$1partition | | 2000 | Network | | 2010 | Network - add\$1routes | | 3000 | PreReady | | 3010 | PreReady - activate\$1windows | | 3020 | PreReady - install\$1egpu\$1manager | | 3030 | PreReady - set\$1monitor\$1on | | 3040 | PreReady - set\$1hibernation | | 3050 | PreReady - set\$1admin\$1account | | 3060 | PreReady - set\$1dns\$1suffix | | 3070 | PreReady - set\$1wallpaper | | 3080 | PreReady - set\$1update\$1schedule | | 3090 | PreReady - output\$1log | | 3100 | PreReady - enable\$1open\$1ssh | | 5000 | Windows is Ready to use | | 6000 | PostReadyLocalData | | 7000 | PostReadyUserData | | 6010/7010 | PostReadyLocal/UserData - set\$1wallpaper | | 6020/7020 | PostReadyLocal/UserData - set\$1update\$1schedule | | 6030/7030 | PostReadyLocal/UserData - set\$1hostname | | 6040/7040 | PostReadyLocal/UserData - execute\$1program | | 6050/7050 | PostReadyLocal/UserData - execute\$1script | | 6060/7060 | PostReadyLocal/UserData - manage\$1package | | 6070/7070 | PostReadyLocal/UserData - initialize\$1volume | | 6080/7080 | PostReadyLocal/UserData - write\$1file | | 6090/7090 | PostReadyLocal/UserData - start\$1ssm | | 7100 | PostReadyUserData - enable\$1open\$1ssh | | 6110/7110 | PostReadyLocal/UserData - enable\$1jumbo\$1frames | ## Salida del registro de la consola de EC2Launch v2 Esta sección contiene una salida del registro de la consola de ejemplo de EC2Launch v2 y muestra todos los mensajes de error del registro de la consola de EC2Launch v2 para ayudarle a solucionar problemas. Para obtener más información sobre la salida de la consola de instancias y cómo acceder a ella, consulte [Salida de la consola de instancias](troubleshoot-unreachable-instance.md#instance-console-console-output). **Topics** + [Salida del registro de la consola de EC2Launch v2](#ec2launchv2-console-log-output) + [Mensajes de registro de la consola de EC2Launch v2](#ec2launchv2-console-log-messages) ### Salida del registro de la consola de EC2Launch v2 A continuación, se muestra una salida del registro de la consola de ejemplo de EC2Launch v2. Algunos valores de este ejemplo se sustituyen por texto representativo entre llaves. ``` 2025/07/22 21:26:53Z: Windows sysprep configuration complete. 2025/07/22 21:26:53Z: Message: Waiting for access to metadata... 2025/07/22 21:26:53Z: Message: Meta-data is now available. 2025/07/22 21:26:53Z: AMI Origin Version: 2024.12.13 2025/07/22 21:26:53Z: AMI Origin Name: Windows_Server-2022-English-Full-Base 2025/07/22 21:26:53Z: OS: Microsoft Windows NT 10.0.20348 2025/07/22 21:26:53Z: OsVersion: 10.0 2025/07/22 21:26:53Z: OsProductName: Windows Server 2022 Datacenter 2025/07/22 21:26:53Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500 2025/07/22 21:26:53Z: OsCurrentBuild: 20348 2025/07/22 21:26:53Z: OsReleaseId: 2009 2025/07/22 21:26:53Z: Language: en-US 2025/07/22 21:26:53Z: TimeZone: UTC 2025/07/22 21:26:53Z: Offset: UTC +0000 2025/07/22 21:26:53Z: Launch: EC2 Launch v2.2.63 2025/07/22 21:26:53Z: AMI-ID: ami-1234567890abcdef1 2025/07/22 21:26:53Z: Instance-ID: i-1234567890abcdef0 2025/07/22 21:26:54Z: Instance Type: t3.xlarge 2025/07/22 21:26:54Z: Driver: AWS NVMe Driver v1.6.0.35 2025/07/22 21:26:54Z: SubComponent: 1.6.0.35; EnableSCSIPersistentReservations: 0 2025/07/22 21:26:54Z: Driver: AWS PV Driver Package v8.5.0 2025/07/22 21:26:55Z: Driver: Amazon Elastic Network Adapter v2.8.0.0 2025/07/22 21:26:55Z: HOSTNAME: EC2AMAZ-9FJG5CC 2025/07/22 21:26:55Z: RDPCERTIFICATE-SUBJECTNAME: {certificate subject name} 2025/07/22 21:26:55Z: RDPCERTIFICATE-THUMBPRINT: {thumbprint hash} 2025/07/22 21:26:56Z: SSM: Amazon SSM Agent v3.3.2746.0 2025/07/22 21:26:57Z: User data format: no_user_data 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsTelemetryEnabled=true 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentCommandErrorCode=1 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentErrorLocation=execute_windows.go:410 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IpConflictDetectionCode=0 2025/07/22 21:26:57Z: Message: Windows is Ready to use {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...} {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...} ``` ### Mensajes de registro de la consola de EC2Launch v2 A continuación, se muestra una lista de todos los mensajes de registro de la consola de EC2Launch v2. ``` Error EC2Launch service is stopping. {error message} ``` Detalles del error de servicio detenido: + `Error setting up EC2Launch agent folders` + `See instance logs for detail` + `Error stopping service` + `Error initializing service` ``` Windows sysprep configuration complete ``` ``` Invalid administrator username: {invalid username} ``` ``` Invalid administrator password Username: {username} Password: {encrypted password} ``` El siguiente mensaje es un bloque de información que contiene detalles de la AMI: ``` 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} HOSTNAME: {computer name} 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} SSM: Amazon SSM Agent {version} AWS VSS Version: {version} ``` ``` Windows sysprep configuration complete. Windows is being configured. 'SysprepState is {state}' Windows is still being configured. 'SysprepState is {state}' Windows is Ready to use Waiting for access to metadata... Meta-data is now available. Metadata is not available for this instance. Timed out waiting for access to metadata. User data format: {format} ``` Los mensajes de telemetría de EC2Launch v2 incluyen los valores de las propiedades de telemetría de lanzamiento. A partir de la versión 2.2.63, los datos de telemetría de agentes de EC2 se formatean como un objeto JSON. ``` EC2LaunchTelemetry: {telemetry property} ``` ``` {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... } ```