Set di scalabilità di macchine virtuali (VMSS) Windows e Desired State Configuration (DSC) con modelli di Azure Resource ManagerWindows VMSS and Desired State Configuration with Azure Resource Manager templates

Questo articolo descrive il modello di Resource Manager per il gestore estensione Desired State Configuration (DSC).This article describes the Resource Manager template for the Desired State Configuration extension handler.

Esempio di modello per una VM WindowsTemplate example for a Windows VM

Il frammento seguente illustra la sezione del modello relativa alle risorse.The following snippet goes into the Resource section of the template.

            "name": "Microsoft.Powershell.DSC",
            "type": "extensions",
             "location": "[resourceGroup().location]",
             "apiVersion": "2015-06-15",
             "dependsOn": [
                  "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'))]"
              ],
              "properties": {
                  "publisher": "Microsoft.Powershell",
                  "type": "DSC",
                  "typeHandlerVersion": "2.20",
                  "autoUpgradeMinorVersion": true,
                  "forceUpdateTag": "[parameters('dscExtensionUpdateTagVersion')]",
                  "settings": {
                      "configuration": {
                          "url": "[concat(parameters('_artifactsLocation'), '/', variables('dscExtensionArchiveFolder'), '/', variables('dscExtensionArchiveFileName'))]",
                          "script": "dscExtension.ps1",
                          "function": "Main"
                      },
                      "configurationArguments": {
                          "nodeName": "[variables('vmName')]"
                      }
                  },
                  "protectedSettings": {
                      "configurationUrlSasToken": "[parameters('_artifactsLocationSasToken')]"
                  }
              }

Esempio di modello per set di scalabilità di macchine virtuali (VMSS) WindowsTemplate example for Windows VMSS

Il nodo VMSS ha una sezione "properties" con gli attributi "VirtualMachineProfile", "extensionProfile".A VMSS node has a "properties" section with the "VirtualMachineProfile", "extensionProfile" attribute. DSC viene aggiunto sotto "extensions".DSC is added under "extensions".

"extensionProfile": {
            "extensions": [
                {
                    "name": "Microsoft.Powershell.DSC",
                    "properties": {
                        "publisher": "Microsoft.Powershell",
                        "type": "DSC",
                        "typeHandlerVersion": "2.20",
                        "autoUpgradeMinorVersion": true,
                        "forceUpdateTag": "[parameters('DscExtensionUpdateTagVersion')]",
                        "settings": {
                            "configuration": {
                                "url": "[concat(parameters('_artifactsLocation'), '/', variables('DscExtensionArchiveFolder'), '/', variables('DscExtensionArchiveFileName'))]",
                                "script": "DscExtension.ps1",
                                "function": "Main"
                            },
                            "configurationArguments": {
                                "nodeName": "localhost"
                            }
                        },
                        "protectedSettings": {
                            "configurationUrlSasToken": "[parameters('_artifactsLocationSasToken')]"
                        }
                    }
                }
            ]
        }

Informazioni dettagliate sulle impostazioniDetailed Settings Information

Di seguito è illustrato lo schema per la sezione delle impostazioni dell'estensione DSC di Azure in un modello di Azure Resource Manager.The following schema is for the settings portion of the Azure DSC extension in an Azure Resource Manager template.


"settings": {
  "wmfVersion": "latest",
  "configuration": {
    "url": "http://validURLToConfigLocation",
    "script": "ConfigurationScript.ps1",
    "function": "ConfigurationFunction"
  },
  "configurationArguments": {
    "argument1": "Value1",
    "argument2": "Value2"
  },
  "configurationData": {
    "url": "https://foo.psd1"
  },
  "privacy": {
    "dataCollection": "enable"
  },
  "advancedOptions": {
    "downloadMappings": {
      "customWmfLocation": "http://myWMFlocation"
    }
  } 
},
"protectedSettings": {
  "configurationArguments": {
    "parameterOfTypePSCredential1": {
      "userName": "UsernameValue1",
      "password": "PasswordValue1"
    },
    "parameterOfTypePSCredential2": {
      "userName": "UsernameValue2",
      "password": "PasswordValue2"
    }
  },
  "configurationUrlSasToken": "?g!bber1sht0k3n",
  "configurationDataUrlSasToken": "?dataAcC355T0k3N"
}

DettagliDetails

