Demonstração: Usar a AWS Tools for Windows PowerShell com o Run Command - AWS Systems Manager
Definir configurações de sessão do AWS Tools for Windows PowerShellListar todos os documentos disponíveisExecutar comandos ou scripts do PowerShellInstalar uma aplicação usando o documento AWS-InstallApplicationInstalar um módulo do PowerShell usando aAWS-InstallPowerShellModuleDocumento JSONIntegrar um nó gerenciado a um domínio usando o documento JSON AWS-JoinDirectoryServiceDomainEnviar métricas do Windows ao Amazon CloudWatch Logs usando o documento AWS-ConfigureCloudWatchAtualizar o EC2Config usando aAWS-UpdateEC2ConfigdocumentAtive ou desative a atualização automática do Windows usando oAWS-ConfigureWindowsUpdatedocumentGerenciar atualizações do Windows usando o Run Command

Demonstração: Usar a AWS Tools for Windows PowerShell com o Run Command

Os exemplos a seguir mostram como usar o AWS Tools for Windows PowerShell para ver informações sobre comandos e parâmetros de comandos, como executar comandos e como visualizar o status desses comandos. Essa demonstração inclui um exemplo para cada um dos documentos do AWS Systems Manager predefinidos.

Importante

Apenas administradores confiáveis devem ter permissão para usar os documentos pré-configurados do Systems Manager mostrados neste tópico. Os comandos ou scripts especificados em documentos do Systems Manager são executados com permissão administrativa em seus nós gerenciados. Se um usuário tiver permissão para executar qualquer um dos documentos do Systems Manager predefinidos (qualquer documento que comece com AWS), ele também terá acesso de administrador ao nó. Para todos os outros usuários, você deve criar documentos restritivos e compartilhá-los com usuários específicos.

Definir configurações de sessão do AWS Tools for Windows PowerShell

Especificar suas credenciais

Abra as Tools for Windows PowerShell no computador local e execute o comando a seguir para especificar suas credenciais. Você deve ter permissões de administrador sobre os nós gerenciados que deseja configurar ou deve ter recebido a permissão apropriada no AWS Identity and Access Management (IAM). Para ter mais informações, consulte Configurar o AWS Systems Manager.

Set-AWSCredentials –AccessKey key-name –SecretKey key-name
Definir uma Região da AWS padrão

Execute o comando a seguir para definir a região da sua sessão do PowerShell. O exemplo usa região Leste dos EUA (Ohio) (us-east-2). O Run Command está disponível nas Regiões da AWS listadas em Systems Manager service endpoints no Referência geral da Amazon Web Services.

Set-DefaultAWSRegion `
    -Region us-east-2

Listar todos os documentos disponíveis

Esse comando lista todos os documentos disponíveis para a sua conta.

Get-SSMDocumentList

Executar comandos ou scripts do PowerShell

Por meio do Run Command e do documento AWS-RunPowerShell, você pode executar qualquer comando ou script em um nó gerenciado, como se estivesse conectado localmente. Você pode emitir comandos ou inserir um caminho para um script local para executar o comando.

nota

Para obter informações sobre a reinicialização de nós gerenciados ao usar o Run Command para chamar scripts, consulte Tratamento de reinicializações ao executar comandos.

Veja a descrição e os parâmetros disponíveis

Get-SSMDocumentDescription `
    -Name "AWS-RunPowerShellScript"

Veja mais informações sobre parâmetros

Get-SSMDocumentDescription `
    -Name "AWS-RunPowerShellScript" | Select -ExpandProperty Parameters

Enviar um comando usando o documento AWS-RunPowerShellScript

O comando a seguir mostra o conteúdo do diretório "C:\Users" e o conteúdo do diretório "C:\" em dois nós. 

$runPSCommand = Send-SSMCommand `
    -InstanceIds @("instance-ID-1", "instance-ID-2") `
    -DocumentName "AWS-RunPowerShellScript" `
    -Comment "Demo AWS-RunPowerShellScript with two instances" `
    -Parameter @{'commands'=@('dir C:\Users', 'dir C:\')}
Obter detalhes da solicitação de comando

O comando a seguir usa o CommandId para obter o status da execução do comando em ambos os nós. Este exemplo usa o CommandId que foi retornado no comando anterior. 

Get-SSMCommand `
    -CommandId $runPSCommand.CommandId

