Executar comandos na instância do Windows no lançamento - Amazon Elastic Compute Cloud
Scripts de dados do usuárioExecução de dados do usuárioDados do usuário e consoleDados do usuário e Tools for Windows PowerShell

Executar comandos na instância do Windows no lançamento

Ao executar uma instância do Windows usando o Amazon EC2, é possível passar os dados do usuário para a instância que pode ser usada para realizar tarefas de configuração automatizadas ou executar scripts após a inicialização da instância. Os dados do usuário da instância são tratados como dados opacos, cabe à instância interpretá-los. Os dados do usuário são processados pelo EC2Config v2 no Windows Server 2022, EC2Launch no Windows Server 2016 e2019, e EC2Config no Windows Server 2012 R2 e anteriores.

Para obter exemplos de assembly de uma propriedade UserData em um modelo do AWS CloudFormation, consulte Propriedade UserData codificada em Base64 e Propriedade UserData codificada em Base64 com AccessKey e SecretKey.

Para obter informações sobre a execução de comandos na instância do Linux no lançamento, consulte Executar comandos na instância do Linux no lançamento no Guia do usuário do Amazon EC2 para instâncias do Linux.

Para ver um exemplo de comandos de execução em uma instância dentro de um Auto Scaling que funciona com ganchos do ciclo de vida, consulte Tutorial: configurar dados do usuário para recuperar o estado de destino do ciclo de vida por meio de metadados de instância no Guia do usuário do Amazon EC2 Auto Scaling.

Scripts de dados do usuário

Para que o EC2Config ou o EC2Launch execute scripts, será necessário colocar o script em uma tag especial ao adicioná-lo aos dados do usuário. A tag usada depende de os comandos serem executados em uma janela de prompt de comando (comandos de lote) ou usando o Windows PowerShell.

Se você especificar um script em lote e um script do Windows PowerShell, o script em lote é executado primeiro e o script do Windows PowerShell é executado em seguida, independentemente da ordem em que eles aparecem nos dados do usuário da instância.

Se você usar uma API da AWS, incluindo a AWS CLI, em um script de dados de usuário, deverá usar um perfil de instância ao inicializar a instância. Um perfil de instância fornece as credenciais apropriadas da AWS exigidas pelo script de dados do usuário para executar a chamada de API. Para ter mais informações, consulte Perfis de instância. As permissões que atribui à função do IAM dependem de quais serviços você chama com a API. Para obter mais informações, consulte Funções do IAM para Amazon EC2.

Sintaxe para scripts em lote

Especifique um script em lote usando a tag script. Separe os comandos usando quebras de linha, conforme mostrado no exemplo a seguir.

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

Por padrão, os scripts de dados do usuário são executados uma vez ao inicializar a instância. Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione <persist>true</persist> aos dados do usuário.

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

Para executar um script XML de dados do usuário como um processo separado com a tarefa executeScript do EC2Launch v2 no estágio UserData, adicione a tag a seguir aos dados do usuário.

<detach>true</detach>

nota

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

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

Sintaxe para scripts do Windows PowerShell

As AMIs do Windows da AWS incluem o AWS Tools for Windows PowerShell para que você possa especificar esses cmdlets nos dados do usuário. Se você associar uma função do IAM à sua instância, não será necessário especificar as credenciais para os cmdlets, pois os aplicações em execução na instância usam as credenciais da função para acessar os recursos da AWS (por exemplo, buckets do Amazon S3).

Especifique um script do Windows PowerShell usando a tag <powershell>. Separe os comandos usando quebras de linha. A tag <powershell> não diferencia maiúsculas de minúsculas.

Por exemplo:

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

Por padrão, os scripts de dados do usuário são executados uma vez ao inicializar a instância. Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione <persist>true</persist> aos dados do usuário.

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

Para executar um script XML de dados do usuário como um processo separado com a tarefa executeScript do EC2Launch v2 no estágio UserData, adicione a tag a seguir aos dados do usuário.

