Event Hubs

Los Event Hubs requieren una licencia.

Los Event Hubs ofrecen la capacidad de enviar comandos de PowerShell a los agentes de PowerShell Universal conectados desde el servidor de PowerShell Universal. Los agentes son servicios ligeros y multiplataforma que pueden ejecutarse en nodos periféricos para permitir que PowerShell Universal emita comandos contra ellos.

Los Event Hubs funcionan mediante un método de comunicación uno a uno desde el servidor al agente o mediante un método de comunicación de difusión uno a varios desde un event hub del servidor a todos los agentes conectados. Los agentes no ejecutan trabajos directamente y requieren el uso de Invoke-PSUCommand desde otros scripts que se ejecutan dentro del servidor de PowerShell Universal. Puede pensar en los event hubs como una forma de realizar comunicación remota de PowerShell sin utilizar el transporte remoto estándar.

Acerca de

PowerShell Universal ejecuta un servidor web con un endpoint de websocket que escuchará las conexiones de los agentes. Esto se denomina event hub. Puede configurar varios event hubs por servidor de PowerShell Universal con diferentes nombres y ajustes de seguridad. Una vez que se ha configurado un event hub en el servidor, puede instalar un agente en cualquier máquina que pueda acceder a PowerShell Universal a través de los puertos HTTP estándar.

El agente requiere cierta configuración sobre dónde y cómo conectarse al servidor. Una vez hecho esto, se puede iniciar el agente para establecer la conexión websocket con el servidor. Después de establecer la conexión, el servidor conoce el cliente conectado. Se registrará en el hub y entonces podrán enviarse eventos desde el servidor a los agentes.

Aunque no puede programar trabajos para que se ejecuten directamente en los agentes, sí puede ejecutar comandos contra los agentes, dentro de trabajos, API y aplicaciones del servidor.

Ejemplo básico

Como ejemplo, puede tener un agente de PowerShell Universal para Linux ejecutándose en su centro de datos de EE. UU. El servidor de PowerShell Universal, que se ejecuta en su centro de datos de la UE, tiene configurado un event hub llamado Linux. En el servidor, configuraría el hub mediante el fichero eventHubs.ps1 o desde la consola de administración.

New-PSUEventHub -Name 'Linux'

En el lado del agente, configuraría entonces un fichero agent.ps1 para indicar al agente dónde debe conectarse al servidor.

{
    "Connections": [
        {
            "Url": "http://eu.mycompany.local",
            "Hub": "Linux"
        }
    ]
}

Con el event hub creado y el agente configurado, el agente se conectará al servidor y ya podrá aceptar comandos.

Dentro del servidor, puede crear un script que se ejecute contra el agente. Aunque el script en sí no se ejecuta contra el agente, puede utilizar el cmdlet integrado Invoke-PSUCommand para hacerlo. Dentro de su script, podría recopilar información del host. Como se especifica el parámetro -Computer, este comando se ejecutará directamente contra el agente y devolverá el nombre del host al script que se ejecuta en el servidor.

Invoke-PSUCommand -Command "hostname" -Computer "linuxhost-12" 

Además, puede realizar acciones contra todo el hub de agentes conectados. Si quisiera, por ejemplo, reiniciar todos los agentes conectados, podría extenderse por todo el hub.

Invoke-PSUCommand -Command "reboot" -Hub "Linux"

Crear un event hub

Para crear un event hub, haga clic en API \ Event Hub y luego en Create New Event Hub. Los Event Hubs tienen un nombre y pueden aplicar autenticación y autorización.

Agente

Deberá instalar y configurar el agente de PowerShell Universal para utilizar los Event Hubs. El agente está disponible en varias plataformas, como MSI instalable en Windows y como imagen de contenedor Docker.

Si el registro del agente informa de `Event Hub not found`, verifique primero que el valor `Hub` en `agent.json` coincide exactamente con un Event Hub configurado en la instancia de PowerShell Universal de destino. En configuraciones habituales, esto significa que el agente llegó al servidor pero el hub indicado aún no existe allí o los nombres no coinciden.

Enviar eventos

Desde el servidor de PowerShell Universal, puede enviar eventos desde un hub a los clientes conectados mediante el cmdlet Send-PSUEvent (Invoke-PSUCommand es un alias de Send-PSUEvent).

Send-PSUEvent -Hub 'MyHub' -Data "Hello!"

El parámetro -Data acepta un objeto que se serializará mediante CLIXML y se enviará al cliente. Los datos se deserializarán antes de pasarlos al bloque de script.

También puede ejecutar comandos. Esto no requiere definir un script en el cliente del event hub. También puede utilizar el alias Invoke-PSUCommand para imitar el comportamiento nativo de PowerShell.

Invoke-PSUCommand -Hub "MyHub" -Command "Start-Process" -Parameters @{
    FilePath = "Notepad"
}

Inspeccionar las conexiones actuales

Utilice Get-PSUEventHubConnection -Active para ver los agentes que están conectados en este momento.

Get-PSUEventHubConnection -Hub 'eventHub' -Active

El comando sin filtrar también puede incluir conexiones antiguas desconectadas, por lo que -Active es la vista de resolución de problemas más rápida cuando desea confirmar si un agente está actualmente en línea. Si necesita dirigirse a un cliente concreto, utilice el ConnectionId devuelto con Send-PSUEvent.

Recibir datos de los clientes

Esta función solo está disponible al enviar datos a un cliente individual, en lugar de a todos los clientes conectados a un hub.

$Connection = Get-PSUEventHubConnection | Where-Object UserName -eq 'Admin'
$Result = Send-PSUEvent -Hub 'Hub' -Data 'Say Hello!' -Connectionid $Connection.ConnectionId
Show-UDToast $Result

Ejemplo: ejecutar scripts en máquinas remotas

Este ejemplo ofrece una forma de ejecutar scripts en máquinas remotas sin tener que instalar otra instancia de PowerShell Universal.

Este ejemplo permite enviar scripts a máquinas remotas y ejecutarlos con un script genérico de event hub.

En primer lugar, cree un event hub en PowerShell Universal. Este ejemplo no utiliza autenticación.

A continuación, instale el agente de PowerShell Universal en la máquina remota. Cree un fichero de configuración en %ProgramData%\PowerShellUniversal\agent.json.

{
    "Connections": [
        {
            "Url": "http://localhost:5000",
            "Hub": "eventHub",
            "ScriptPath": "script.ps1"
        }
    ]
}

Después, cree un script auxiliar script.ps1 para recibir los datos del event hub y procesar las solicitudes de PSU para invocar scripts. Crea un nuevo fichero PS1 temporal y utiliza el $EventData transmitido desde el mensaje del event hub con el contenido y los parámetros del script.

$TempFile = (New-TemporaryFile).FullName + ".ps1"
$EventData.Contents | Out-File -FilePath $TempFile
$Parameters = $EventData.Parameters
& $TempFile @Parameters

En PowerShell Universal, añada un script que desee ejecutar en la máquina remota. En este ejemplo, simplemente inicia un proceso.

param($Name)

Start-Process $Name

Por último, añada otro script que envíe el evento al cliente. Esto también podría hacerse desde una API o una aplicación. Como el script del agente es genérico, simplemente ejecutará lo que se le pase.

param($TargetComputer, $ProcessName)
 
Send-PSUEvent -Computer $TargetComputer -Data @{
    Contents = Get-Content StartAProcess.ps1 -Raw
    Parameters = @{
        Name = $ProcessName
    }
}

A partir de aquí, incluso podría utilizar el script para programar trabajos que se ejecuten en las máquinas remotas mediante el agente.