Nome proprietàProperty Name TipoType DescrizioneDescription
settings.wmfVersionsettings.wmfVersion stringstring Specifica la versione di Windows Management Framework da installare nella macchina virtuale.Specifies the version of the Windows Management Framework that should be installed on your VM. Impostando questa proprietà su 'latest' verrà installata la versione più recente di WMF.Setting this property to 'latest' installs the most updated version of WMF. Gli unici valori attualmente possibili per questa proprietà sono '4.0', '5.0', '5.0PP' e 'latest'.The only current possible values for this property are '4.0', '5.0', '5.0PP', and 'latest'. Questi valori possibili sono soggetti ad aggiornamenti.These possible values are subject to updates. Il valore predefinito è 'latest'.The default value is 'latest'.
settings.configuration.urlsettings.configuration.url stringstring Specifica il percorso URL da cui scaricare il file ZIP della configurazione DSC.Specifies the URL location from which to download your DSC configuration zip file. Se l'URL specificato richiede un token di firma di accesso condiviso per l'accesso, è necessario impostare la proprietà protectedSettings.configurationUrlSasToken sul valore del token di firma di accesso condiviso.If the URL provided requires a SAS token for access, you need to set the protectedSettings.configurationUrlSasToken property to the value of your SAS token. Questa proprietà è obbligatoria se settings.configuration.script e/o settings.configuration.function sono definiti.This property is required if settings.configuration.script and/or settings.configuration.function are defined.
settings.configuration.scriptsettings.configuration.script stringstring Specifica il nome del file di script che contiene la definizione della configurazione DSC.Specifies the file name of the script that contains the definition of your DSC configuration. Questo script deve trovarsi nella cartella radice del file ZIP scaricato dall'URL specificato dalla proprietà configuration.url.This script must be in the root folder of the zip file downloaded from the URL specified by the configuration.url property. Questa proprietà è obbligatoria se settings.configuration.url e/o settings.configuration.script sono definiti.This property is required if settings.configuration.url and/or settings.configuration.script are defined.
settings.configuration.functionsettings.configuration.function stringstring Specifica il nome della configurazione DSC.Specifies the name of your DSC configuration. La configurazione indicata deve essere contenuta nello script definito da configuration.script.The configuration named must be contained in the script defined by configuration.script. Questa proprietà è obbligatoria se settings.configuration.url e/o settings.configuration.function sono definiti.This property is required if settings.configuration.url and/or settings.configuration.function are defined.
settings.configurationArgumentssettings.configurationArguments RaccoltaCollection Definisce i parametri da passare alla configurazione DSC.Defines any parameters you would like to pass to your DSC configuration. Questa proprietà non è crittografata.This property is not encrypted.
settings.configurationData.urlsettings.configurationData.url stringstring Specifica l'URL da cui scaricare il file di dati di configurazione con estensione psd1 da usare come input per la configurazione DSC.Specifies the URL from which to download your configuration data (.psd1) file to use as input for your DSC configuration. Se l'URL specificato richiede un token di firma di accesso condiviso per l'accesso, è necessario impostare la proprietà protectedSettings.configurationDataUrlSasToken sul valore del token di firma di accesso condiviso.If the URL provided requires a SAS token for access, you need to set the protectedSettings.configurationDataUrlSasToken property to the value of your SAS token.
settings.privacy.dataEnabledsettings.privacy.dataEnabled stringstring Abilita o disabilita la raccolta di dati di telemetria.Enables or disables telemetry collection. Gli unici valori attualmente possibili per questa proprietà sono 'Enable', 'Disable', '', o $null.The only possible values for this property are 'Enable', 'Disable', '', or $null. Lasciando questa proprietà vuota o con valore null verrà abilitata la raccolta di dati di telemetria.Leaving this property blank or null enables telemetry. Il valore predefinito è ''.The default value is ''. Altre informazioniMore Information
settings.advancedOptions.downloadMappingssettings.advancedOptions.downloadMappings RaccoltaCollection Definisce i percorsi alternativi da cui scaricare WMF.Defines alternate locations from which to download the WMF. Altre informazioniMore Information
protectedSettings.configurationArgumentsprotectedSettings.configurationArguments RaccoltaCollection Definisce i parametri da passare alla configurazione DSC.Defines any parameters you would like to pass to your DSC configuration. Questa proprietà è crittografata.This property is encrypted.
protectedSettings.configurationUrlSasTokenprotectedSettings.configurationUrlSasToken stringstring Specifica il token di firma di accesso condiviso per accedere all'URL definito da configuration.url.Specifies the SAS token to access the URL defined by configuration.url. Questa proprietà è crittografata.This property is encrypted.
protectedSettings.configurationDataUrlSasTokenprotectedSettings.configurationDataUrlSasToken stringstring Specifica il token di firma di accesso condiviso per accedere all'URL definito da configurationData.url.Specifies the SAS token to access the URL defined by configurationData.url. Questa proprietà è crittografata.This property is encrypted.

Differenze tra settings e protectedSettingsSettings vs. ProtectedSettings

