Partager via

Changements du comportement dans PowerShell Desired State Configuration pour la configuration de machine

  • Article

Avant de commencer, nous vous conseillons de lire la présentation de la configuration de machine.

Un guide vidéo de ce document est disponible.

La configuration de machine utilise PowerShell Desired State Configuration (PSDSC) version 3 pour auditer et configurer des machines. La configuration DSC définit l’état dans lequel la machine doit se trouver. Il y a de nombreuses différences notables dans la façon dont DSC est implémenté dans la configuration de machine.

La configuration de machine utilise PowerShell 7 multiplateforme

La configuration de machine est conçue de façon à ce que l’expérience de gestion de Windows et Linux puisse être cohérente. Dans les deux environnements de système d’exploitation, une personne disposant d’une connaissance de PowerShell DSC peut créer et publier des configurations en mobilisant ses compétences en matière d’écriture de script.

La configuration d'ordinateur utilise uniquement PowerShell DSC version 3 et ne s’appuie pas sur l’implémentation précédente de DSC pour Linux ou les fournisseurs nx* inclus dans ce référentiel.

À partir de la version 1.26.33, la configuration de machine fonctionne dans PowerShell 7.1.2 pour Windows et PowerShell 7.2 préversion 6 pour Linux. Depuis la version 7.2, le module PSDesiredStateConfiguration ne fait plus partie de l’installation de PowerShell, mais est installé en tant que module de PowerShell Gallery.

Configurations multiples

La configuration de machine prend en charge l’attribution de plusieurs configurations à la même machine. Aucune action particulière n’est requise dans le système d’exploitation de l’extension de configuration de machine. Il n’est pas nécessaire de configurer des configurations partielles.

Les dépendances sont gérées par configuration

Quand une configuration est ajoutée à un package au moyen des outils disponibles, les dépendances requises pour la configuration sont incluses dans un fichier .zip. Les machines extraient le contenu dans un dossier unique pour chaque configuration. L’agent fourni par l’extension de configuration d'ordinateur crée une session PowerShell dédiée pour chaque configuration. Il utilise un $Env:PSModulePath qui limite le chargement automatique du module uniquement au chemin d’accès où le package a été extrait.

Cette modification présente plusieurs avantages :

  • Il est possible d’utiliser des versions de modules différentes pour chaque configuration sur une même machine.
  • Lorsqu’une configuration n’est plus nécessaire sur un ordinateur, l’agent supprime en toute sécurité l’intégralité du dossier dans lequel la configuration a été extraite. Vous n’avez pas besoin de gérer les dépendances partagées entre les configurations.
  • Il n’est pas nécessaire de gérer plusieurs versions d’un module dans un service central.

Les artefacts sont gérés sous forme de packages

La fonctionnalité Azure Automation State Configuration comprend la gestion des artefacts pour les modules et les scripts de configuration. Une fois que les deux sont publiés dans le service, le script peut être compilé au format MOF. De la même façon, le serveur Pull Windows nécessitait également une gestion des configurations et des modules au niveau de l’instance du service web. Au contraire, l’extension DSC offre un modèle simplifié où tous les artefacts sont regroupés dans un package qui est stocké à un emplacement accessible à partir de l’ordinateur cible via une requête HTTPS. Stockage Blob Azure est l’option populaire pour héberger les artefacts.

La configuration de machine utilise uniquement le modèle simplifié où tous les artefacts sont regroupés dans un package accessible à partir de la machine cible via HTTPS. Il n’est pas nécessaire de publier des modules ou des scripts, ni de les compiler dans le service. L’un des changements est que le package doit toujours inclure un MOF compilé. Il n’est pas possible d’inclure un fichier de script dans le package et de le compiler sur l’ordinateur cible.

Taille maximale du package de configuration personnalisée

