Anatomie d’une ressource DSC basée sur une commande

  • Article

Les ressources DSC fournissent une interface standardisée pour la gestion des paramètres d’un système. Une ressource définit les propriétés que vous pouvez gérer et implémente le code nécessaire pour obtenir une instance de la ressource.

Les ressources DSC basées sur les commandes sont définies avec au moins deux fichiers :

  1. Manifeste de ressource DSC qui indique à DSC comment interagir avec la ressource.
  2. Un ou plusieurs fichiers exécutables et leurs dépendances pour gérer les instances de la ressource.

Manifestes de ressources DSC

Les manifestes de ressources DSC sont définis en tant que fichiers JSON. Pour que DSC reconnaisse un fichier JSON en tant que manifeste, le fichier doit répondre aux critères suivants :

  1. Le fichier doit être détectable dans la variable d’environnement PATH .
  2. Le nom de fichier doit se terminer .dsc.resource.jsonpar .

Lorsque DSC recherche dans le système local les ressources DSC basées sur les commandes disponibles, il recherche dans chaque dossier du PATH fichier les fichiers qui utilisent la convention d’affectation de noms du manifeste de ressource DSC. DSC analyse ensuite chacun de ces fichiers découverts et les valide par rapport au schéma JSON du manifeste de ressource DSC.

Si le fichier JSON valide par rapport au schéma, DSC peut utiliser la ressource DSC.

Au minimum, le manifeste doit définir :

  • Version du schéma JSON du manifeste de ressource DSC avec laquelle elle est compatible.
  • Nom complet de la ressource, comme Microsoft.Windows/Registry. La syntaxe de nom complet est <owner>[.<group>][.<area>]/<name>. Les composants de groupe et de zone du nom complet permettent d’organiser les ressources en espaces de noms.
  • Comment DSC peut appeler la commande pour obtenir l’état actuel d’une ressource instance.
  • Un moyen de valider un instance. Il peut s'agir de l'une des ressources suivantes :
    • Schéma JSON qui décrit un instance
    • Une commande DSC doit appeler pour obtenir le schéma au moment de l’exécution
    • Commande pour valider les ressources DSC imbriquées. Cette dernière option s’applique uniquement aux ressources de groupe DSC et aux ressources du fournisseur DSC.

Le manifeste peut éventuellement définir :

  • Comment DSC peut appeler la commande pour tester si un instance est dans l’état souhaité.
  • Comment DSC peut appeler la commande pour définir un instance à l’état souhaité.
  • Signification des codes de sortie non nuls retournés par la commande .
  • Comment DSC peut appeler la commande pour gérer d’autres ressources DSC, quand la ressource est une ressource de groupe DSC ou une ressource de fournisseur DSC.
  • Métadonnées relatives à la ressource, comme son auteur et une brève description.

Si le manifeste ne définit pas comment tester un instance de la ressource, DSC effectue un test synthétique pour les instances de ressource. Le test synthétique de DSC obtient toujours l’état réel d’un instance et effectue une comparaison stricte des propriétés de l’instance à l’état souhaité. Le test synthétique ignore toutes les propriétés précédées d’un trait de soulignement (_) ou d’un signe dollar ($). Si l’une des propriétés n’est pas exactement identique à l’état souhaité défini, DSC signale l’instance comme étant non conforme.

Si le manifeste ne définit pas comment définir un instance de la ressource DSC, DSC ne peut pas utiliser la ressource pour appliquer l’état souhaité.

Le manifeste n’a pas besoin de spécifier le même fichier exécutable pour chaque opération. La définition de chaque opération est indépendante.

Exécutables de ressources DSC

Les ressources DSC basées sur des commandes nécessitent toujours un fichier exécutable pour que DSC s’exécute. Le manifeste de ressource DSC n’a pas besoin d’être groupé avec l’exécutable. L’exécutable peut être n’importe quel fichier exécutable, tel qu’une application binaire ou un script d’interpréteur de commandes. Une ressource peut utiliser différents exécutables pour différentes opérations.

Pour que DSC utilise un exécutable, il doit être détectable dans la variable d’environnement PATH . DSC appelle l’exécutable une fois par opération, en utilisant le code de sortie retourné par l’exécutable pour déterminer si la commande a réussi. DSC traite le code 0 de sortie comme une réussite et tous les autres codes de sortie comme une erreur.

Entrées

DSC envoie l’entrée aux ressources DSC basées sur les commandes en tant qu’objet blob de données JSON sur stdin ou en tant qu’ensemble d’indicateurs et de valeurs d’argument. La gestion des entrées est définie par opération dans le manifeste de ressource DSC.

Lorsque DSC envoie l’entrée au format JSON sur stdin, l’objet blob de données est la représentation JSON de l’état souhaité d’un instance. Il s’agit de l’option la plus robuste pour une ressource, car elle permet à la ressource de prendre en charge des propriétés complexes avec des objets imbriqués.

Lorsque DSC envoie l’entrée en tant qu’arguments, il génère une paire d’arguments pour chacune des propriétés spécifiées. Le premier argument est le nom de la propriété précédée de --, par exemple --duration. Le deuxième argument est la valeur de la propriété. L’ordre des paires d’arguments n’est pas garanti. Cette méthode d’entrée ne prend pas en charge les propriétés complexes.

Sorties

L’exécutable d’une ressource DSC basée sur une commande doit retourner des données JSON à stdout lorsqu’elle est appelée par DSC. L’encodage de sortie doit être UTF-8. Lorsque la ressource retourne l’état d’un instance, DSC valide les données JSON par rapport au schéma instance de la ressource.

Pour les ressources du fournisseur DSC, DSC s’attend à ce que l’exécutable passe par les états instance pour les ressources qu’il gère sous la forme d’un tableau JSON unique ou d’une série de lignes JSON.

Les ressources DSC basées sur des commandes peuvent signaler des informations de journalisation à DSC en émettant des lignes JSON à stderr. Chaque entrée de journal doit être un objet JSON qui comprend deux clés :

  1. La message clé définit la chaîne lisible par l’utilisateur pour l’entrée de journal.
  2. La level clé définit si le message représente un Error, un Warningou Information.

DSC collecte les messages des ressources et les affiche dans les résultats d’une opération de configuration. Lorsque DSC appelle une ressource directement en dehors d’une configuration, il ne collecte pas les messages. Au lieu de cela, ils sont simplement émis à stderr.

Contenu associé