Tutte le impostazioni vengono salvate in un file di testo delle impostazioni nella macchina virtuale.All settings are saved in a settings text file on the VM. Le proprietà indicate in 'settings' sono proprietà pubbliche perché non sono crittografate nel file di testo delle impostazioni.Properties under 'settings' are public properties because they are not encrypted in the settings text file. Le proprietà indicate in 'protectedSettings' vengono crittografate con un certificato e non vengono visualizzate in testo normale in questo file nella macchina virtuale.Properties under 'protectedSettings' are encrypted with a certificate and are not shown in plain text in this file on the VM.

Se la configurazione richiede credenziali, queste possono essere indicate in protectedSettings:If the configuration needs credentials, they can be included in protectedSettings:

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

EsempioExample

L'esempio seguente deriva dalla sezione "Introduzione" di Introduzione al gestore dell'estensione DSC (Desired State Configuration) di Azure.The following example derives from the "Getting Started" section of the DSC Extension Handler Overview page. Questo esempio usa modelli di Resource Manager anziché i cmdlet per distribuire l'estensione.This example uses Resource Manager templates instead of cmdlets to deploy the extension. Salvare la configurazione di "IisInstall.ps1", inserirla in un file ZIP e caricare il file in un URL accessibile.Save the "IisInstall.ps1" configuration, place it in a .ZIP file, and upload the file in an accessible URL. Questo esempio usa l'archiviazione BLOB di Azure, ma è possibile scaricare file ZIP da qualsiasi percorso.This example uses Azure blob storage, but it is possible to download .ZIP files from any arbitrary location.

Nel modello di Azure Resource Manager il codice seguente indica alla VM di scaricare il file corretto ed eseguire la funzione PowerShell appropriata:In the Azure Resource Manager template, the following code instructs the VM to download the correct file and run the appropriate PowerShell function:

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

Aggiornamento dal formato precedenteUpdating from the Previous Format

Tutte le impostazioni presenti nel formato precedente, contenente le proprietà pubbliche ModulesUrl, ConfigurationFunction, SasToken o Properties, verranno automaticamente adattate al formato corrente ed eseguite come in precedenza.Any settings in the previous format (containing the public properties ModulesUrl, ConfigurationFunction, SasToken, or Properties) automatically adapt to the current format and run just as they did before.

Lo schema seguente è simile allo schema delle impostazioni precedente:The following schema is what the previous settings schema looked like:

"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"
}

Il formato precedente si adatta al formato corrente come segue:Here's how the previous format adapts to the current format:

Nome proprietàProperty Name Equivalente nello schema precedentePrevious Schema Equivalent
settings.wmfVersionsettings.wmfVersion settings.wmfVersionsettings.WMFVersion
settings.configuration.urlsettings.configuration.url settings.ModulesUrlsettings.ModulesUrl
settings.configuration.scriptsettings.configuration.script Prima parte di settings.ConfigurationFunction (prima di "\\")First part of settings.ConfigurationFunction (before '\\')
settings.configuration.functionsettings.configuration.function Seconda parte di settings.ConfigurationFunction (dopo "\\")Second part of settings.ConfigurationFunction (after '\\')
settings.configurationArgumentssettings.configurationArguments settings.Propertiessettings.Properties
settings.configurationData.urlsettings.configurationData.url protectedSettings.DataBlobUri (senza token di firma di accesso condiviso)protectedSettings.DataBlobUri (without SAS token)
settings.privacy.dataEnabledsettings.privacy.dataEnabled settings.privacy.dataEnabledsettings.Privacy.DataEnabled
settings.advancedOptions.downloadMappingssettings.advancedOptions.downloadMappings settings.advancedOptions.downloadMappingssettings.AdvancedOptions.DownloadMappings
protectedSettings.configurationArgumentsprotectedSettings.configurationArguments protectedSettings.PropertiesprotectedSettings.Properties
protectedSettings.configurationUrlSasTokenprotectedSettings.configurationUrlSasToken settings.SasTokensettings.SasToken
protectedSettings.configurationDataUrlSasTokenprotectedSettings.configurationDataUrlSasToken Token di firma di accesso condiviso di protectedSettings.DataBlobUriSAS token from protectedSettings.DataBlobUri

Risoluzione dei problemi - Codice errore 1100Troubleshooting - Error Code 1100

Il codice errore 1100 indica che si è verificato un problema con l'input dell'utente per l'estensione DSC.Error Code 1100 indicates that there is a problem with the user input to the DSC extension. Il testo di questi errori può variare.The text of these errors is variable and may change. Di seguito sono riportati alcuni degli errori che possono verificarsi e la possibile soluzione.Here are some of the errors you may run into and how you can fix them.