O status do comando neste exemplo pode ser Success, Pending ou InProgress.

Obter informações de comando por nó gerenciado

O comando a seguir usa o CommandId do comando anterior para obter o status da execução do comando por nó gerenciado.

Get-SSMCommandInvocation `
    -CommandId $runPSCommand.CommandId
Obter informações de comando com dados de resposta para um nó gerenciado específico

O comando a seguir retorna a saída da solicitação Send-SSMCommand original para um nó gerenciado específico. 

Get-SSMCommandInvocation `
    -CommandId $runPSCommand.CommandId `
    -Details $true `
    -InstanceId instance-ID | Select -ExpandProperty CommandPlugins

Cancelar um comando

O comando a seguir cancela o Send-SSMCommand para o documento AWS-RunPowerShellScript.

$cancelCommand = Send-SSMCommand `
    -InstanceIds @("instance-ID-1","instance-ID-2") `
    -DocumentName "AWS-RunPowerShellScript" `
    -Comment "Demo AWS-RunPowerShellScript with two instances" `
    -Parameter @{'commands'='Start-Sleep –Seconds 120; dir C:\'}

Stop-SSMCommand -CommandId $cancelCommand.CommandId
Verificar o status do comando

O comando a seguir verifica o status do comando Cancel.

Get-SSMCommand `
    -CommandId $cancelCommand.CommandId

Instalar uma aplicação usando o documento AWS-InstallApplication

Usando o Run Command e o documento AWS-InstallApplication, é possível instalar, reparar ou desinstalar aplicações em nós gerenciados. O comando requer o caminho ou endereço para um MSI.

nota

Para obter informações sobre a reinicialização de nós gerenciados ao usar o Run Command para chamar scripts, consulte Tratamento de reinicializações ao executar comandos.

Veja a descrição e os parâmetros disponíveis

Get-SSMDocumentDescription `
    -Name "AWS-InstallApplication"

Veja mais informações sobre parâmetros

Get-SSMDocumentDescription `
    -Name "AWS-InstallApplication" | Select -ExpandProperty Parameters

Enviar um comando usando o documento AWS-InstallApplication

O comando a seguir instala uma versão do Python em seu nó gerenciado no modo autônomo e registra a saída em um arquivo de texto local na sua unidade C:.

$installAppCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-InstallApplication" `
    -Parameter @{'source'='https://www.python.org/ftp/python/2.7.9/python-2.7.9.msi'; 'parameters'='/norestart /quiet /log c:\pythoninstall.txt'}
Obter informações de comando por nó gerenciado

O comando a seguir usa o CommandId para obter o status da execução do comando.

Get-SSMCommandInvocation `
    -CommandId $installAppCommand.CommandId `
    -Details $true
Obter informações de comando com dados de resposta para um nó gerenciado específico

O comando a seguir retorna os resultados da instalação do Python.

Get-SSMCommandInvocation `
    -CommandId $installAppCommand.CommandId `
    -Details $true `
    -InstanceId instance-ID | Select -ExpandProperty CommandPlugins

Instalar um módulo do PowerShell usando aAWS-InstallPowerShellModuleDocumento JSON

Você pode usar o Run Command para instalar módulos do PowerShell em nós gerenciados. Para obter mais informações sobre os módulos PowerShell, consulte Módulos do Windows PowerShell.

Veja a descrição e os parâmetros disponíveis

Get-SSMDocumentDescription `
    -Name "AWS-InstallPowerShellModule"

Veja mais informações sobre parâmetros

Get-SSMDocumentDescription `
    -Name "AWS-InstallPowerShellModule" | Select -ExpandProperty Parameters

Instalar um módulo PowerShell

O comando a seguir faz download do arquivo EZOut.zip, instala o arquivo e depois executa um comando adicional para instalar o visualizador XPS. Por fim, a saída desse comando é carregada em um bucket do S3 chamado "demo-ssm-output-bucket". 

$installPSCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-InstallPowerShellModule" `
    -Parameter @{'source'='https://gallery.technet.microsoft.com/EZOut-33ae0fb7/file/110351/1/EZOut.zip';'commands'=@('Add-WindowsFeature -name XPS-Viewer -restart')} `
    -OutputS3BucketName demo-ssm-output-bucket
Obter informações de comando por nó gerenciado

O comando a seguir usa o CommandId para obter o status da execução do comando. 

Get-SSMCommandInvocation `
    -CommandId $installPSCommand.CommandId `
    -Details $true
Obter informações de comando com dados de resposta para o nó gerenciado

O comando a seguir retorna a saída do Send-SSMCommand original para o CommandId específico. 

Get-SSMCommandInvocation `
    -CommandId $installPSCommand.CommandId `
    -Details $true | Select -ExpandProperty CommandPlugins

Integrar um nó gerenciado a um domínio usando o documento JSON AWS-JoinDirectoryServiceDomain

Por meio do Run Command, você pode unir rapidamente um nó gerenciado a um domínio do AWS Directory Service. Antes de executar esse comando, você deverá criar um diretório. Recomendamos também que conheça mais sobre o AWS Directory Service. Para obter mais informações, consulte o Guia do administrador do AWS Directory Service.

Você só pode unir um nó gerenciado a um domínio. Não é possível remover um nó de um domínio.

nota

Para obter informações sobre nós gerenciados ao usar o Run Command para chamar scripts, consulte Tratamento de reinicializações ao executar comandos.

Veja a descrição e os parâmetros disponíveis

Get-SSMDocumentDescription `
    -Name "AWS-JoinDirectoryServiceDomain"

Veja mais informações sobre parâmetros

Get-SSMDocumentDescription `
    -Name "AWS-JoinDirectoryServiceDomain" | Select -ExpandProperty Parameters

Integrar um nó gerenciado a um domínio

O comando a seguir integra um nó gerenciado a um domínio AWS Directory Service determinado e carrega qualquer saída gerada no exemplo do bucket do Amazon Simple Storage Service (Amazon S3). 

$domainJoinCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-JoinDirectoryServiceDomain" `
    -Parameter @{'directoryId'='d-example01'; 'directoryName'='ssm.example.com'; 'dnsIpAddresses'=@('192.168.10.195', '192.168.20.97')} `
    -OutputS3BucketName demo-ssm-output-bucket
Obter informações de comando por nó gerenciado

O comando a seguir usa o CommandId para obter o status da execução do comando. 

Get-SSMCommandInvocation `
    -CommandId $domainJoinCommand.CommandId `
    -Details $true
Obter informações de comando com dados de resposta para o nó gerenciado

Este comando retorna a saída do Send-SSMCommand original para o CommandId específico.

Get-SSMCommandInvocation `
    -CommandId $domainJoinCommand.CommandId `
    -Details $true | Select -ExpandProperty CommandPlugins

Enviar métricas do Windows ao Amazon CloudWatch Logs usando o documento AWS-ConfigureCloudWatch

Você pode enviar mensagens do Windows Server nos logs do aplicativo, do sistema e do Rastreamento de Eventos para Windows (ETW) para o Amazon CloudWatch Logs. Quando você permite o registro pela primeira vez, o Systems Manager envia todos os logs gerados no prazo de um (1) minuto a partir do momento em que você inicia o upload de logs para a aplicação, o sistema, a segurança e os logs do ETW. Logs ocorridos antes dessa hora não são incluídos. Se você desativar o registro em log e depois reabilitá-lo, o Systems Manager enviará logs do ponto em que ele parou. Para todos os arquivos de log personalizados e logs do IIS (Serviços de Informações da Internet), o Systems Manager lê os arquivos de log desde o início. Além disso, o Systems Manager também pode enviar dados do contador de performance para o CloudWatch Logs.

Se você habilitou anteriormente a integração do CloudWatch no EC2Config, as configurações do Systems Manager substituirão todas as configurações armazenadas localmente em seu nó gerenciado no arquivo C:\Program Files\Amazon\EC2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json. Para obter mais informações sobre como usar o EC2Config para gerenciar o contador e os logs de performance em um único nó gerenciado, consulte Coletar métricas e logs de instâncias do Amazon EC2 em servidores on-premises com o agente do CloudWatch no Guia do usuário do Amazon CloudWatch.

Veja a descrição e os parâmetros disponíveis

Get-SSMDocumentDescription `
    -Name "AWS-ConfigureCloudWatch"

Veja mais informações sobre parâmetros

Get-SSMDocumentDescription `
    -Name "AWS-ConfigureCloudWatch" | Select -ExpandProperty Parameters

Enviar logs de aplicativo ao CloudWatch

O comando a seguir configura o nó gerenciado e move logs de aplicações do Windows para o CloudWatch.

$cloudWatchCommand = Send-SSMCommand `
    -InstanceID instance-ID `
    -DocumentName "AWS-ConfigureCloudWatch" `
    -Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"ApplicationEventLog", "FullName":"AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"LogName":"Application", "Levels":"7"}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch", "Parameters":{"Region":"region", "LogGroup":"my-log-group", "LogStream":"instance-id"}}], "Flows":{"Flows":["ApplicationEventLog,CloudWatch"]}}}'}
