Execução de comandos na instância do Amazon EC2 na inicialização - Amazon Elastic Compute Cloud

Execução de comandos na instância do Amazon EC2 na inicialização

Ao iniciar uma instância do Amazon EC2, é possível transferir dados do usuário para a instância que é usada para executar tarefas de configuração automatizadas ou para executar scripts após o início da instância.

Se você estiver interessado em cenários de automação mais complexos, considere usar AWS CloudFormation e AWS OpsWorks. Para obter mais informações, consulte as informações a seguir.

Em instâncias do Linux, é possível transferir dois tipos de dados do usuário para o Amazon EC2, nomeadamente, os scripts de shell e diretivas do cloud-init. Além disso, é possível transferir esses dados para o assistente de inicialização de instâncias como texto simples, como um arquivo (isso é útil para iniciar instâncias com as ferramentas de linha de comando) ou como texto codificado em base64 (para chamadas de API).

Nas instâncias do Windows, os agentes de inicialização gerenciam os scripts de dados do usuário. As seções apresentadas a seguir abordam as diferenças na forma em que os dados do usuário são tratados em cada sistema operacional.

Como o Amazon EC2 lida com os dados dos usuários para instâncias do Linux

Nos exemplos a seguir, os comandos de Instalar um servidor LAMP no Amazon Linux 2 são convertidos em um script de shell e um conjunto de diretivas de cloud-init que são executados quando a instância é iniciada. Em cada exemplo, as seguintes tarefas são executadas pelos dados do usuário:

  • Os pacotes de distribuição de software são atualizados.

  • O servidor web necessário, php, e os pacotes mariadb são instalados.

  • O serviço httpd é iniciado e ativado por systemctl.

  • O grupo de segurança ec2-user é adicionado ao grupo apache.

  • As permissões de propriedade e de arquivos apropriadas são definidas para o diretório Web e os arquivos contidos nele.

  • Uma página Web simples é criada para testar o servidor Web e o mecanismo de PHP.

Pré-requisitos

Para os exemplos deste tópico, suponha o seguinte:

  • Sua instância tem um nome DNS público que é acessível pela Internet.

  • O grupo de segurança associado à sua instância é configurado para permitir tráfego SSH (porta 22), de modo que você possa se conectar à instância para visualizar os arquivos de log de saída.

  • Sua instância é iniciada com uma AMI do Amazon Linux 2. Essas instruções são para serem usadas com o Amazon Linux 2, e os comandos e as diretivas podem não funcionar para outras distribuições do Linux. Para obter mais informações sobre outras distribuições, como suporte para cloud-init, consulte a documentação específica.

Dados de usuário e scripts de shell

Se você estiver familiarizado com scripts de shell, esta é a maneira mais fácil e completa de enviar instruções para uma instância na execução. Se você adicionar essas tarefas no momento da inicialização, será necessário mais tempo para iniciar a instância. É necessário reservar alguns minutos extras para que as tarefas sejam concluídas antes de testar se o script de usuário foi concluído com êxito.

Importante

Por padrão, os scripts de dados do usuário e as diretrizes cloud-init são executados somente durante o ciclo de inicialização quando você inicia uma instância pela primeira vez. É possível atualizar sua configuração para garantir que seus scripts de dados de usuário e diretrizes cloud-init sejam executados sempre que você reiniciar sua instância. Para obter mais informações, consulte How can I utilize user data to automatically run a script with every restart of my Amazon EC2 Linux instance? (Como posso utilizar os dados do usuário para executar automaticamente um script a cada reinicialização da minha instância do Linux do Amazon EC2?) na Central de Conhecimento da AWS.

Os scripts de shell de dados de usuário devem ser iniciados pelos caracteres #! e pelo caminho para o intérprete que você deseja que leia o script (geralmente /bin/bash). Para uma introdução sobre scripts de shell, consulte o Manual de referência do Bash no site do Sistema operacional GNU.

Os scripts inseridos como dados de usuário são executados como usuário raiz,, portanto, não use o comando sudo no script. Lembre-se de que todos os arquivos que você criar serão de propriedade do usuário raiz. Caso precise que um usuário não raiz tenha acesso aos arquivos, modifique as permissões em conformidade com o script. Além disso, como o script não é executado interativamente, você não pode incluir os comandos que exigem feedback do usuário (como yum update sem o sinalizador -y).

