Extension de configuration d’état souhaité avec des modèles Azure Resource Manager

Article
12/22/2024

Remarque

Avant d’activer l’extension DSC, sachez qu’une version plus récente de DSC est désormais en disponibilité générale. Elle est gérée par la fonctionnalité de configuration d’ordinateur. La fonctionnalité de configuration d’ordinateur inclut les fonctionnalités du gestionnaire d’extension Desired State Configuration (DSC) et les fonctionnalités les plus couramment demandées selon les commentaires des clients. La configuration d’ordinateur inclut également la prise en charge des ordinateurs hybrides par le biais des serveurs avec Arc.

Cet article décrit le modèle Azure Resource Manager destiné au gestionnaire de l’extension Configuration d’état souhaité (DSC).

Remarque

Vous pouvez rencontrer des exemples de schéma légèrement différents. Le schéma a été modifié dans la version d’octobre 2016. Pour plus d’informations, consultez Mettre à jour à partir d’un format antérieur.

Exemple Bicep pour une machine virtuelle

L’extension DSC hérite des propriétés par défaut de l’extension. Pour plus d’informations, consultez la classe VirtualMachineExtension.

@description('URI of the configuration package')
param configUri string

@description('first configuration parameter')
param arg1 string

@description('second configuration parameter')
@secure()
param arg2 string

var configName = split(split(configUri, '/')[4], '.')[0]

resource vm 'Microsoft.Compute/virtualMachines@2023-09-01' existing = {
  name: srvName
}

resource configuration_dscext 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: 'configurationname_dscext'
  parent: vm
  location: location
  properties: {
    publisher: 'Microsoft.Powershell'
    type: 'DSC'
    typeHandlerVersion: '2.77'
    autoUpgradeMinorVersion: true
    settings: {
      wmfVersion: 'latest'
      configuration: {
        url: configUri
        script: 'configurationname_dscext.ps1'
        function: 'configurationname_dscext'
      }
      configurationArguments: {
        arg1: arg1
      }
      advancedOptions: {
        rebootNodeIfNeeded: true
      }
    }
    protectedSettings: {
      configurationArguements: {
        arg2: arg2
      }
    }
  }
}

Exemple Bicep pour des groupes de machines virtuelles Windows identiques

Un nœud de groupe de machines virtuelles identiques a une section qui inclut un attribut extensionProfile. Sous Extensions, ajoutez les détails nécessaires pour l’extension DSC.

Pour plus d’informations sur la création de modèles qui déploient des extensions pour des groupes de machines virtuelles identiques, consultez le document Microsoft.Compute virtualMachineScaleSets

L’extension DSC hérite des propriétés par défaut de l’extension. Pour plus d’informations, consultez la classe VirtualMachineScaleSetExtension.

Paramètres ou protectedSettings

Tous les paramètres sont enregistrés dans un fichier texte de paramètres sur la machine virtuelle. Les propriétés répertoriées sous settings sont des propriétés publiques. Les propriétés publiques ne sont pas chiffrées dans le fichier texte des paramètres. Les propriétés définies sous protectedSettings sont chiffrées avec un certificat et ne sont pas affichées en texte brut dans le fichier de paramètres sur la machine virtuelle.

Si des informations d’identification sont requises pour la configuration, vous pouvez inclure ces informations dans protectedSettings :

"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
               "userName": "UsernameValue1",
               "password": "PasswordValue1"
        }
    }
}

Exemple à l’aide du script de configuration dans le stockage Azure

L’exemple suivant est extrait de la vue d’ensemble du gestionnaire d’extensions DSC. Cet exemple utilise des modèles Resource Manager au lieu d’applets de commande pour déployer l’extension. Enregistrez la configuration IisInstall.ps1, placez-la dans un fichier .zip (exemple : iisinstall.zip), puis chargez le fichier dans une URL accessible. Cet exemple utilise le stockage Blob Azure, mais vous pouvez télécharger les fichiers .zip depuis n’importe quel emplacement arbitraire.

Dans le modèle Resource Manager, le code suivant demande à la VM de télécharger le fichier correct puis d’exécuter la fonction PowerShell appropriée :

"settings": {
    "configuration": {
        "url": "https://demo.blob.core.windows.net/iisinstall.zip",
        "script": "IisInstall.ps1",
        "function": "IISInstall"
    }
},
"protectedSettings": {
    "configurationUrlSasToken": "odLPL/U1p9lvcnp..."
}

Mettre à jour à partir d’un format antérieur

Tous les paramètres dotés d'un format précédent de l’extension (et contenant les propriétés publiques ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken ou Properties) s’adaptent automatiquement au format actuel de l’extension. Ils s’exécuter exactement comme auparavant.

Le schéma suivant montre ce à quoi les paramètres précédents ressemblaient :

