Ejecutar comandos en la instancia de Windows durante el lanzamiento - Amazon Elastic Compute Cloud

Ejecutar comandos en la instancia de Windows durante el lanzamiento

Al lanzar una instancia de Windows al usar Amazon EC2, los datos de usuario se pueden transmitir a la instancia y se pueden utilizar para realizar tareas de configuración automáticas o ejecutar scripts después de que se inicie la instancia. Los datos de usuario de la instancia se tratan como datos opacos; la instancia es quien debe interpretarlos. EC2Launch v2 procesa los datos de usuario en Windows Server 2022 y versiones anteriores y EC2Launch los procesa en Windows Server 2016 y 2019 y versiones posteriores, y EC2Config en Windows Server 2012 R2 y versiones anteriores.

Para obtener ejemplos del ensamblado de una propiedad UserData en una plantilla deAWS CloudFormation, consulte Propiedad UserData cifrada en Base64 y Propiedad UserData cifrada en Base64 con AccessKey y SecretKey.

Para obtener información acerca de cómo ejecutar comandos en su instancia de Linux durante el lanzamiento, consulte Ejecución de comandos en la instancia de Linux durante el lanzamiento en la Guía del usuario de Amazon EC2 para instancias de Linux.

Para ver un ejemplo de ejecución de comandos en una instancia de Auto Scaling que funcionan con enlaces de ciclo de vida, consulte el Tutorial: Configurar datos de usuario para recuperar el estado de ciclo de vida de destino a través de los metadatos de la instancia en la Guía del usuario de Amazon EC2 Auto Scaling.

Scripts de datos de usuario

Para que EC2Config o EC2Launch ejecuten scripts, debe incluir el script dentro de una etiqueta especial al añadirlo a los datos de usuario. La etiqueta que se utiliza depende de si los comandos se ejecutan en una ventana del símbolo del sistema (comandos por lotes) o con Windows PowerShell.

Si se especifica tanto un script de procesamiento por lotes como un script de Windows PowerShell, el script por lotes se ejecuta en primer lugar y después lo hace el script de Windows PowerShell, independientemente del orden en el que aparezcan en los datos de usuario de la instancia.

Si utiliza una API de AWS, incluida la AWS CLI, en un script de datos del usuario, debe utilizar un perfil de instancia al lanzar la instancia. Un perfil de instancia proporciona las credenciales de AWS adecuadas requeridas por el script de datos de usuario para ejecutar la llamada a la API. Para obtener más información, consulte Perfiles de instancias. Los permisos que asigne al rol de IAM dependen de los servicios a los que llame con la API. Para obtener más información, consulte Roles de IAM para Amazon EC2.

Sintaxis de los scripts de procesamiento por lotes

Especifique un script de procesamiento por lotes con la etiqueta script. Separe los comandos mediante saltos de línea, como se muestra en el siguiente ejemplo.

<script> echo Current date and time >> %SystemRoot%\Temp\test.log echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log </script>

De forma predeterminada, los scripts de datos de usuario se ejecutan solo una vez, cuando se lanza la instancia. Para ejecutarlos cada vez que se lanza o se reinicia la instancia, añade <persist>true</persist> a los datos de usuario.

<script> echo Current date and time >> %SystemRoot%\Temp\test.log echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log </script> <persist>true</persist>
Agente EC2Launch v2

Para ejecutar un script de datos de usuario XML como un proceso independiente con la tarea executeScript de EC2Launch v2 en la etapa UserData, agregue la siguiente etiqueta a sus datos de usuario.

<detach>true</detach>

nota

La etiqueta de desconexión no es compatible con los agentes de lanzamiento anteriores.

<script> echo Current date and time >> %SystemRoot%\Temp\test.log echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log </script> <detach>true</detach>

Sintaxis de los scripts de Windows PowerShell