Se você usar uma API da AWS, incluindo a CLI da AWS 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 emitir a chamada de API. Para obter mais informações, consulte Usar perfis de instâncias no Guia do usuário do IAM. As permissões que atribui à função do IAM dependem de quais serviços você chama com a API. Para ter mais informações, consulte Funções do IAM para Amazon EC2.

O arquivo de log de saída de cloud-init captura a saída do console para facilitar a depuração de seus scripts após uma execução se a instância não se comportar da maneira desejada. Para exibir o arquivo de log, conecte-se à instância e abra /var/log/cloud-init-output.log.

Quando um script de dados do usuário é processado, ele é copiado para e executado a partir deste diretório /var/lib/cloud/instances/instance-id/. O script não é excluído depois de ser executado. Certifique-se de excluir os scripts de dados do usuário de /var/lib/cloud/instances/instance-id/ antes de criar uma AMI a partir da instância. Caso contrário, o script existirá nesse diretório em qualquer instância iniciada na AMI.

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 shell no campo User data (Dados do usuário) e conclua o procedimento de inicialização de instância.

Este script de exemplo cria e configura nosso servidor Web.

#!/bin/bash yum update -y amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2 yum install -y httpd mariadb-server systemctl start httpd systemctl enable httpd usermod -a -G apache ec2-user chown -R ec2-user:apache /var/www chmod 2775 /var/www find /var/www -type d -exec chmod 2775 {} \; find /var/www -type f -exec chmod 0664 {} \; echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php

Reserve tempo suficiente para executar a instância e execute os comandos do script. Depois, verifique se o script concluiu as tarefas previstas.

Em nosso exemplo, em um navegador Web, insira o URL do arquivo de teste PHP criado pelo script. Essa URL é o endereço DNS público da instância seguido por uma barra e o nome do arquivo.

http://my.public.dns.amazonaws.com/phpinfo.php

É necessário consultar a página de informações do PHP. Caso não seja possível visualizar a página de informações do PHP, verifique se o security group que você está usando contém uma regra para permitir tráfego HTTP (porta 80). Para ter mais informações, consulte Adicionar regras a um grupo de segurança.

(Opcional) Se o script não tiver realizado as tarefas você esperava ou se você quiser simplesmente verificar se o script foi concluído sem erros, conecte-se à instância, examine o arquivo de log de saída de cloud-init (/var/log/cloud-init-output.log) e procure mensagens de erro na saída.

Para informações adicionais de depuração, é possível criar um arquivo multiparte Mime que inclua uma seção de dados de cloud-init com a seguinte diretiva:

output : { all : '| tee -a /var/log/cloud-init-output.log' }

Essa diretiva envia a saída do comando do script para /var/log/cloud-init-output.log. Para obter mais informações sobre os formatos de dados de cloud-init e a criação de arquivos multiparte Mime, consulte Formatos de cloud-init.

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

Para atualizar os dados do usuário da instância, primeiro é necessário interromper a instância. Se a instância estiver em execução, será possível visualizar os dados do usuário, mas não modificá-los.

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.

Para modificar os dados do usuário da instância
  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 Instance state (Estado da instância) e Stop instance (Interromper instância). Se essa opção estiver desabilitada, a instância já foi interrompida ou o dispositivo raiz é um volume de armazenamento de instâncias.

  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).

  6. Modifique os dados do usuário conforme necessário e escolha Save (Salvar).

  7. Inicie a instância. Os novos dados do usuário ficam visíveis na instância depois que você a inicia. Contudo, os scripts dos dados do usuário não são executados.

Diretivas de cloud-init e dados de usuário

O pacote de cloud-init configura aspectos específicos de uma nova instância do Amazon Linux quando ela é executada. Em particular, ele configura o arquivo .ssh/authorized_keys para o usuário ec2 para que você possa se conectar com sua própria chave privada. Para obter mais informações sobre as tarefas de configuração que o pacote de cloud-init executa para instâncias do Amazon Linux, consulte Using cloud-init on Amazon Linux 2 no Amazon Linux 2 User Guide.

As diretivas de cloud-init podem ser passadas a uma instância em execução da mesma forma que um script é passado, embora a sintaxe seja diferente. Para obter mais informações sobre o cloud-init, consulte http://cloudinit.readthedocs.org/en/latest/index.html.

Importante

Por padrão, os scripts de dados do usuário e as diretrizes cloud-init são executados somente durante o ciclo de inicialização quando você inicia uma instância pela primeira vez. É possível atualizar sua configuração para garantir que seus scripts de dados de usuário e diretrizes cloud-init sejam executados sempre que você reiniciar sua instância. Para obter mais informações, consulte How can I utilize user data to automatically run a script with every restart of my Amazon EC2 Linux instance? (Como posso utilizar os dados do usuário para executar automaticamente um script a cada reinicialização da minha instância Linux do Amazon EC2?) na Central de Conhecimento da AWS.