Dans Azure Automation State Configuration, les configurations DSC étaient limitées en taille. La configuration d'ordinateur prend en charge une taille de package totale de 100 Mo avant compression. Il n’existe aucune limite spécifique quant à la taille du fichier MOF au sein du package.

Le mode de configuration est défini dans l’artefact de package

Lors de la création du package de configuration, le mode est défini à l’aide des options suivantes :

  • Audit : vérifie la conformité d’un ordinateur. Aucune modification n’est apportée.
  • AuditandSet : vérifie et corrige l’état de conformité de l’ordinateur. Des modifications sont apportées si la machine n’est pas conforme.

Le mode est défini dans le package plutôt que dans le service Local Configuration Manager, car chaque configuration peut être appliquée avec un mode différent.

Prise en charge de paramétrage via Azure Resource Manager

Les paramètres définis par le tableau de propriétés configurationParameter dans les affectations de configuration d’ordinateur remplacent le texte statique dans un fichier MOF de configuration lorsque celui-ci est stocké sur un ordinateur. Les paramètres rendent la personnalisation possible et permettent à un opérateur de contrôler les modifications à partir de l’API de service sans avoir besoin d’exécuter des commandes à l’intérieur de l’ordinateur.

Les paramètres d’Azure Policy qui transmettent des valeurs à des attributions de configuration de machine doivent être de type chaîne. Il n’est pas possible de passer des tableaux en paramètre, même si la ressource DSC les prend en charge.

Déclencheur défini à partir d’une machine extérieure

Un problème rencontré dans les versions précédentes de DSC était de corriger la dérive à grande échelle en utilisant peu de code personnalisé, et la dépendance de connexions à distance WinRM. Une configuration d’invité résout ce problème. Les utilisateurs d’une configuration de machine contrôlent la correction de la dérive via une correction à la demande.

La séquence contient une méthode Get

Quand une configuration de machine audite ou configure une machine, la même séquence d’événements est utilisée pour Windows et Linux. Le changement de comportement notable est que le service appelle la méthode Get pour retourner des détails sur l’état de l’ordinateur.

  1. L’agent exécute d’abord Test pour déterminer si la configuration est dans l’état approprié.
  2. Si le package est défini sur Audit, la valeur booléenne retournée par la fonction détermine si l’état Azure Resource Manager de l’affectation d’invité doit être Compliant ou NonCompliant.
  3. Si le package est défini sur AuditandSet, la valeur booléenne détermine s’il faut corriger la machine en appliquant la configuration à l’aide de la méthode Set. Si la méthode Test retourne $false, Set est exécuté. Si Test retourne $true, Set n’est pas exécuté.
  4. Enfin, le fournisseur exécute Get pour retourner l’état actuel de chaque paramètre, afin que des détails soient disponibles à la fois sur la raison pour laquelle un machine n’est pas conforme et pour confirmer que l’état actuel est conforme.

Exigences particulières pour la méthode Get

La méthode Get DSC a des exigences particulières pour la configuration d’ordinateur qui n’ont pas été nécessaires pour DSC.

  • La table de hachage retournée doit inclure une propriété nommée Reasons.
  • La propriété Reasons doit être un tableau.
  • Chaque élément du tableau doit être une table de hachage avec les clés Code et Phrase.
  • Aucune autre valeur que la table de hachage ne doit être renvoyée.

La propriété Reasons est utilisée par le service pour normaliser la manière dont les informations sont présentées. Vous pouvez considérer chaque élément dans la propriété Reasons comme un message expliquant pourquoi la ressource est conforme ou non. La propriété est un tableau, car une ressource peut ne pas être conforme pour plusieurs raisons.

