For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agent

PowerShell Universal prend en charge deux implémentations d'agent distant. Utilisez Devolutions Agent pour les nouveaux déploiements. Il se connecte à PowerShell Universal via gRPC et prend en charge les tâches distantes, les groupes d'ordinateurs, les commandes de communication à distance PowerShell et les environnements virtuels multi-pwsh. L'agent PowerShell Universal Agent demeure disponible pour l'automatisation basée sur Event Hub.

Devolutions Agent

Devolutions Agent est l'agent recommandé pour les nouvelles installations. Il établit une connexion gRPC sortante et authentifiée vers PowerShell Universal; la communication à distance PowerShell n'a pas besoin d'être configurée entre le serveur et l'ordinateur géré.

Téléchargez l'installateur Windows depuis le Centre de téléchargement Devolutions. Pour les déploiements en conteneur, utilisez l'image devolutions/powershell-universal-agent de Docker Hub.

Prérequis et connectivité

Installez Devolutions Agent sur l'ordinateur qui exécutera les tâches. L'agent doit pouvoir atteindre le point de terminaison gRPC de PowerShell Universal via HTTP/2. Dans la configuration de développement par défaut, il s'agit du port 5006; utilisez le point de terminaison HTTPS en production.

Chaque agent a besoin d'un ID d'agent unique et stable. Lorsque l'agent se connecte, PowerShell Universal crée ou met à jour un enregistrement d'ordinateur de type Agent, le marque comme étant en ligne et ajoute des étiquettes pour son nom de machine, son système d'exploitation, son architecture, ses hubs et ses capacités. Utilisez ces étiquettes pour cibler l'agent avec des groupes d'ordinateurs.

Créer un jeton d'application

Créez un jeton d'application dédié pour chaque Devolutions Agent. Le jeton doit avoir le rôle intégré Agent. Ce rôle est volontairement limité à l'enregistrement de l'agent et n'accorde pas de permissions sur l'API de gestion; n'utilisez donc pas de nouveau un jeton d'administrateur ou d'automatisation.

Grant-PSUAppToken `
  -IdentityName 'devolutions-agent-01' `
  -Role 'Agent' `
  -Description 'Devolutions Agent on production-01' `
  -Expiry (Get-Date).AddYears(1)

Stockez le jeton retourné comme un secret. Faites-le pivoter avant son expiration et remplacez-le dans la configuration de l'agent. L'agent ne peut pas se connecter avec un jeton manquant, invalide ou n'ayant pas le rôle Agent.

Configurer l'agent

L'installateur Windows peut activer la fonctionnalité PowerShell Universal Agent et recueillir l'URL du serveur PowerShell Universal, le jeton d'application, l'ID de l'agent et le nom d'affichage. L'agent peut aussi être configuré dans agent.json.

AppToken accepte soit la valeur du jeton, soit une référence $secret:<name> résolue par PowerShell SecretManagement. AgentId est l'identifiant utilisé pour cibler l'agent. DisplayName est un nom convivial affiché dans PowerShell Universal. Hubs devient des étiquettes d'ordinateur Hub. PowerShell peut sélectionner une version multi-pwsh, utiliser un chemin d'exécutable spécifique ou utiliser Windows PowerShell.

Pour l'image de conteneur Linux, fournissez PSU_SERVER_URL et PSU_APP_TOKEN; les deux sont requis pour activer l'intégration PSU.

Exécuter des tâches sur un agent

Une fois que l'agent apparaît dans Manage > Computers & Groups > Computers, créez un groupe d'ordinateurs dont les étiquettes le sélectionnent. Par exemple, un agent configuré avec "Hubs": ["production"] possède une étiquette Hub ayant la valeur production; un groupe d'ordinateurs avec l'étiquette production sélectionne cet agent.

Attribuez le groupe d'ordinateurs à un script ou à une planification, puis choisissez si l'exécution doit se faire sur n'importe quel ordinateur correspondant ou sur tous les ordinateurs correspondants. Vous pouvez aussi invoquer un script sur un seul agent en utilisant son ID d'agent comme file d'attente.

