Tutorial: uso de la AWS Tools for Windows PowerShell con Run Command

Los siguientes ejemplos muestran cómo utilizar AWS Tools for Windows PowerShell para ver información sobre los comandos y los parámetros de comando, cómo ejecutar comandos y cómo consultar el estado de dichos comandos. Este tutorial incluye un ejemplo para cada uno de los documentos de AWS Systems Manager predefinidos.

importante

Solo los administradores de confianza deben tener permiso para utilizar los documentos preconfigurados de Systems Manager que se muestran en este tema. Los comandos o los scripts especificados en los documentos de Systems Manager se ejecutan con permisos administrativos en los nodos administrados. Si un usuario tiene permiso para ejecutar cualquiera de los documentos de Systems Manager predefinidos (cualquier documento que empiece con AWS), dicho usuario también tendrá acceso de administrador al nodo. Para todos los demás usuarios, debe crear documentos restrictivos y compartirlos con los usuarios específicos.

Configurar las opciones de la sesión de AWS Tools for Windows PowerShell

Especificar sus credenciales

Abra Tools for Windows PowerShell en su equipo local y ejecute el siguiente comando para especificar sus credenciales. Debe tener permisos de administrador en los nodos administrados que desea configurar o se le deben haber otorgado los permisos adecuados en AWS Identity and Access Management (IAM). Para obtener más información, consulte Configuración de AWS Systems Manager.

Set-AWSCredentials –AccessKey key-name –SecretKey key-name

Establezca una Región de AWS predeterminada.

Ejecute el siguiente comando para establecer la región de la sesión de PowerShell. En el ejemplo, se utiliza la región Este de EE. UU. (Ohio) (us-east-2). Run Command está disponible en las Regiones de AWS que se indican en Puntos de conexión de servicio de Systems Manager en la Referencia general de Amazon Web Services.

Set-DefaultAWSRegion `
    -Region us-east-2

Enumerar todos los documentos disponibles

Este comando enumera todos los documentos disponibles para su cuenta.

Get-SSMDocumentList

Ejecutar comandos o scripts de PowerShell

Si utiliza Run Command y el documento AWS-RunPowerShell, puede ejecutar cualquier comando o script en un nodo administrado como si hubiera iniciado sesión de manera local. Puede emitir comandos o ingresar una ruta a un script local para ejecutar el comando.

nota

Para obtener información acerca de cómo reiniciar los nodos administrados cuando se utiliza Run Command para llamar a scripts, consulte Gestión de reinicios al ejecutar comandos.

Ver la descripción y los parámetros disponibles

Get-SSMDocumentDescription `
    -Name "AWS-RunPowerShellScript"

Ver más información sobre los parámetros

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

Enviar comandos utilizando el documento AWS-RunPowerShellScript

El siguiente comando muestra el contenido del directorio "C:\Users" y el contenido del directorio "C:\" en dos nodos administrados.

$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:\')}

Obtener los detalles de la solicitud del comando

El comando siguiente utiliza el CommandId para obtener el estado de la ejecución del comando en ambos nodos administrados. Este ejemplo utiliza el CommandId devuelto en el comando anterior.

Get-SSMCommand `
    -CommandId $runPSCommand.CommandId

El estado del comando en este ejemplo puede ser Success, Pending o InProgress.

Obtención de información de comandos por nodo administrado

El comando siguiente utiliza el CommandId del comando anterior para obtener el estado de la ejecución del comando nodo por nodo.

Get-SSMCommandInvocation `
    -CommandId $runPSCommand.CommandId

Obtención de información de comando con los datos de respuesta de un nodo administrado concreto

El siguiente comando devuelve la salida del Send-SSMCommand original para un nodo administrado concreto.

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

Cancelar un comando

El siguiente comando cancela el comando Send-SSMCommand para el 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

Comprobar el estado del comando

El comando siguiente comprueba el estado del comando Cancel.

Get-SSMCommand `
    -CommandId $cancelCommand.CommandId

Instalar una aplicación utilizando el documento AWS-InstallApplication

Si utiliza Run Command y el documento AWS-InstallApplication, puede instalar, reparar o desinstalar aplicaciones en nodos administrados. El comando requiere la ruta o dirección de un MSI.

nota

Para obtener información acerca de cómo reiniciar los nodos administrados cuando se utiliza Run Command para llamar a scripts, consulte Gestión de reinicios al ejecutar comandos.

Ver la descripción y los parámetros disponibles

Get-SSMDocumentDescription `
    -Name "AWS-InstallApplication"

Ver más información sobre los parámetros

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

Enviar comandos utilizando el documento AWS-InstallApplication

El siguiente comando instala una versión de Python en el nodo administrado en modo desatendido y registra la salida en un archivo de texto local de la unidad 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'}