Obter informações de comando por nó gerenciado

O comando a seguir usa o CommandId para obter o status da execução do comando. 

Get-SSMCommandInvocation `
    -CommandId $cloudWatchCommand.CommandId `
    -Details $true
Obter informações de comando com dados de resposta para um nó gerenciado específico

O comando a seguir retorna os resultados da configuração do Amazon CloudWatch.

Get-SSMCommandInvocation `
    -CommandId $cloudWatchCommand.CommandId `
    -Details $true `
    -InstanceId instance-ID | Select -ExpandProperty CommandPlugins

Enviar contadores de performance ao CloudWatch usando o documento AWS-ConfigureCloudWatch

O comando de demonstração a seguir faz upload de contadores de performance para o CloudWatch. Para mais informações, consulte o Guia do usuário do Amazon CloudWatch.

$cloudWatchMetricsCommand = Send-SSMCommand `
    -InstanceID instance-ID `
    -DocumentName "AWS-ConfigureCloudWatch" `
    -Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"PerformanceCounter", "FullName":"AWS.EC2.Windows.CloudWatch.PerformanceCounterComponent.PerformanceCounterInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"CategoryName":"Memory", "CounterName":"Available MBytes", "InstanceName":"", "MetricName":"AvailableMemory", "Unit":"Megabytes","DimensionName":"", "DimensionValue":""}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatch.CloudWatchOutputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"AccessKey":"", "SecretKey":"","Region":"region", "NameSpace":"Windows-Default"}}], "Flows":{"Flows":["PerformanceCounter,CloudWatch"]}}}'}

