Event Hubs

Gli Event Hubs richiedono una licenza.

Gli Event Hubs offrono la possibilità di inviare comandi PowerShell agli agent PowerShell Universal connessi dal server PowerShell Universal. Gli agent sono servizi leggeri e multipiattaforma che possono essere eseguiti sui nodi edge per consentire a PowerShell Universal di impartire comandi verso di essi.

Gli Event Hubs funzionano con un metodo di comunicazione uno-a-uno dal server all'agent oppure con un metodo di comunicazione fan out uno-a-molti da un event hub sul server verso tutti gli agent connessi. Gli agent non eseguono direttamente i job e richiedono l'uso di Invoke-PSUCommand da altri script in esecuzione all'interno del server PowerShell Universal. Può considerare gli event hub come un modo per effettuare PowerShell Remoting senza usare il trasporto di remoting standard.

Informazioni

PowerShell Universal esegue un server web con un endpoint websocket che rimane in ascolto in attesa che gli agent si connettano. Questo viene definito event hub. È possibile configurare più event hub per ogni server PowerShell Universal con nomi e impostazioni di sicurezza differenti. Una volta configurato un event hub sul server, è possibile installare un agent su qualsiasi macchina in grado di raggiungere PowerShell Universal tramite le porte HTTP standard.

L'agent richiede alcune configurazioni relative a dove e come connettersi al server. Una volta fatto questo, l'agent può essere avviato per stabilire la connessione websocket con il server. Dopo che la connessione è stata stabilita, il server è a conoscenza del client connesso. Verrà registrato all'interno dell'hub e gli eventi potranno quindi essere inviati dal server agli agent.

Sebbene non sia possibile pianificare l'esecuzione di job direttamente sugli agent, è possibile eseguire comandi verso gli agent, all'interno di job, API e app nel server.

Esempio di base

Ad esempio, potrebbe avere un agent PowerShell Universal Linux in esecuzione nel suo datacenter statunitense. Il server PowerShell Universal, in esecuzione nel suo datacenter europeo, ha un event hub configurato denominato Linux. Sul server, configurerebbe l'hub utilizzando il file eventHubs.ps1 oppure tramite la console di amministrazione.

New-PSUEventHub -Name 'Linux'

Sul lato agent, configurerebbe quindi un file agent.ps1 per indicare all'agent dove deve connettersi al server.

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

Con l'event hub creato e l'agent configurato, l'agent si connetterà al server e potrà ora accettare comandi.

All'interno del server, può creare uno script che viene eseguito verso l'agent. Sebbene lo script stesso non venga eseguito sull'agent, può utilizzare il cmdlet integrato Invoke-PSUCommand per farlo. All'interno del suo script, potrebbe raccogliere informazioni sull'host. Poiché è specificato il parametro -Computer, questo comando verrà eseguito direttamente sull'agent e restituirà il nome host allo script in esecuzione nel server.

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

Inoltre, può intraprendere azioni verso l'intero hub di agent connessi. Se, ad esempio, volesse riavviare tutti gli agent connessi, potrebbe estendere l'operazione a tutto l'hub.

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

Creazione di un event hub

Per creare un event hub, faccia clic su API \ Event Hub e faccia clic su Create New Event Hub. Gli Event Hubs hanno un nome e possono scegliere di applicare autenticazione e autorizzazione.

Agent

Sarà necessario installare e configurare l'agent PowerShell Universal per utilizzare gli Event Hubs. L'agent è disponibile su più piattaforme, come MSI installabile su Windows e come immagine di container Docker.

Se il log dell'agent riporta `Event Hub not found`, verifichi innanzitutto che il valore `Hub` in `agent.json` corrisponda esattamente a un Event Hub configurato sull'istanza PowerShell Universal di destinazione. Nelle configurazioni più comuni, ciò significa che l'agent ha raggiunto il server ma l'hub con quel nome non esiste ancora oppure i nomi non corrispondono.

Invio di eventi

All'interno del server PowerShell Universal, può inviare eventi da un hub ai client connessi utilizzando il cmdlet Send-PSUEvent (Invoke-PSUCommand è un alias di Send-PSUEvent).

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

Il parametro -Data accetta un oggetto che verrà serializzato utilizzando CLIXML e inviato al client. I dati verranno deserializzati prima di essere passati allo script block.

Può anche eseguire comandi. Ciò non richiede la definizione di uno script sul client dell'event hub. Può inoltre utilizzare l'alias Invoke-PSUCommand per riprodurre il comportamento nativo di PowerShell.

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

Ispezione delle connessioni correnti

Utilizzi Get-PSUEventHubConnection -Active per visualizzare gli agent attualmente connessi.

Get-PSUEventHubConnection -Hub 'eventHub' -Active

Il comando senza filtri può includere anche connessioni disconnesse meno recenti, quindi -Active è la vista di risoluzione dei problemi più rapida quando desidera verificare se un agent è attualmente online. Se deve indirizzare un client specifico, utilizzi il ConnectionId restituito con Send-PSUEvent.

Ricezione di dati dai client

Questa funzionalità è disponibile solo quando si inviano dati a un singolo client, anziché a tutti i client connessi 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

Esempio: esecuzione di script su macchine remote

Questo esempio offre un modo per eseguire script su macchine remote senza dover installare un'altra istanza di PowerShell Universal.

Questo esempio consente di inviare script a macchine remote ed eseguirli con uno script generico dell'event hub.

Innanzitutto, crei un event hub in PowerShell Universal. Questo esempio non utilizza l'autenticazione.

Successivamente, installi l'agent PowerShell Universal sulla macchina remota. Crei un file di configurazione in %ProgramData%\PowerShellUniversal\agent.json.

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

Successivamente, crei uno script di supporto script.ps1 per ricevere i dati dell'event hub ed elaborare le richieste da PSU per invocare gli script. Crea un nuovo file PS1 temporaneo e utilizza $EventData passato dal messaggio dell'event hub con il contenuto e i parametri per lo script.

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

In PowerShell Universal, aggiunga uno script che desidera eseguire sulla macchina remota. In questo esempio, avvia semplicemente un processo.

param($Name)

Start-Process $Name

Infine, aggiunga un altro script che invii l'evento al client. Questo potrebbe provenire anche da un'API o da un'app. Poiché lo script sull'agent è generico, eseguirà semplicemente qualsiasi cosa gli venga passata.

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

Da qui potrebbe persino utilizzare lo script per pianificare l'esecuzione di job sulle macchine remote tramite l'agent.