Les propriétés Code et Phrase sont attendues par le service. Lorsque vous créez une ressource personnalisée, définissez le texte que vous souhaitez afficher pour expliquer pourquoi la ressource n’est pas conforme à la valeur de Phrase. Code a des exigences de mise en forme spécifiques, visant à afficher clairement les informations sur la ressource utilisée pour effectuer l’audit. Cette solution rend la configuration d’invité extensible. Vous pouvez exécuter n’importe quelle commande tant que la sortie peut être retournée sous forme de valeur de chaîne pour la propriété Phrase.

  • Code (chaîne) : nom de la ressource, répété, puis un nom abrégé sans espaces comme identificateur de la raison. Ces trois valeurs doivent être séparées par des points-virgules, sans espaces.
    • Par exemple, registry:registry:keynotpresent.
  • Phrase (chaîne) : texte lisible par l’utilisateur expliquant pourquoi le paramètre n’est pas conforme.
    • Par exemple, The registry key $key isn't present on the machine..
$reasons = @()
$reasons += @{
  Code   = 'Name:Name:ReasonIdentifer'
  Phrase = 'Explain why the setting is not compliant'
}
return @{
    reasons = $reasons
}

Lorsque vous utilisez des outils de ligne de commande pour obtenir des informations qui sont renvoyées dans Get, vous pouvez constater que l’outil renvoie une sortie à laquelle vous ne vous attendiez pas. Même si vous capturez la sortie dans PowerShell, la sortie a également pu être écrite dans une erreur standard. Pour éviter ce problème, pensez à rediriger la sortie vers la valeur Null.

Classe incorporée de la propriété Reasons

Dans les ressources basées sur un script (Windows uniquement), la classe Reasons est incluse dans le fichier MOF de schéma comme suit.

[ClassVersion("1.0.0.0")]
class Reason
{
  [Read] String Phrase;
  [Read] String Code;
};

[ClassVersion("1.0.0.0"), FriendlyName("ResourceName")]
class ResourceName : OMI_BaseResource
{
  [Key, Description("Example description")] String Example;
  [Read, EmbeddedInstance("Reason")] String Reasons[];
};

Dans les ressources basées sur une classe (Windows et Linux), la classe Reason est incluse dans le module PowerShell comme suit. Linux respectant la casse, le C de Code et le P de Phrase doivent être en majuscules.

enum ensure {
  Absent
  Present
}

class Reason {
  [DscProperty()]
  [string] $Code

  [DscProperty()]
  [string] $Phrase
}

[DscResource()]
class Example {

  [DscProperty(Key)]
  [ensure] $ensure

  [DscProperty()]
  [Reason[]] $Reasons

  [Example] Get() {
    # return current current state
  }

  [void] Set() {
    # set the state
  }

  [bool] Test() {
    # check whether state is correct
  }
}

Si la ressource requiert certaines propriétés, celles-ci doivent également être retournées par Get en parallèle avec la classe Reason. Si Reason n’est pas inclus, le service inclut un comportement « catch-all » qui compare les valeurs entrées dans Get et celles retournées par Get, et fournit une comparaison détaillée comme Reason.

Noms de configuration

Le nom de la configuration personnalisée doit être cohérent partout. Ces éléments doivent avoir le même nom :

  • Fichier .zip du package de contenu
  • Nom de configuration dans le fichier MOF
  • Nom de l’affectation de configuration d’ordinateur dans le modèle de Resource Manager Azure

Exécution de commandes dans Windows PowerShell

L’exécution de modules Windows dans PowerShell peut être effectuée à l’aide du modèle ci-dessous dans vos ressources DSC. Le modèle ci-dessous configure temporairement PSModulePath pour qu’il exécute Windows PowerShell au lieu de PowerShell afin de découvrir les modules nécessaires qui sont disponibles dans Windows PowerShell. Cet exemple est un extrait de code adapté de la ressource DSC qui est utilisé dans la ressource DSC intégrée Serveur web sécurisé.

Ce modèle configure temporairement le chemin d’exécution de PowerShell pour qu’il s’exécute à partir de Windows PowerShell et découvre l’applet de commande nécessaire qui, dans ce cas, est Get-WindowsFeature. La sortie de la commande est retournée, puis normalisée pour respecter les exigences de compatibilité. Une fois l’applet de commande exécutée, $env:PSModulePath est défini sur le chemin d’origine.