Seuls les agents en ligne qui ne sont pas en mode maintenance sont sélectionnés. Une invocation de groupe configurée pour All crée une tâche pour chaque agent correspondant; Any sélectionne un seul agent correspondant.

Exécuter des commandes avec Invoke-PSUCommand

Invoke-PSUCommand est un alias de Send-PSUEvent. Utilisez -Computer pour exécuter sur un ID d'agent en particulier, ou -ComputerGroup pour exécuter sur chaque ordinateur correspondant d'un groupe. La commande retourne la sortie du pipeline et écrit localement les flux distants d'avertissement, d'information, détaillé et d'erreur.

Utilisez -Timeout pour permettre des commandes de plus longue durée. L'agent doit rester connecté pendant toute l'invocation.

Utiliser des environnements virtuels multi-pwsh

Pour un environnement d'exécution isolé ou en conteneur avec un environnement virtuel activé, PowerShell Universal empaquette automatiquement l'environnement virtuel multi-pwsh sélectionné et demande à l'agent distant de l'importer avant le début de la tâche. L'agent héberge ensuite la tâche avec la version de PowerShell et le nom d'environnement virtuel correspondants.

Utilisez ceci pour livrer les modules requis par une tâche :

  1. Créez ou mettez à jour l'environnement virtuel dans PowerShell Universal et installez-y les modules requis.

  2. Sélectionnez cet environnement isolé ou en conteneur pour le script.

  3. Ciblez Devolutions Agent directement ou par l'entremise d'un groupe d'ordinateurs.

L'importation s'exécute via multi-pwsh venv import. Vous n'avez pas besoin de copier manuellement les modules vers l'agent; gardez la définition de l'environnement virtuel et ses modules sous la gestion de PowerShell Universal afin que l'agent reçoive le paquet attendu.

Ce que PowerShell Universal transfère

PowerShell Universal crée un dépôt distant sous le répertoire temporaire de l'agent, à PowerShellUniversal/Repository, avec les dossiers Scripts et Modules. Le dossier Modules du dépôt est ajouté au chemin des modules PowerShell distant.

Pour une tâche de script, PowerShell Universal transfère le script de démarrage de la tâche vers le dossier Scripts distant et exécute la tâche par l'entremise du flux de communication à distance PowerShell gRPC. Ce transfert se fait à chaque exécution : le script de démarrage copié est supprimé une fois la tâche terminée. La console d'administration ne fournit pas d'action Install on Agent ni de paramètre Keep run scripts on agents.

Lorsque l'environnement sélectionné utilise un environnement virtuel multi-pwsh, son paquet est importé avant l'exécution de la tâche. Ne présumez pas que des fichiers de serveur, des secrets ou des modules arbitraires installés en dehors de l'environnement virtuel sélectionné sont transférés à l'agent; provisionnez-les explicitement dans l'environnement ou sur l'ordinateur géré.

PowerShell Universal Agent

PowerShell Universal Agent est l'agent original basé sur Event Hub. Il exécute un script local ou une commande PowerShell directe après avoir reçu une invocation Event Hub via WebSockets. Utilisez-le lorsque vous avez besoin d'un flux de travail Event Hub existant; utilisez Devolutions Agent pour les nouveaux déploiements de tâches distantes.

Configurer agent.json

Créez agent.json après l'installation. Stockez-le sous $env:ProgramData\PowerShellUniversal pour un agent à l'échelle du système, ou sous $env:AppData\PowerShellUniversal pour un agent par utilisateur.

Url et Hub sont requis. Authentifiez-vous avec AppToken ou UseDefaultCredentials. ScriptPath est optionnel, car les Event Hubs peuvent invoquer directement des commandes PowerShell. Un chemin de script relatif est résolu à partir du répertoire de données de PowerShell Universal; utilisez un chemin absolu lorsque le script est stocké ailleurs.

Envoyer des commandes Event Hub

Utilisez Invoke-PSUCommand ou Send-PSUEvent pour invoquer l'Event Hub configuré. Pour des exemples spécifiques aux Event Hubs et les options d'invocation, consultez Event Hubs.

Mis à jour

Ce contenu vous a-t-il été utile ?