Las AMI de Windows de AWS incluyen las AWS Tools for Windows PowerShell, por lo que puede especificar estos cmdlets en los datos de usuario. Si asocia un rol de IAM a la instancia, no es necesario especificar credenciales para los cmdlets, ya que las aplicaciones que se ejecutan en la instancia pueden utilizar las credenciales del rol para obtener acceso a los recursos de AWS (por ejemplo, los buckets de Amazon S3).

Especifique un script de Windows PowerShell con la etiqueta <powershell>. Separe los comandos con saltos de línea. La etiqueta <powershell> no distingue entre mayúsculas y minúsculas.

Por ejemplo:

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

De forma predeterminada, los scripts de datos de usuario se ejecutan solo una vez, cuando se lanza la instancia. Para ejecutarlos cada vez que se lanza o se reinicia la instancia, añade <persist>true</persist> a los datos de usuario.

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

Para ejecutar un script de datos de usuario XML como un proceso independiente con la tarea executeScript de EC2Launch v2 en la etapa UserData, agregue la siguiente etiqueta a sus datos de usuario.

<detach>true</detach>

nota

La etiqueta de desconexión no es compatible con los agentes de lanzamiento anteriores.

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

Sintaxis de los scripts de configuración de YAML

Si está utilizando EC2Launch v2 para ejecutar scripts, puede utilizar el formato YAML. Para ver tareas de configuración, detalles y ejemplos de EC2Launch v2, consulte Configuración de tareas de EC2Launch v2.

Especifique una secuencia de comandos YAML con el paso executeScript.

Ejemplo de sintaxis de YAML para ejecutar un script de PowerShell

version: 1.0 tasks: - task: executeScript inputs: - frequency: always type: powershell runAs: localSystem content: |- $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file

Ejemplo de sintaxis YAML para ejecutar un script por lotes

version: 1.1 tasks: - task: executeScript inputs: - frequency: always type: batch runAs: localSystem content: |- echo Current date and time >> %SystemRoot%\Temp\test.log echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log

Codificación Base64

Si utiliza Amazon EC2 API o una herramienta que no realice codificación base64 de los datos de usuario, debe codificar los datos de usuario usted mismo. De lo contrario, se registra un error por imposibilidad de encontrar etiquetas script o powershell para ejecutar. A continuación se ofrece un ejemplo de codificación con Windows PowerShell.

$UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

A continuación se ofrece un ejemplo de descodificación con PowerShell.

$Script = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData))

Para obtener más información acerca de la codificación base64, consulte https://www.ietf.org/rfc/rfc4648.txt.

Ejecución de datos de usuario

De forma predeterminada, todas las AMI de Windows de AWS tienen habilitada la ejecución de datos de usuario para el lanzamiento inicial. Puede especificar que los scripts de datos de usuario se ejecuten la próxima vez que la instancia se inicie o reinicie. O puede especificar que los scripts de datos de usuario se ejecuten cada vez que la instancia se inicie o reinicie.

nota

Los datos de usuario no están habilitados para ejecutarse de forma predeterminada después del lanzamiento inicial. Para permitir que los datos de usuario se ejecuten al reiniciar o iniciar la instancia, consulte Inicios o reinicios posteriores.

Los scripts de datos de usuario se ejecutan desde la cuenta del administrador local cuando se genera una contraseña aleatoria. De lo contrario, los scripts de datos de usuario se ejecutan desde la cuenta Sistema.

Lanzamiento de la instancia

Los scripts de los datos de usuario de la instancia se ejecutan durante el lanzamiento inicial de la instancia. Si se encuentra la etiqueta persist, significa que la ejecución de los datos de usuario está habilitada para inicios o reinicios posteriores. Los archivos de registro de EC2Launch v2, EC2Launch y EC2Config contienen información del resultado estándar y las secuencias de error estándar.

EC2Launch v2

El archivo de registro de EC2Launch v2 es C:\ProgramData\Amazon\EC2Launch\log\agent.log.

nota

Es posible que la carpeta C:\ProgramData esté oculta. Para ver la carpeta, debe mostrar los archivos y las carpetas ocultos.