Obtención de información de comandos por nodo administrado

El comando siguiente utiliza el CommandId para obtener el estado de la ejecución del comando.

Get-SSMCommandInvocation `
    -CommandId $installAppCommand.CommandId `
    -Details $true

Obtención de información de comando con los datos de respuesta de un nodo administrado concreto

El siguiente comando devuelve el resultado de la instalación de Python.

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

Instalar un módulo de PowerShell utilizando el documento JSON AWS-InstallPowerShellModule

Puede utilizar Run Command para instalar módulos de PowerShell en nodos administrados. Para obtener más información acerca de los módulos de PowerShell, consulte Módulos de Windows PowerShell.

Ver la descripción y los parámetros disponibles

Get-SSMDocumentDescription `
    -Name "AWS-InstallPowerShellModule"

Ver más información sobre los parámetros

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

Instalar un módulo de PowerShell

El siguiente comando descarga el archivo EZOut.zip, lo instala y, a continuación, ejecuta un comando adicional para instalar el visor de XPS. Por último, la salida de este comando se carga en un bucket de S3 denominado "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

Obtención de información de comandos por nodo administrado

El comando siguiente utiliza el CommandId para obtener el estado de la ejecución del comando.

Get-SSMCommandInvocation `
    -CommandId $installPSCommand.CommandId `
    -Details $true

Obtención de información de comandos con los datos de respuesta del nodo administrado

El siguiente comando devuelve el resultado del comando Send-SSMCommand original para el CommandId especificado.

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

Unión de un nodo administrado a un dominio utilizando el documento JSON AWS-JoinDirectoryServiceDomain

Si utiliza Run Command, puede unir rápidamente un nodo administrado a un dominio de AWS Directory Service. Antes de ejecutar este comando, cree un directorio. También le recomendamos obtener más información acerca de AWS Directory Service. Para obtener más información, consulte la Guía de administración de AWS Directory Service.

Solo puede unir un nodo administrado a un dominio. No se puede eliminar un nodo de un dominio.

nota

Para obtener información acerca de los nodos administrados cuando se utiliza Run Command para llamar a scripts, consulte Gestión de reinicios al ejecutar comandos.

Ver la descripción y los parámetros disponibles

Get-SSMDocumentDescription `
    -Name "AWS-JoinDirectoryServiceDomain"

Ver más información sobre los parámetros

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

Unión de un nodo administrado a un dominio

El siguiente comando une un nodo administrado con el dominio AWS Directory Service dado y carga cualquier salida generada en el bucket de ejemplo de 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

Obtención de información de comandos por nodo administrado

El comando siguiente utiliza el CommandId para obtener el estado de la ejecución del comando.

Get-SSMCommandInvocation `
    -CommandId $domainJoinCommand.CommandId `
    -Details $true

Obtención de información de comandos con los datos de respuesta del nodo administrado

Este comando devuelve la salida del comando Send-SSMCommand original para el CommandId especificado.

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

Enviar métricas de Windows a Amazon CloudWatch Logs mediante el documento AWS-ConfigureCloudWatch

Puede enviar mensajes de Windows Server en los registros de aplicación, sistema, seguridad y Seguimiento de eventos para Windows (ETW) a Amazon CloudWatch Logs. Cuando se permite el registro por primera vez, Systems Manager envía todos los registros generados en un plazo de un (1) minuto a partir del momento en que empieza a cargar registros para los registros de aplicación, sistema, seguridad y ETW. No se incluyen los registros que se produjeron antes de este tiempo. Si desactiva el registro y después vuelve a activarlo, Systems Manager envía registros desde el momento en que dejó de hacerlo. En el caso de cualquier archivo de registros personalizado y registro de Internet Information Services (IIS), Systems Manager lee los archivos de registros desde el principio. Además, Systems Manager también puede enviar datos del contador de rendimiento a CloudWatch Logs.

Si con anterioridad activó la integración de CloudWatch en EC2Config, la configuración de Systems Manager anulará cualquier configuración almacenada de forma local en el nodo administrado en el archivo C:\Program Files\Amazon\EC2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json. Para obtener información sobre cómo se utiliza EC2Config para administrar los contadores de rendimiento y los registros en un solo nodo administrado, consulte Recopilación de métricas y registros de instancias de Amazon EC2 y servidores locales con el agente de CloudWatch en la Guía del usuario de Amazon CloudWatch.

Ver la descripción y los parámetros disponibles