Se você adicionar essas tarefas no momento da inicialização, será necessário mais tempo para iniciar uma instância. É necessário reservar alguns minutos extras para que as tarefas sejam concluídas antes de testar se as diretivas de dados de usuário foram concluídas.

Para passar diretivas de cloud-init para uma instância com dados de usuário
  1. 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 o texto da diretiva cloud-init no campo User data (Dados do usuário) e conclua o procedimento de inicialização de instância.

    No exemplo a seguir, as diretivas criam e configuram um servidor Web no Amazon Linux 2. A linha #cloud-config na parte superior é necessária para identificar os comandos como diretrizes cloud-init.

    #cloud-config repo_update: true repo_upgrade: all packages: - httpd - mariadb-server runcmd: - [ sh, -c, "amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2" ] - systemctl start httpd - sudo systemctl enable httpd - [ sh, -c, "usermod -a -G apache ec2-user" ] - [ sh, -c, "chown -R ec2-user:apache /var/www" ] - chmod 2775 /var/www - [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ] - [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ] - [ sh, -c, 'echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php' ]
  2. Reserve tempo suficiente para que a instância seja executada e execute as diretivas nos dados de usuário. Depois, verifique se as diretivas concluíram as tarefas previstas.

    Para este exemplo, em um navegador da Web, insira a URL do arquivo de teste PHP criado pelas diretivas. Essa URL é o endereço DNS público da instância seguido por uma barra e o nome do arquivo.

    http://my.public.dns.amazonaws.com/phpinfo.php

    É necessário consultar a página de informações do PHP. Caso não seja possível visualizar a página de informações do PHP, verifique se o security group que você está usando contém uma regra para permitir tráfego HTTP (porta 80). Para ter mais informações, consulte Adicionar regras a um grupo de segurança.

  3. (Opcional) Se as diretivas não tiverem realizado as tarefas que você esperava ou se você quiser simplesmente verificar se as diretivas foram concluídas sem erros, conecte-se à instância, examine o arquivo de log de saída (/var/log/cloud-init-output.log) e procure mensagens de erro na saída. Para informações adicionais de depuração, é possível adicionar a seguinte linha às diretivas:

    output : { all : '| tee -a /var/log/cloud-init-output.log' }

    Essa diretiva orientadora envia a saída runcmd para /var/log/cloud-init-output.log.

Dados do usuário e AWS CLI

É possível usar AWS CLI 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.

No Windows, é possível usar o AWS Tools for Windows PowerShell em vez de usar a AWS CLI. Para obter mais informações, consulteDados do usuário e Tools for Windows PowerShell

Exemplo: especificar dados do usuário na execução

Para especificar dados de usuário ao executar a instância, use o comando run-instances com o parâmetro --user-data. Com run-instances, a AWS CLI executa codificação de base64 dos dados de usuário para você.

O exemplo a seguir mostra como especificar um script como uma string na linha de comando:

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \ --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \ --user-data echo user data

O exemplo a seguir mostra como especificar um script usando um arquivo de texto. Certifique-se de usar o prefixo file:// para especificar o arquivo.

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \ --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \ --user-data file://my_script.txt

A seguir, temos um exemplo de arquivo de texto com um script de shell.

#!/bin/bash yum update -y service httpd start chkconfig httpd on
Exemplo: modificar os dados do usuário de uma instância interrompida

É possível modificar os dados de usuário de uma instância interrompida usando o comando modify-instance-attribute. Com modify-instance-attribute, a AWS CLI não executa a codificação de base64 dos dados de usuário para você.

  • Em um computador Linux, use o comando base64 para codificar os dados de usuário.

    base64 my_script.txt >my_script_base64.txt
  • Em um computador Windows, use o comando certutil para codificar os dados de usuário. Para poder usar esse arquivo com a AWS CLI, é necessário remover as primeiras (INICIAR CERTIFICADO) e últimas (ENCERRAR CERTIFICADO) linhas.

    certutil -encode my_script.txt my_script_base64.txt notepad my_script_base64.txt

Use os parâmetros --attribute e --value para usar o arquivo de texto codificado para especificar os dados de usuário. Certifique-se de usar o prefixo file:// para especificar o arquivo.

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --value file://my_script_base64.txt
Exemplo: limpar os dados do usuário de uma instância interrompida