Al ejecutar los datos de usuario, se registra la información siguiente:

  • Info: Converting user-data to yaml format: si los datos del usuario se proporcionaron en formato XML

  • Info: Initialize user-data state: el inicio de la ejecución de datos de usuario

  • Info: Frequency is: always: si la tarea de datos de usuario se está ejecutando en cada arranque

  • Info: Frequency is: once: si la tarea de datos de usuario se está ejecutando una sola vez

  • Stage: postReadyUserData execution completed: el final de la ejecución de datos de usuario

EC2Launch

El archivo de registro de EC2Launch es C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log.

Es posible que la carpeta C:\ProgramData esté oculta. Para ver la carpeta, debe mostrar los archivos y las carpetas ocultos.

Al ejecutar los datos de usuario, se registra la información siguiente:

  • Userdata execution begins: el inicio de la ejecución de datos de usuario

  • <persist> tag was provided: true: si se encuentra la etiqueta persistir

  • Running userdata on every boot: si se encuentra la etiqueta persistir

  • <powershell> tag was provided.. running powershell content: si se encuentra la etiqueta powershell

  • <script> tag was provided.. running script content: si se encuentra la etiqueta script

  • Message: The output from user scripts: si se ejecutan scripts de datos de usuario, se registra su salida

EC2Config

El archivo de registro de EC2Config es C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log. Al ejecutar los datos de usuario, se registra la información siguiente:

  • Ec2HandleUserData: Message: Start running user scripts: el inicio de la ejecución de datos de usuario

  • Ec2HandleUserData: Message: Re-enabled userdata execution: si se encuentra la etiqueta persistir

  • Ec2HandleUserData: Message: Could not find <persist> and </persist>: si no se encuentra la etiqueta persistir

  • Ec2HandleUserData: Message: The output from user scripts: si se ejecutan scripts de datos de usuario, se registra su salida

Inicios o reinicios posteriores

Cuando se actualizan los datos de usuario de la instancia, los scripts de datos de usuario no se ejecutan automáticamente al iniciar o reiniciar la instancia. Sin embargo, puede habilitar la ejecución de los datos de usuario para que los scripts que los contienen se ejecuten una sola vez al iniciar o reiniciar la instancia, o bien cada vez que esta se inicie o se reinicie.

Si elige la opción Cerrar con Sysprep, los scripts de datos de usuario se ejecutarán la próxima vez que comience o se reinicie la instancia, aunque no se haya habilitado la ejecución de los datos de usuario para comienzos o reinicios posteriores. Los scripts de datos de usuario no se ejecutarán en reinicios o comienzos posteriores.

Habilitar la ejecución de datos de usuario con EC2Launch v2 (Vista previa de las AMI)
  • Ejecutar una tarea en los datos de usuario en el primer arranque, establezca frequency en once.

  • Ejecutar una tarea en los datos de usuario en cada arranque, establezca frequency en always.

Habilitar la ejecución de datos de usuario en Windows Server 2016 o versiones posteriores (EC2Launch)
  1. Conéctese a la instancia de Windows.

  2. Abra una ventana de comandos de PowerShell y ejecute el comando siguiente:

    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -Schedule
  3. Desconéctese de la instancia de Windows. Para ejecutar los scripts actualizados la próxima vez que se inicie la instancia, detén la instancia y actualiza los datos de usuario. Para obtener más información, consulte Visualizar y actualizar los datos de usuario de la instancia.

Habilitar la ejecución de datos de usuario en Windows Server 2012 EC2Config y versiones anteriores (R2)
  1. Conéctese a la instancia de Windows.

  2. Abrir C:\Program Files\Amazon\Ec2ConfigService\Ec2ConfigServiceSetting.exe.

  3. En User Data (Datos de usuario), seleccione Enable UserData execution for next service start (Habilitar la ejecución de datos de usuario en el siguiente inicio de servicio).

  4. Desconéctese de la instancia de Windows. Para ejecutar los scripts actualizados la próxima vez que se inicie la instancia, detén la instancia y actualiza los datos de usuario. Para obtener más información, consulte Visualizar y actualizar los datos de usuario de la instancia.