<detach>true</detach>

nota

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

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

Sintaxe para scripts de configuração YAML

Se você estiver usando o EC2Launch v2 para executar scripts, poderá usar o formato YAML. Para visualizar tarefas de configuração, detalhes e exemplos do EC2Launch v2, consulte Configuração de tarefas do EC2Launch v2.

Especifique um script YAML com a tarefa executeScript.

Exemplo de sintaxe do YAML para executar um script do 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

Exemplo de sintaxe do YAML para executar um script em lote

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

Codificação base64

Se você estiver usando a API do Amazon EC2 ou uma ferramenta que não execute codificação base64 dos dados do usuário, codifique você mesmo os dados do usuário. Caso contrário, será registrado um erro sobre não ser possível encontrar as tags script ou powershell para executar. A seguir está um exemplo que codifica usando o Windows PowerShell.

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

A seguir está um exemplo que decodifica usando o PowerShell.

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

Para obter mais informações sobre a codificação base64, consulte https://www.ietf.org/rfc/rfc4648.txt.

Execução de dados do usuário

Por padrão, todas as AMIs do Windows da AWS têm a execução de dados de usuário habilitada para a execução inicial. É possível especificar que os scripts de dados do usuário sejam executados na próxima vez que a instância for reiniciada. Também é possível especificar que os scripts de dados do usuário sejam executados toda vez que a instância for reiniciada.

nota

Os dados do usuário não são habilitados para execução por padrão após a inicialização inicial. Para permitir que os dados do usuário sejam executados ao reinicializar ou iniciar a instância, consulte Reinicializações ou inicializações subsequentes.

Os scripts de dados do usuário são executados na conta do administrador local quando uma senha aleatória é gerada. Caso contrário, os scripts de dados do usuário são executados na conta do sistema.

Execução da instância

Os scripts nos dados do usuário da instância são executados durante a execução inicial da instância. Se a tag persist for localizada, a execução de dados do usuário será habilitada para reinicializações ou inicializações subsequentes. Os arquivos de log do EC2Launch v2, EC2Launch e EC2Config contêm a saída da saída padrão e dos fluxos de erro padrão.

EC2Launch v2

O arquivo de log para EC2Launch v2 é C:\ProgramData\Amazon\EC2Launch\log\agent.log.

nota

A pasta C:\ProgramData pode estar oculta. Para visualizar a pasta, é necessário mostrar arquivos e pastas ocultos.

As informações a seguir são registradas quando os dados do usuário são executados.

  • Info: Converting user-data to yaml format – Se os dados do usuário tiverem sido fornecidos no formato XML

  • Info: Initialize user-data state: o início da execução de dados do usuário

  • Info: Frequency is: always – Se a tarefa de dados do usuário estiver sendo executada em cada inicialização

  • Info: Frequency is: once – Se a tarefa de dados do usuário estiver sendo executada apenas uma vez

  • Stage: postReadyUserData execution completed – O final da execução de dados do usuário

EC2Launch

O arquivo de log do EC2Launch é C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log.

A pasta C:\ProgramData pode estar oculta. Para visualizar a pasta, é necessário mostrar arquivos e pastas ocultos.

As informações a seguir são registradas quando os dados do usuário são executados.

  • Userdata execution begins: o início da execução de dados do usuário

  • <persist> tag was provided: true –se a etiqueta persist for encontrada

  • Running userdata on every boot –se a etiqueta persist for encontrada

  • <powershell> tag was provided.. running powershell content: se a tag powershell for encontrada

  • <script> tag was provided.. running script content – se a etiqueta script for encontrada

  • Message: The output from user scripts – Se os scripts de dados do usuário forem executados, a saída será registrada

EC2Config