Valori non validiInvalid Values

"Privacy.dataCollection è '{0}'."Privacy.dataCollection is '{0}'. Gli unici valori possibili sono '', 'Enable' e 'Disable'" "WmfVersion è '{0}'.The only possible values are '', 'Enable', and 'Disable'" "WmfVersion is '{0}'. Gli unici valori possibili sono: ...Only possible values are … e "più recenti"and 'latest'"

Problema: un valore specificato non è consentito.Problem: A provided value is not allowed.

Soluzione: sostituire il valore non valido con un valore valido.Solution: Change the invalid value to a valid value. Vedere la tabella nella sezione dei dettagli.See the table in the Details section.

URL non validoInvalid URL

"ConfigurationData.url è '{0}'."ConfigurationData.url is '{0}'. URL non valido" "DataBlobUri è '{0}'.This is not a valid URL" "DataBlobUri is '{0}'. URL non valido" "Configuration.url è '{0}'.This is not a valid URL" "Configuration.url is '{0}'. URL non valido"This is not a valid URL"

Problema: un URL specificato non è valido.Problem: A provided URL is not valid.

Soluzione: verificare tutti gli URL specificati.Solution: Check all your provided URLs. Verificare che tutti gli URL si risolvano in percorsi validi cui l'estensione può accedere nel computer remoto.Make sure all URLs resolve to valid locations that the extension can access on the remote machine.

Tipo ConfigurationArgument non validoInvalid ConfigurationArgument Type

"Tipo configurationArguments {0} non valido""Invalid configurationArguments type {0}"

Problema: la proprietà ConfigurationArguments non si risolve in un oggetto Hashtable.Problem: The ConfigurationArguments property cannot resolve to a Hashtable object.

Soluzione: rendere la proprietà ConfigurationArguments un oggetto Hashtable.Solution: Make your ConfigurationArguments property a Hashtable. Seguire il formato indicato nell'esempio precedente.Follow the format provided in the preceeding example. Prestare attenzione alle virgolette, alle virgole e alle parentesi graffe.Watch out for quotes, commas, and braces.

ConfigurationArguments duplicatoDuplicate ConfigurationArguments

"Trovati argomenti duplicati '{0}' in configurationArguments pubblici e protetti""Found duplicate arguments '{0}' in both public and protected configurationArguments"

Problema: ConfigurationArguments nelle impostazioni pubbliche e ConfigurationArguments nelle impostazioni protette contengono proprietà con lo stesso nome.Problem: The ConfigurationArguments in public settings and the ConfigurationArguments in protected settings contain properties with the same name.

Soluzione: rimuovere una delle proprietà duplicate.Solution: Remove one of the duplicate properties.

Proprietà mancantiMissing Properties

"Configuration.function richiede che venga specificato configuration.url o configuration.module""Configuration.function requires that configuration.url or configuration.module is specified"

"Configuration.url richiede che venga specificato configuration.script""Configuration.url requires that configuration.script is specified"

"Configuration.script richiede che venga specificato configuration.url""Configuration.script requires that configuration.url is specified"

"Configuration.url richiede che venga specificato configuration.function""Configuration.url requires that configuration.function is specified"

"ConfigurationUrlSasToken richiede che venga specificato configuration.url""ConfigurationUrlSasToken requires that configuration.url is specified"

"ConfigurationDataUrlSasToken richiede che venga specificato configurationData.url""ConfigurationDataUrlSasToken requires that configurationData.url is specified"

Problema: una proprietà definita richiede un'altra proprietà mancante.Problem: A defined property needs another property that is missing.

Soluzioni:Solutions:

  • Specificare la proprietà mancante.Provide the missing property.
  • Rimuovere la proprietà che richiede la proprietà mancante.Remove the property that needs the missing property.

Passaggi successiviNext Steps

Per informazioni su DSC e sui set di scalabilità delle macchine virtuali, vedere Using Virtual Machine Scale Sets with the Azure DSC ExtensionLearn about DSC and virtual machine scale sets in Using Virtual Machine Scale Sets with the Azure DSC Extension

Per altre informazioni dettagliate, leggere l'articolo sulla gestione delle credenziali protette di DSC.Find more details on DSC's secure credential management.

Per altre informazioni sul gestore dell'estensione DSC, vedere Introduzione al gestore dell'estensione DSC (Desired State Configuration) di Azure.For more information on the Azure DSC extension handler, see Introduction to the Azure Desired State Configuration extension handler.

Per altre informazioni su PowerShell DSC, vedere il centro di documentazione di PowerShell.For more information about PowerShell DSC, visit the PowerShell documentation center.