Datos de usuario y la consola

Puede especificar los datos de usuario de la instancia al lanzar la instancia. Si el volumen raíz de la instancia es un volumen de EBS, también puede detener la instancia y actualizar los datos de usuario.

Especificar los datos de usuario de la instancia durante el lanzamiento

Siga el procedimiento para lanzar una instancia. El campo User data (Datos de usuario) se encuentra en la sección Detalles avanzados del asistente de lanzamiento de instancias. Ingrese el script de shell en el campo User data y, a continuación, complete el procedimiento de lanzamiento de instancias.

En la siguiente captura de pantalla del campo de datos del usuario, la secuencia de comandos de ejemplo crea un archivo en la carpeta temporal de Windows, utilizando la fecha y la hora actuales en el nombre del archivo. Al incluir <persist>true</persist>, el script se ejecuta cada vez que comienzas o reinicias la instancia. Si deja vacía la casilla Los datos del usuario ya están codificados en base64, la consola Amazon EC2 realizará la codificación en base64 por usted.


					Campo de texto de datos del usuario de Advance Details (Detalles avanzados).

Visualizar y actualizar los datos de usuario de la instancia

Puede ver los datos de usuario de cualquier instancia y actualizarlos en las instancias detenidas.

Para actualizar los datos de usuario de una instancia con la consola
  1. Abra la consola de Amazon EC2 en https://console.aws.amazon.com/ec2/.

  2. En el panel de navegación, seleccione Instances (Instancias).

  3. Seleccione la instancia y elija Actions (Acciones), Instance State (Estado de la instancia) y Stop instance (Detener instancia).

    aviso

    Cuando detiene una instancia, se borran los datos contenidos en todos los volúmenes de almacén de instancias. Para conservar los datos de los volúmenes del almacén de instancias, asegúrese de realizar una copia de seguridad de ellos en un almacenamiento persistente.

  4. Cuando se le pida que confirme, elija Stop. Puede que transcurran unos minutos hasta que la instancia se detenga.

  5. Con la instancia aún seleccionada, elija Actions (Acciones), Instance Settings (Configuración de la instancia) y Edit user data (Editar datos del usuario). Los datos de usuario no se pueden cambiar si la instancia se está ejecutando, pero puede verlos.

  6. En el cuadro de diálogo Modificar datos del usuario, actualiza los datos de usuario y a continuación selecciona Guardar. Para ejecutar los scripts de datos de usuario cada vez que comienzas o reinicias la instancia, agrega <persist>true</persist>, tal como se muestra en el siguiente ejemplo:

    
							Cuadro de diálogo Edit User Data (Editar datos de usuario).
  7. Inicie la instancia. Si habilitaste la ejecución de los datos de usuario para arranques o reinicios posteriores, los scripts de datos de usuario actualizados se ejecutan como parte del proceso de inicio de la instancia.

Datos de usuario y las Tools for Windows PowerShell

Puede usar la Tools for Windows PowerShell para especificar, modificar y ver los datos de usuario de la instancia. Para obtener más información acerca de cómo ver los datos de usuario de la instancia usando los metadatos de la instancia, consulte Recuperación de los datos de usuario de la instancia desde su instancia. Para obtener más información acerca de los datos de usuario y de AWS CLI, consulte Datos de usuario y de AWS CLI en Guía del usuario de Amazon EC2 para instancias de Linux.

Ejemplo: Especificar los datos de usuario de la instancia durante el lanzamiento

Cree un archivo de texto con los datos de usuario de la instancia. Para ejecutar los scripts de datos de usuario cada vez que arrrancas o reinicias la instancia, agrega <persist>true</persist>, tal como se muestra en el siguiente ejemplo.

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