O arquivo de log do EC2Config é C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log. As informações a seguir são registradas quando os dados do usuário são executados.

  • Ec2HandleUserData: Message: Start running user scripts: o início da execução de dados do usuário

  • Ec2HandleUserData: Message: Re-enabled userdata execution –se a etiqueta persist for encontrada

  • Ec2HandleUserData: Message: Could not find <persist> and </persist>: se a tag persist não for encontrada

  • Ec2HandleUserData: Message: The output from user scripts – Se os scripts de dados do usuário forem executados, a saída será registrada

Reinicializações ou inicializações subsequentes

Quando você atualiza os dados do usuário da instância, os scripts de dados do usuário não são executados automaticamente ao reiniciar ou iniciar a instância. No entanto, é possível habilitar a execução de dados do usuário para que eles sejam executados uma vez ao reiniciar ou iniciar a instância, ou sempre que reiniciar ou iniciar a instância.

Se você escolher a opção Shutdown with Sysprep (Desativar com Sysprep), os scripts de dados do usuário serão executados na próxima vez que a instância for reiniciada ou iniciada, mesmo que você não tenha habilitado a execução de dados do usuário para reinicializações ou inicializações subsequentes. Os scripts de dados do usuário não serão executados em reinicializações ou inicializações subsequentes.

Como habilitar a execução de dados do usuário com o EC2Launch v2 (Visualizar AMIs)

  • Para executar uma tarefa nos dados do usuário na primeira inicialização, defina frequency como once.

  • Para executar uma tarefa nos dados do usuário em cada inicialização, defina frequency como always.

Como habilitar a execução de dados do usuário com o EC2Launch (Windows Server 2016 ou versões posteriores)

  1. Conecte-se à sua instância do Windows.

  2. Abra uma janela de comando do PowerShell e execute o comando a seguir:

    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -Schedule

  3. Desconecte-se da instância do Windows. Para executar scripts atualizados na próxima vez que a instância for iniciada, interrompa a instância e atualize os dados do usuário. Para ter mais informações, consulte Visualizar e atualizar os dados do usuário da instância.

Como habilitar a execução de dados do usuário com EC2Config (Windows Server 2012 R2 e versões anteriores)

  1. Conecte-se à sua instância do Windows.

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

  3. Em User Data (Dados do usuário), selecione Enable UserData execution for next service start (Habilitar execução de dados do usuário para o próximo início de serviço).

  4. Desconecte-se da instância do Windows. Para executar scripts atualizados na próxima vez que a instância for iniciada, interrompa a instância e atualize os dados do usuário. Para ter mais informações, consulte Visualizar e atualizar os dados do usuário da instância.

Dados do usuário e console

É possível especificar os dados do usuário da instância ao executar uma instância. Se o volume raiz da instância for um volume do EBS, também é possível parar a instância e atualizar os dados de usuário.

Especificar os dados do usuário da instância no lançamento

Siga o procedimento para iniciar uma instância. O campo User data (Dados do usuário) está localizado na seção Detalhes avançados do assistente de inicialização de instância. Insira seu script do PowerShell no campo Dados do usuário e conclua o procedimento de execução de instância.

Na seguinte captura de tela do campo Dados do usuário, o script de exemplo cria um arquivo na pasta temporária do Windows usando a data e a hora atuais no nome de arquivo. Ao incluir <persist>true</persist>, o script é executado sempre que você reiniciar ou iniciar a instância. Se você deixar a caixa de seleção Os dados do usuário já foram codificados em base64 vazia, o console do Amazon EC2 executará a codificação base64 para você.

Campo de texto de dados do usuário Advance Details (Detalhes avançados).

Visualizar e atualizar os dados do usuário da instância

É possível visualizar dados do usuário da instância para qualquer instância e atualizar dados do usuário da instância para uma instância interrompida.