Atualizar o EC2Config usando aAWS-UpdateEC2Configdocument

Usando o Run Command e o documento AWS-EC2ConfigUpdate, é possível atualizar o serviço EC2Config em execução em nós gerenciados do Windows Server. Esse comando pode atualizar o serviço EC2Config para a versão mais recente ou uma versão que você especificar.

Veja a descrição e os parâmetros disponíveis

Get-SSMDocumentDescription `
    -Name "AWS-UpdateEC2Config"

Veja mais informações sobre parâmetros

Get-SSMDocumentDescription `
    -Name "AWS-UpdateEC2Config" | Select -ExpandProperty Parameters

Atualizar EC2Config para a versão mais recente

$ec2ConfigCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-UpdateEC2Config"
Obter informações de comando com dados de resposta para o nó gerenciado

Esse comando retorna a saída do comando especificado do Send-SSMCommand anterior.

Get-SSMCommandInvocation `
    -CommandId $ec2ConfigCommand.CommandId `
    -Details $true `
    -InstanceId instance-ID | Select -ExpandProperty CommandPlugins

Atualizar EC2Config para uma versão específica

O comando a seguir faz o downgrade do EC2Config para uma versão anterior.

Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-UpdateEC2Config" `
    -Parameter @{'version'='4.9.3519'; 'allowDowngrade'='true'}