# The Get-WindowsFeature cmdlet needs to be run through Windows PowerShell
# rather than through PowerShell, which is what the Policy engine runs.
$null = Invoke-Command -ScriptBlock {
    param ([string]$FileName)

    $InitialPSModulePath   = $env:PSModulePath
    $WindowsPSFolder       = "$env:SystemRoot\System32\WindowsPowershell\v1.0"
    $WindowsPSExe          = "$WindowsPSFolder\powershell.exe"
    $WindowsPSModuleFolder = "$WindowsPSFolder\Modules"
    $GetFeatureScriptBlock = {
        param([string]$FileName)

        if (Get-Command -Name Get-WindowsFeature -ErrorAction SilentlyContinue) {
            Get-WindowsFeature -Name Web-Server |
                ConvertTo-Json |
                Out-File $FileName
        } else {
            Add-Content -Path $FileName -Value 'NotServer'
        }
    }

    try {
        # Set env variable to include Windows Powershell modules so we can find
        # the Get-WindowsFeature cmdlet.
        $env:PSModulePath = $WindowsPSModuleFolder
        # Call Windows PowerShell to get the info about the Web-Server feature
        & $WindowsPSExe -command $WindowsFeatureScriptBlock -args $FileName
    } finally {
        # Reset the env variable even if there's an error.
        $env:PSModulePath = $InitialPSModulePath
    }
}

Fonctionnalités DSC courantes non disponibles pendant la préversion publique de la configuration de machine

Dans la préversion publique, la configuration d’ordinateur ne prend pas en charge la spécification de dépendances entre machines avec les ressources WaitFor*. Il n’est pas possible pour un ordinateur d’observer un autre ordinateur en attendant qu’il atteigne un état déterminé avant de progresser.

La gestion du redémarrage n’est pas disponible dans la préversion publique de la configuration de machine. Notamment, l’état $global:DSCMachineStatus n’est pas disponible. Les configurations ne peuvent pas redémarrer un nœud au cours ou à la fin d’une configuration.

Problèmes de compatibilité connus avec les modules pris en charge

Le module PsDscResources dans PowerShell Gallery et le module PSDesiredStateConfiguration fourni avec Windows sont pris en charge par Microsoft, et constituent un ensemble couramment utilisé de ressources pour DSC. En attendant que le module PSDscResources soit mis à jour pour DSCv3, vous devez être conscient des problèmes de compatibilité connus suivants.

  • N’utilisez pas les ressources du module PSDesiredStateConfiguration fourni avec Windows. Au lieu de cela, passez à PSDscResources.
  • N’utilisez pas les ressources WindowsFeature, WindowsFeatureSet, WindowsOptionalFeature, et WindowsOptionalFeatureSet dans PsDscResources. Un problème connu est survenu lors du chargement du module DISM dans PowerShell 7.1.3 sur Windows Server, ce qui nécessite une mise à jour.

Les ressources nx* pour Linux qui étaient incluses dans le référentiel DSC pour Linux ont été écrites dans une combinaison des langages C et Python. Comme la voie à suivre pour DSC pour Linux consiste à utiliser PowerShell, les ressources nx* existantes ne sont pas compatibles avec DSCv3. Jusqu’à ce qu’un nouveau module contenant les ressources prises en charge pour Linux soit disponible, il est nécessaire de créer des ressources personnalisées.

Coexistence avec DSC version 3 et versions antérieures

DSC version 3 dans la configuration de machine peut coexister avec des versions plus anciennes installées dans Windows et Linux. Les implémentations sont séparées. Toutefois, étant donné qu’il n’y a pas de détection des conflits entre les versions de DSC, ne tentez pas de gérer les mêmes paramètres.

Étapes suivantes