Para atualizar os dados do usuário para uma instância usando o console

  1. Abra o console do Amazon EC2 em https://console.aws.amazon.com/ec2/.

  2. No painel de navegação, escolha Instances (Instâncias).

  3. Selecione a instância e escolha Actions (Ações), Instance state (Estado da instância) e Stop instance (Interromper instância).

    Atenção

    Quando você interrompe uma instância, os dados em todos os volumes de armazenamento de instâncias são apagados. Para manter dados longe dos volumes de armazenamento de instância, faça backup no armazenamento persistente.

  4. Quando a confirmação for solicitada, escolha Parar. Pode demorar alguns minutos para que a instância pare.

  5. Com a instância ainda selecionada, escolha Actions (Ações), Instance settings (Configurações de instância), Edit user data (Editar dados de usuário). Não é possível alterar os dados do usuário se a instância estiver em execução, mas é possível visualizá-la.

  6. Na caixa de diálogo Edit user data (Editar dados do usuário), atualize os dados do usuário e escolha Save (Salvar). Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione <persist>true</persist>, como mostrado no exemplo a seguir:

    Caixa de diálogo Edit User Data (Editar dados do usuário).

  7. Inicie a instância. Se você habilitou a execução de dados do usuário para reinicializações ou inicializações subsequentes, os scripts de dados do usuário atualizados serão executados como parte do processo de inicialização da instância.

Dados do usuário e Tools for Windows PowerShell

É possível usar Tools for Windows PowerShell para especificar, modificar e ver os dados do usuário para sua instância. Para obter informações sobre como visualizar os dados do usuário da sua instância usando metadados de instância, consulte Recuperar os dados do usuário da instância da sua instância. Para obter informações sobre dados do usuário e a AWS CLI, consulte Dados do usuário e a AWS CLI no Guia do usuário para instâncias do Linux do Amazon EC2.

Exemplo: especifique os dados do usuário da instância no lançamento

Crie um arquivo de texto com dados do usuário da instância. Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione <persist>true</persist>, como mostrado no exemplo a seguir:

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

Para especificar dados do usuário da instância ao executar a instância, use o comando New-EC2Instance. Esse comando não executa a codificação base64 dos dados do usuário para você. Use os comandos a seguir para codificar os dados do usuário em um arquivo de texto denominado script.txt.

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

Use o parâmetro -UserData para passar os dados do usuário para o 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
Exemplo: atualizar dados do usuário da instância para uma instância interrompida

É possível modificar os dados do usuário de uma instância interrompida usando o comando Edit-EC2InstanceAttribute.

Crie um arquivo de texto com o novo script. Use os comandos a seguir para codificar os dados do usuário no arquivo de texto denominado new-script.txt.

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

Use os parâmetros -UserData e -Value para especificar os dados do usuário.

PS C:\> Edit-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData -Value $NewUserData
Exemplo: visualizar dados do usuário da instância

Para recuperar os dados do usuário para uma instância, use o comando Get-EC2InstanceAttribute.

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

A seguir está um exemplo de saída. Observe que os dados do usuário são codificados.

PHBvd2Vyc2hlbGw+DQpSZW5hbWUtQ29tcHV0ZXIgLU5ld05hbWUgdXNlci1kYXRhLXRlc3QNCjwvcG93ZXJzaGVsbD4=

Use os comandos a seguir para armazenar os dados de usuário codificados em uma variável e decodifique-os.

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 seguir está um exemplo de saída.

<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>
Exemplo: renomear a instância para corresponder ao valor da tag

É possível usar o comando Get-EC2Tag para ler o valor da tag. Renomeie a instância na primeira inicialização para corresponder ao valor da tag e reinicialize. Para executar esse comando com êxito, é necessário ter uma função com permissões ec2:DescribeTags vinculadas à instância, pois as informações de tag são recuperadas pela chamada de API. Para obter mais informações sobre as permissões de configurações usando as funções do IAM, consulte Associação de uma função do IAM a uma instância.

nota

Esse script falha em versões do 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>

Também é possível renomear a instância usando tags em metadados de instância, se sua instância estiver configurada para acessar tags a partir dos metadados da instância.

nota

Esse script falha em versões do 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>