Ative ou desative a atualização automática do Windows usando oAWS-ConfigureWindowsUpdatedocument

Usando o Run Command e o documento AWS-ConfigureWindowsUpdate, é possível ativar ou desativar as atualizações automáticas do Windows em seus nós gerenciados do Windows Server. Esse comando configura o agente de atualização do Windows para baixar e instalar atualizações do Windows na data e hora no dia e hora que você especificar. Se uma atualização exigir uma reinicialização, o nó gerenciado reiniciará automaticamente 15 minutos após a instalação das atualizações. Com esse comando, você também pode configurar o Windows Update para verificar atualizações, mas não pode instalá-las. O documento AWS-ConfigureWindowsUpdate é compatível com o Windows Server 2008, 2008 R2, 2012, 2012 R2 e 2016.

Veja a descrição e os parâmetros disponíveis

Get-SSMDocumentDescription `
    –Name "AWS-ConfigureWindowsUpdate"

Veja mais informações sobre parâmetros

Get-SSMDocumentDescription `
    -Name "AWS-ConfigureWindowsUpdate" | Select -ExpandProperty Parameters

Ativar a atualização automática do Windows

O comando a seguir configura o Windows Update para baixar e instalar atualizações diariamente às 22h. 

$configureWindowsUpdateCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-ConfigureWindowsUpdate" `
    -Parameters @{'updateLevel'='InstallUpdatesAutomatically'; 'scheduledInstallDay'='Daily'; 'scheduledInstallTime'='22:00'}
Visualizar o status do comando para permitir atualizações automáticas do Windows

O comando a seguir usa o CommandId para obter o status da execução do comando para ativar a Atualização Automática do Windows.

Get-SSMCommandInvocation `
    -Details $true `
    -CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins

Desativar a atualização automática do Windows

O seguinte comando reduz o nível de notificação do Windows Update para que o sistema verifique se há atualizações, mas não atualiza automaticamente o nó gerenciado.

$configureWindowsUpdateCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-ConfigureWindowsUpdate" `
    -Parameters @{'updateLevel'='NeverCheckForUpdates'}
Visualizar o status do comando para desativar a atualização automática do Windows

O comando a seguir usa o CommandId para obter o status da execução do comando para ativar a Atualização Automática do Windows.

Get-SSMCommandInvocation `
    -Details $true `
    -CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins

Gerenciar atualizações do Windows usando o Run Command

Usando o Run Command e do documento AWS-InstallWindowsUpdates, você pode gerenciar atualizações dos nós gerenciados do Windows Server. Esse comando verifica ou instala atualizações ausentes em nós gerenciados e, opcionalmente, reinicializa após a instalação. Você também pode especificar as classificações e os níveis de severidade adequados para as atualizações a serem instaladas no ambiente.

nota

Para obter informações sobre a reinicialização de nós gerenciados ao usar o Run Command para chamar scripts, consulte Tratamento de reinicializações ao executar comandos.

Os exemplos a seguir demonstram como realizar as tarefas de gerenciamento do Windows Update especificadas.

Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-InstallWindowsUpdates" `
    -Parameters @{'Action'='Scan'}

Instalar atualizações específicas do Windows

Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-InstallWindowsUpdates" `
    -Parameters @{'Action'='Install';'IncludeKbs'='kb-ID-1,kb-ID-2,kb-ID-3';'AllowReboot'='True'}

Instalar atualizações importantes do Windows ausentes

Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-InstallWindowsUpdates" `
    -Parameters @{'Action'='Install';'SeverityLevels'='Important';'AllowReboot'='True'}

Instalar atualizações do Windows ausentes com exclusões específicas

Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-InstallWindowsUpdates" `
    -Parameters @{'Action'='Install';'ExcludeKbs'='kb-ID-1,kb-ID-2';'AllowReboot'='True'}