"settings": {
    "WMFVersion": "latest",
    "ModulesUrl": "https://UrlToZipContainingConfigurationScript.ps1.zip",
    "SasToken": "SAS Token if ModulesUrl points to private Azure Blob Storage",
    "ConfigurationFunction": "ConfigurationScript.ps1\\ConfigurationFunction",
    "Properties": {
        "ParameterToConfigurationFunction1": "Value1",
        "ParameterToConfigurationFunction2": "Value2",
        "ParameterOfTypePSCredential1": {
            "UserName": "UsernameValue1",
            "Password": "PrivateSettingsRef:Key1"
        },
        "ParameterOfTypePSCredential2": {
            "UserName": "UsernameValue2",
            "Password": "PrivateSettingsRef:Key2"
        }
    }
},
"protectedSettings": {
    "Items": {
        "Key1": "PasswordValue1",
        "Key2": "PasswordValue2"
    },
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

Voici comment le format précédent s’adapte au format actuel :

Nom de la propriété actuelle	Équivalent dans le schéma précédent
settings.wmfVersion	settings.wmfVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	Première partie de settings.ConfigurationFunction (avant \\)
settings.configuration.function	Deuxième partie de settings.ConfigurationFunction (après \\)
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri (sans jeton SAP)
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.advancedOptions.downloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	Jeton SAP de protectedSettings.DataBlobUri

Dépannage

Voici certaines des erreurs que vous risquez de rencontrer et la manière dont vous pouvez les résoudre.

Valeurs non valides

"Privacy.dataCollection is '{0}'. The only possible values are '', 'Enable' et 'Disable'. "WmfVersion is '{0}'. Les seules valeurs possibles sont les suivantes : and 'latest'".

Problème : une valeur fournie n’est pas autorisée.

Solution: Remplacez la valeur non valide par une valeur valide.

URL non valide

"ConfigurationData.url is '{0}'. This is not a valid URL » (configurationData.url est « {0} ». Il ne s’agit pas d’une URL valide.) « DataBlobUri is '{0}'. This is not a valid URL » (DataBlobUri est « {0} ». Il ne s’agit pas d’une URL valide.) « Configuration.url is '{0}'. This is not a valid URL » (configuration.url est « {0} ». Il ne s’agit pas d’une URL valide.)

Problème : une URL fournie n’est pas valide.

Solution: Vérifiez toutes les URL que vous avez fournies. Assurez-vous que toutes les URL se résolvent en emplacements valides auxquels l’extension peut accéder sur l’ordinateur distant.

Type configurationArguments non valide

"Invalid configurationArguments type {0}"

Problème : la propriété ConfigurationArguments ne peut pas se résoudre en objet de table de hachage.

Solution: faites de votre propriété ConfigurationArguments une table de hachage. Suivez le format fourni dans les exemples précédents. Prenez garde aux guillemets, aux virgules et aux accolades.

Propriétés configurationArguments en double

« Found duplicate arguments '{0}' in both public and protected configurationArguments » (Arguments en double trouvés dans les paramètres configuration Arguments publics et protégés)

Problème : Les arguments ConfigurationArguments dans les paramètres publics et les arguments ConfigurationArguments dans les paramètres protégés contiennent des propriétés portant le même nom.

Solution: Supprimez l’une des propriétés en double.

Propriétés manquantes

« settings.Configuration.function requires that settings.configuration.url or settings.configuration.module is specified » (settings.configuration.url ou settings.configuration.module doit être spécifié pour settings.Configuration.function)

« settings.Configuration.url requires that settings.configuration.script is specified » (settings.configuration.script doit être spécifié pour settings.Configuration.url)

« settings.Configuration.script requires that settings.configuration.url is specified » (settings.configuration.url doit être spécifié pour settings.Configuration.script)

« settings.Configuration.url requires that settings.configuration.function is specified » (settings.configuration.function doit être spécifié pour settings.Configuration.url)

« protectedSettings.ConfigurationUrlSasToken requires that settings.configuration.url is specified » (settings.configuration.url doit être spécifié pour protectedSettings.ConfigurationUrlSasToken)

« protectedSettings.ConfigurationDataUrlSasToken requires that settings.configurationData.url is specified » (settings.configurationData.url doit être spécifié pour protectedSettings.ConfigurationDataUrlSasToken)

Problème : Une propriété définie a besoin d’une autre propriété, laquelle est manquante.

Solutions :

Fournissez la propriété manquante.
Supprimez la propriété qui a besoin de la propriété manquante.

Étapes suivantes

En savoir plus sur l’utilisation des groupes identiques de machines virtuelles avec l’extension DSC Azure.
En savoir plus sur la Gestion des informations d’identification sécurisées de DSC.
Obtenir une introduction au gestionnaire d’extensions Azure DSC.
Pour plus informations sur DSC PowerShell, reportez-vous au centre de documentation PowerShell.

Partager via