Partager via

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

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 de commande DSC 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 comme des fichiers de données. Pour que DSC reconnaisse un fichier de données en tant que manifeste, le fichier doit répondre aux critères suivants :

  1. Les données du fichier doivent être au format YAML ou JSON.

  2. Le fichier doit utiliser l’encodage UTF-8.

  3. Le fichier doit être détectable dans la variable d’environnement PATH .

  4. Le nom de fichier doit se terminer par l’un des suffixes suivants :

    • .dsc.resource.json
    • .dsc.resource.yaml
    • .dsc.resource.yml

Lorsque DSC recherche dans le système local des ressources de commande disponibles, il recherche dans chaque dossier du PATH le les fichiers qui utilisent la convention de dénomination 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 est validé 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 il est compatible.
  • Nom complet de la ressource, par exemple Microsoft.Windows/Registry. La syntaxe de nom complet est <owner>[.<group>][.<area>]/<name>. Les composants de groupe et d’aire 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 instance de ressource.
  • Un moyen de valider une instance. Les options de validation d’une instance sont les suivantes :
    • Un schéma JSON qui décrit une instance
    • Une commande DSC doit être appelée pour obtenir le schéma au moment de l’exécution
    • Commande permettant de valider les ressources DSC imbriquées. Cette dernière option s’applique uniquement aux ressources de groupe DSC et aux ressources d’adaptateur DSC.

Le manifeste peut définir :

  • Type de ressource décrit par le manifeste : adapter, group, importerou resource.

    Si le manifeste ne définit pas le type de ressource, il est interprété par défaut resource comme une ressource typique qui gère directement une instance.

  • Comment DSC peut appeler la commande pour tester si une instance est dans l’état souhaité.

    Si le manifeste ne définit pas comment tester une 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’une instance et effectue une comparaison stricte des propriétés de l’instance à l’état souhaité, sensible à la casse. Si l’une des propriétés n’est pas exactement la même que l’état souhaité défini, DSC signale que l’instance n’est pas conforme.

  • Comment DSC peut appeler la commande pour définir une instance à l’état souhaité.

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

  • Signification des codes de sortie non nuls renvoyés par la commande.

    Si le manifeste ne définit pas la signification des codes de sortie, tous les codes de sortie non nuls sont signalés comme un échec générique.

  • Comment DSC peut appeler la commande pour exporter une liste de chaque instance de cette ressource sur la machine.

  • Comment DSC peut appeler la commande pour supprimer une instance spécifique de la ressource.

  • Métadonnées sur la ressource, comme son auteur et une brève description.

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 de commande nécessitent toujours un fichier exécutable pour que DSC s’exécute. Il n’est pas nécessaire d’associer le manifeste à l’exécutable. L’exécutable peut être n’importe quel fichier exécutable, tel qu’une application binaire ou un script shell. 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, à l’aide du code de sortie renvoyé par l’exécutable pour déterminer si la commande a réussi. DSC traite le code 0 de sortie comme un succès et tous les autres codes de sortie comme une erreur.

Données d'entrée

DSC envoie des entrées aux ressources de commande de l’une des manières suivantes :

  • Un objet blob de données JSON sur stdin.

    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’une instance. Cette option d’entrée prend en charge les propriétés complexes avec des objets imbriqués.

  • Un objet blob de données JSON en tant que valeur d’un argument spécifique.

    Lorsque la ressource définit un argument d’entrée JSON, DSC appelle la commande avec l’argument défini et transmet la représentation JSON de l’état souhaité d’une instance à cet argument. Cette option d’entrée prend en charge les propriétés complexes avec des objets imbriqués.

  • Un ensemble d’indicateurs et de valeurs d’arguments.

    Lorsque DSC envoie l’entrée sous forme d’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éfixée par --, par --durationexemple . 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.

  • Variables d’environnement.

    Lorsque DSC envoie l’entrée sous forme de variables d’environnement, il définit une variable d’environnement pour chaque propriété de l’instance de ressource et définit la valeur de la représentation de chaîne de cette propriété. Ces variables d’environnement ne sont définies que pour l’exécution de la commande pour cette opération spécifique. Les variables d’environnement n’affectent pas les autres processus.

La gestion des entrées est définie par opération dans le manifeste de la ressource. Une ressource peut définir différentes manipulations d’entrée pour les opérations qu’elle prend en charge.

Sorties

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

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

Les ressources de commande peuvent signaler des informations de journalisation à DSC en émettant des lignes JSON dans stderr. Chaque entrée de journal doit être un objet JSON qui inclut deux clés :

  1. La message clé définit la chaîne lisible par l’homme pour l’entrée de journal.
  2. La level clé définit si le message représente un , un warningou informationun error.

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, DSC émet les messages vers stderr.

Contenu associé

  • Last updated on