Get-SSMDocumentDescription `
    -Name "AWS-ConfigureCloudWatch"

Ver más información sobre los parámetros

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

Enviar registros de aplicación a CloudWatch

El siguiente comando configura el nodo administrado y mueve los registros de aplicaciones de Windows a 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"]}}}'}

Obtención de información de comandos por nodo administrado

El comando siguiente utiliza el CommandId para obtener el estado de la ejecución del comando.

Get-SSMCommandInvocation `
    -CommandId $cloudWatchCommand.CommandId `
    -Details $true

Obtención de información de comando con los datos de respuesta de un nodo administrado concreto

El siguiente comando devuelve los resultados de la configuración de Amazon CloudWatch.

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

Enviar contadores de rendimiento a CloudWatch utilizando el documento AWS-ConfigureCloudWatch

El siguiente comando de demostración carga contadores de desempeño en CloudWatch. Para obtener más información, consulte la Guía del usuario de 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"]}}}'}

Actualizar EC2Config utilizando el documento AWS-UpdateEC2Config

Si utiliza Run Command y el documento AWS-EC2ConfigUpdate, puede actualizar el servicio EC2Config que se ejecuta en los nodos administrados de Windows Server. Este comando puede actualizar el servicio EC2Config a la versión más reciente o a la versión que especifique.

Ver la descripción y los parámetros disponibles

Get-SSMDocumentDescription `
    -Name "AWS-UpdateEC2Config"

Ver más información sobre los parámetros

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

Actualizar EC2Config a la versión más reciente

$ec2ConfigCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-UpdateEC2Config"

Obtención de información de comandos con los datos de respuesta del nodo administrado

Este comando devuelve la salida del comando especificado del comando anterior Send-SSMCommand.

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

Actualizar EC2Config a una versión específica

El siguiente comando degradará EC2Config a una versión anterior.

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

Activar o desactivar la actualización automática de Windows con el documento AWS-ConfigureWindowsUpdate

Si utiliza Run Command y el documento AWS-ConfigureWindowsUpdate, puede activar o desactivar las actualizaciones automáticas de Windows en los nodos administrados de Windows Server. Este comando configura el agente de Windows Update para que descargue e instale las actualizaciones de Windows el día y a la hora que usted especifique. Si una actualización requiere un reinicio, el nodo administrado se reiniciará automáticamente 15 minutos después de haber instalado las actualizaciones. Con este comando también puede configurar Windows Update para que verifique si hay actualizaciones, pero sin instalarlas. El documento AWS-ConfigureWindowsUpdate es compatible con Windows Server 2008, 2008 R2, 2012, 2012 R2 y 2016.

Ver la descripción y los parámetros disponibles

Get-SSMDocumentDescription `
    –Name "AWS-ConfigureWindowsUpdate"

Ver más información sobre los parámetros

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

Activar la actualización automática de Windows

El siguiente comando configura Windows Update para que descargue e instale las actualizaciones automáticamente todos los días a las 10:00 h.

$configureWindowsUpdateCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-ConfigureWindowsUpdate" `
    -Parameters @{'updateLevel'='InstallUpdatesAutomatically'; 'scheduledInstallDay'='Daily'; 'scheduledInstallTime'='22:00'}

Ver el estado del comando para permitir la actualización automática de Windows

El comando siguiente utiliza el CommandId para obtener el estado de la ejecución del comando para permitir la actualización automática de Windows.

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

Desactivar la actualización automática de Windows

El comando siguiente reduce el nivel de notificación de Windows Update para que el sistema verifique si hay actualizaciones, pero no actualice automáticamente el nodo administrado.

$configureWindowsUpdateCommand = Send-SSMCommand `
    -InstanceId instance-ID `
    -DocumentName "AWS-ConfigureWindowsUpdate" `
    -Parameters @{'updateLevel'='NeverCheckForUpdates'}

Ver el estado del comando para desactivar la actualización automática de Windows

El comando siguiente utiliza el CommandId para obtener el estado de la ejecución del comando para desactivar la actualización automática de Windows.

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

Administrar las actualizaciones de Windows mediante Run Command

Mediante el uso de Run Command y el documento AWS-InstallWindowsUpdates, puede administrar actualizaciones para nodos administrados de Windows Server. Este comando busca o instala las actualizaciones que faltan en los nodos administrados y, de forma opcional, se reinicia después de la instalación. También puede especificar las clasificaciones y los niveles de gravedad adecuados para las actualizaciones que se van a instalar en su entorno.

nota

Para obtener información acerca de cómo reiniciar los nodos administrados cuando se utiliza Run Command para llamar a scripts, consulte Gestión de reinicios al ejecutar comandos.

Los siguientes ejemplos muestran cómo realizar las tareas de administración de Windows Update especificadas.

Buscar todas las actualizaciones de Windows que faltan

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

Instalar actualizaciones de Windows específicas

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

Instalar las actualizaciones importantes de Windows que faltan

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

Instalar las actualizaciones de Windows que faltan con exclusiones específicas

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