Para excluir os dados do usuário existentes, use o comando modify-instance-attribute da seguinte maneira:

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --user-data Value=
Exemplo: visualizar dados do usuário

Para recuperar os dados de usuário de uma instância, use o comando describe-instance-attribute. Com describe-instance-attribute, a AWS CLI não executa a decodificação de base64 dos dados de usuário para você.

aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData

Esta é uma saída de exemplo com dados de usuário com codificação base64.

{ "UserData": { "Value": "IyEvYmluL2Jhc2gKeXVtIHVwZGF0ZSAteQpzZXJ2aWNlIGh0dHBkIHN0YXJ0CmNoa2NvbmZpZyBodHRwZCBvbg==" }, "InstanceId": "i-1234567890abcdef0" }
  • Em um computador Linux, use a opção --query para obter os dados de usuário codificados e o comando base64 para descodificá-los.

    aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" | base64 --decode
  • Em um computador Windows, use a opção --query para obter os dados de usuário codificados e o comando certutil para descodificá-los. Observe que a saída codificada está armazenada em um arquivo e a saída descodificada está armazenada em outro arquivo.

    aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" >my_output.txt certutil -decode my_output.txt my_output_decoded.txt type my_output_decoded.txt

O seguinte é um exemplo de saída.

#!/bin/bash yum update -y service httpd start chkconfig httpd on

Combinar scripts de shell e diretivas de cloud-init

Por padrão, você só pode incluir um tipo de conteúdo em dados de usuário de cada vez. Porém, você pode usar os tipos de conteúdo text/cloud-config e text/x-shellscript em um arquivo mime-multi part para incluir um script de shell e diretivas de cloud-init nos dados de usuário.

O exemplo a seguir mostra o formato mime-multi part.

Content-Type: multipart/mixed; boundary="//" MIME-Version: 1.0 --// Content-Type: text/cloud-config; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="cloud-config.txt" #cloud-config cloud-init directives --// Content-Type: text/x-shellscript; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="userdata.txt" #!/bin/bash shell script commands --//--

Por exemplo, os seguintes dados de usuário incluem diretivas cloud-init e um script de shell bash. As diretivas cloud-init criam um arquivo (/test-cloudinit/cloud-init.txt) e gravam Created by cloud-init nesse arquivo. O script de shell bash cria um arquivo (/test-userscript/userscript.txt) e grava Created by bash shell script nesse arquivo.

Content-Type: multipart/mixed; boundary="//" MIME-Version: 1.0 --// Content-Type: text/cloud-config; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="cloud-config.txt" #cloud-config runcmd: - [ mkdir, /test-cloudinit ] write_files: - path: /test-cloudinit/cloud-init.txt content: Created by cloud-init --// Content-Type: text/x-shellscript; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="userdata.txt" #!/bin/bash mkdir test-userscript touch /test-userscript/userscript.txt echo "Created by bash shell script" >> /test-userscript/userscript.txt --//--

Como o Amazon EC2 lida com os dados dos usuários para instâncias do Windows

Nas instâncias do Windows, os agentes de inicialização padrão para a versão do seu sistema operacional tratam os dados do usuário da maneira descrita a seguir.

  • O EC2Launch v2 executa os scripts de dados do usuário no Windows Server 2022

  • O EC2Launch executa os scripts de dados do usuário no Windows Server 2016 e 2019

  • O Serviço EC2Config executa os scripts de dados do usuário em versões do Windows Server anteriores ao Windows Server 2016

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 um exemplo de comandos de execução em uma instância dentro de um grupo do Auto Scaling que funciona com ganchos do ciclo de vida, consulte Tutorial: Configure user data to retrieve the target lifecycle state through instance metadata 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, é necessário colocar o script em uma etiqueta 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 ter 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 de dados do usuário XML como um processo separado com a tarefa executeScript do EC2Launch v2 no estágio UserData, adicione <detach>true</detach> aos dados do usuário.

nota

A tag detach 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>

É possível especificar um ou mais argumentos do PowerShell com tag <powershellArguments>. Se nenhum argumento for passado, o EC2Launch e o EC2Launch v2 adicionarão 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>
Agente do EC2Launch v2

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

nota

A tag detach 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.

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.

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 os dados do usuário e a AWS CLI, consulte Dados do usuário e AWS CLI.

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ção ao usar perfis do IAM, consulte Anexar uma função do IAM a uma instância.

<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. Para ter mais informações, consulte Trabalho com tags de instância em metadados de instância.

<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>