Para especificar los datos de usuario de la instancia cuando lanza la instancia, use el comando New-EC2Instance. Este comando no realiza codificación base64 de los datos de usuario. Para codificar los datos de usuario en un archivo de texto llamado script.txt, utilice los siguientes comando.

PS C:\> $Script = Get-Content -Raw script.txt PS C:\> $UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

Utilice el parámetro -UserData para pasar los datos de usuario al comando New-EC2Instance.

PS C:\> New-EC2Instance -ImageId ami-abcd1234 -MinCount 1 -MaxCount 1 -InstanceType m3.medium \ -KeyName my-key-pair -SubnetId subnet-12345678 -SecurityGroupIds sg-1a2b3c4d \ -UserData $UserData
Ejemplo: Actualizar los datos de usuario de una instancia detenida

Puede modificar los datos de usuario de una instancia detenida utilizando el comando Edit-EC2InstanceAttribute.

Cree un archivo de texto con el nuevo script. Para codificar los datos de usuario en el archivo de texto llamado new-script.txt, utilice los siguientes comando.

PS C:\> $NewScript = Get-Content -Raw new-script.txt PS C:\> $NewUserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($NewScript))

Utilice los parámetros -UserData y -Value para especificar los datos de usuario.

PS C:\> Edit-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData -Value $NewUserData
Ejemplo: Ver los datos de usuario de la instancia

Para recuperar los datos de usuario de una instancia, utilice el comando Get-EC2InstanceAttribute.

PS C:\> (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData

A continuación, se muestra un ejemplo del resultado. Tenga en cuenta que los datos de usuario están codificados.

PHBvd2Vyc2hlbGw+DQpSZW5hbWUtQ29tcHV0ZXIgLU5ld05hbWUgdXNlci1kYXRhLXRlc3QNCjwvcG93ZXJzaGVsbD4=

Para almacenar los datos de usuario codificados en una variable y luego decodificarlos, utilice los siguientes comandos.

PS C:\> $UserData_encoded = (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData PS C:\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData_encoded))

A continuación, se muestra un ejemplo del resultado.

<powershell> $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell> <persist>true</persist>
Ejemplo: Cambiar el nombre a la instancia para que coincida con el valor de la etiqueta

Puede utilizar el comando Get-EC2Tag para leer el valor de la etiqueta, cambiar el nombre a la instancia durante el primer arranque para que coincida con el valor de la etiqueta y reiniciar. Para ejecutar este comando correctamente, debe tener un rol con permisos ec2:DescribeTags adjunto a la instancia, porque la información de etiquetas se recupera mediante una llamada a la API. Para obtener más información acerca de los permisos de configuración mediante roles de IAM, consulte Adjuntar un rol de IAM a una instancia.

nota

Este script falla en versiones de Windows Server anteriores a 2008.

<powershell> $instanceId = (invoke-webrequest http://169.254.169.254/latest/meta-data/instance-id -UseBasicParsing).content $nameValue = (get-ec2tag -filter @{Name="resource-id";Value=$instanceid},@{Name="key";Value="Name"}).Value $pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$" #Verify Name Value satisfies best practices for Windows hostnames If ($nameValue -match $pattern) {Try {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} Catch {$ErrorMessage = $_.Exception.Message Write-Output "Rename failed: $ErrorMessage"}} Else {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"} </powershell>

También puede cambiar el nombre de la instancia mediante etiquetas en los metadatos de la instancia, si la instancia está configurada para etiquetas de acceso desde los metadatos de instancia.

nota

Este script falla en versiones de Windows Server anteriores a 2008.

<powershell> $nameValue = Get-EC2InstanceMetadata -Path /tags/instance/Name $pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$" #Verify Name Value satisfies best practices for Windows hostnames If ($nameValue -match $pattern) {Try {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} Catch {$ErrorMessage = $_.Exception.Message Write-Output "Rename failed: $ErrorMessage"}} Else {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"} </powershell>