Estensione Desired State Configuration (DSC) con modelli di Azure Resource Manager

Nota

Prima di abilitare l'estensione DSC, si vuole sapere che una versione più recente di DSC è ora disponibile a livello generale, gestita da una funzionalità di Configurazione automatica di Azure denominata machine. La funzionalità di configurazione del computer combina le funzionalità del gestore dell'estensione DSC (Desired State Configuration), Automazione di Azure State Configuration e le funzionalità più comunemente richieste dal feedback dei clienti. La configurazione del computer include anche il supporto del computer ibrido tramite i server abilitati per Arc.

Questo articolo descrive il modello di Azure Resource Manager per il gestore dell'estensione Desired State Configuration (DSC). Molti degli esempi usano RegistrationURL (fornito come stringa) e RegistrationKey (forniti come PSCredential) per eseguire l'onboarding con Automazione di Azure. Per informazioni dettagliate su come ottenere questi valori, vedere Usare la metaconfigurazione DSC per registrare i computer ibridi.

Nota

Prima di abilitare l'estensione DSC, si vuole sapere che una versione più recente di DSC è ora disponibile a livello generale, gestita da una funzionalità di Configurazione automatica di Azure denominata machine. La funzionalità di configurazione del computer combina le funzionalità del gestore dell'estensione DSC (Desired State Configuration), Automazione di Azure State Configuration e le funzionalità più comunemente richieste dal feedback dei clienti. La configurazione del computer include anche il supporto del computer ibrido tramite i server abilitati per Arc.

Nota

Si potrebbero notare esempi di schema leggermente diversi. La modifica dello schema è avvenuta nella versione di ottobre 2016. Per maggiori dettagli, vedere Aggiornamento da un formato precedente.

Esempio di modello per una VM Windows

Il frammento seguente illustra la sezione del modello relativa alle risorse. L'estensione DSC eredita le proprietà di estensione predefinite. Per altre informazioni, vedere VirtualMachineExtension class (Classe VirtualMachineExtension).

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/Microsoft.Powershell.DSC')]",
  "apiVersion": "2018-06-01",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', parameters('VMName'))]"
  ],
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "protectedSettings": {
      "Items": {
        "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
      }
    },
    "settings": {
      "Properties": [
        {
          "Name": "RegistrationKey",
          "Value": {
            "UserName": "PLACEHOLDER_DONOTUSE",
            "Password": "PrivateSettingsRef:registrationKeyPrivate"
          },
          "TypeName": "System.Management.Automation.PSCredential"
        },
        {
          "Name": "RegistrationUrl",
          "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
          "TypeName": "System.String"
        },
        {
          "Name": "NodeConfigurationName",
          "Value": "[parameters('nodeConfigurationName')]",
          "TypeName": "System.String"
        }
      ]
    }
  }
}

Esempio di modello per set di scalabilità di macchine virtuali Windows

Il nodo di un set di scalabilità di macchine virtuali ha una sezione properties con un attributo VirtualMachineProfile, extensionProfile. In extensions aggiungere i dettagli per l'estensione DSC.

L'estensione DSC eredita le proprietà di estensione predefinite. Per altre informazioni, vedere VirtualMachineScaleSetExtension class (Classe VirtualMachineScaleSetExtension).

"extensionProfile": {
    "extensions": [
      {
        "name": "Microsoft.Powershell.DSC",
        "properties": {
          "publisher": "Microsoft.Powershell",
          "type": "DSC",
          "typeHandlerVersion": "2.77",
          "autoUpgradeMinorVersion": true,
          "protectedSettings": {
            "Items": {
              "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
            }
          },
          "settings": {
            "Properties": [
              {
                "Name": "RegistrationKey",
                "Value": {
                  "UserName": "PLACEHOLDER_DONOTUSE",
                  "Password": "PrivateSettingsRef:registrationKeyPrivate"
                },
                "TypeName": "System.Management.Automation.PSCredential"
              },
              {
                "Name": "RegistrationUrl",
                "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
                "TypeName": "System.String"
              },
              {
                "Name": "NodeConfigurationName",
                "Value": "[parameters('nodeConfigurationName')]",
                "TypeName": "System.String"
              }
            ]
          }
        }
      }
    ]
  }

Informazioni dettagliate sulle impostazioni

Usare lo schema seguente nella sezione delle impostazioni dell'estensione DSC di Azure in un modello di Resource Manager.

Per un elenco degli argomenti disponibili per lo script di configurazione predefinito, vedere Script di configurazione predefinito.

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

Dettagli

Nome proprietà	Type	Descrizione
settings.wmfVersion	string	Specifica la versione di Windows Management Framework (WMF) da installare nella macchina virtuale. Impostando questa proprietà su latest verrà installata la versione più recente di WMF. Attualmente, gli unici valori possibili per questa proprietà sono 4.0, 5.0, 5.1 e latest. Questi valori possibili sono soggetti ad aggiornamenti. Il valore predefinito è latest.
settings.configuration.url	string	Specifica il percorso URL da cui scaricare il file ZIP della configurazione DSC. Se l'URL specificato richiede un token di firma di accesso condiviso per l'accesso, impostare la proprietà protectedSettings.configurationUrlSasToken sul valore del token di firma di accesso condiviso. Questa proprietà è obbligatoria se settings.configuration.script o settings.configuration.function sono definiti. Se non viene specificato alcun valore per queste proprietà, l'estensione chiama lo script di configurazione predefinito per impostare i metadati di Gestione configurazione locale e devono essere forniti gli argomenti.
settings.configuration.script	string	Specifica il nome del file di script che contiene la definizione della configurazione DSC. Questo script deve trovarsi nella cartella radice del file con estensione zip che viene scaricato dall'URL specificato dalla proprietà settings.configuration.url. Questa proprietà è obbligatoria se settings.configuration.url o settings.configuration.script sono definiti. Se non viene specificato alcun valore per queste proprietà, l'estensione chiama lo script di configurazione predefinito per impostare i metadati di Gestione configurazione locale e devono essere forniti gli argomenti.
settings.configuration.function	string	Specifica il nome della configurazione DSC. La configurazione indicata deve essere inclusa nello script definito da settings.configuration.script. Questa proprietà è obbligatoria se settings.configuration.url o settings.configuration.function sono definiti. Se non viene specificato alcun valore per queste proprietà, l'estensione chiama lo script di configurazione predefinito per impostare i metadati di Gestione configurazione locale e devono essere forniti gli argomenti.
settings.configurationArguments	Raccolta	Definisce i parametri da passare alla configurazione DSC. Questa proprietà non è crittografata.
settings.configurationData.url	string	Specifica l'URL da cui scaricare il file di dati di configurazione con estensione psd1 da usare come input per la configurazione DSC. Se l'URL specificato richiede un token di firma di accesso condiviso per l'accesso, impostare la proprietà protectedSettings.configurationDataUrlSasToken sul valore del token di firma di accesso condiviso.
settings.privacy.dataCollection	string	Abilita o disabilita la raccolta di dati di telemetria. Gli unici valori possibili per questa proprietà sono Enable, Disable, '' o $null. Lasciando questa proprietà vuota o con valore null verrà abilitata la raccolta di dati di telemetria. Il valore predefinito è ''. Per altre informazioni, vedere Azure DSC extension data collection (Raccolta di dati dell'estensione DSC di Azure).
settings.advancedOptions.downloadMappings	Raccolta	Definisce i percorsi alternativi da cui scaricare WMF. Per altre informazioni, vedere Azure DSC extension 2.8 and how to map downloads of the extension dependencies to your own location (Estensione DSC di Azure 2.8 e come eseguire il mapping dei download delle dipendenze dell'estensione al percorso).
protectedSettings.configurationArguments	Raccolta	Definisce i parametri da passare alla configurazione DSC. Questa proprietà è crittografata.
protectedSettings.configurationUrlSasToken	string	Specifica il token di firma di accesso condiviso da usare per accedere all'URL definito da settings.configuration.url. Questa proprietà è crittografata.
protectedSettings.configurationDataUrlSasToken	string	Specifica il token di firma di accesso condiviso da usare per accedere all'URL definito da settings.configurationData.url. Questa proprietà è crittografata.

Script di configurazione predefinito

Per altre informazioni sui valori seguenti, vedere Configurazione di Gestione configurazione locale - Impostazioni di base. È possibile usare lo script di configurazione predefinito dell'estensione DSC per configurare solo le proprietà di Gestione configurazione locale elencate nella tabella seguente.

Nome proprietà	Type	Descrizione
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Proprietà obbligatoria. Specifica la chiave che viene usata per la registrazione di un nodo nel servizio Automazione di Azure come password di un oggetto credenziale di PowerShell. Questo valore può essere individuato automaticamente usando il metodo listkeys per l'account di Automazione. Vedere l'esempio.
settings.configurationArguments.RegistrationUrl	string	Proprietà obbligatoria. Specifica l'URL dell'endpoint di Automazione in cui il nodo tenta di registrarsi. Questo valore può essere individuato automaticamente usando il metodo reference per l'account di Automazione.
settings.configurationArguments.NodeConfigurationName	string	Proprietà obbligatoria. Specifica la configurazione del nodo nell'account di Automazione da assegnare al nodo.
settings.configurationArguments.ConfigurationMode	string	Specifica la modalità di Gestione configurazione locale. Le opzioni valide sono ApplyOnly, ApplyandMonitor e ApplyandAutoCorrect. Il valore predefinito è ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Specifica la frequenza con cui Gestione configurazione locale tenta di verificare la disponibilità di aggiornamenti con l'account di Automazione. Il valore predefinito è 30. Il valore minimo è 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Specifica la frequenza con cui Gestione configurazione locale convalida la configurazione corrente. Il valore predefinito è 15. Il valore minimo è 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Specifica se un nodo può essere riavviato automaticamente se richiesto da un'operazione DSC. Il valore predefinito è false.
settings.configurationArguments.ActionAfterReboot	string	Specifica che cosa avviene dopo un riavvio durante l'applicazione di una configurazione. Le opzioni valide sono ContinueConfiguration e StopConfiguration. Il valore predefinito è ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Specifica se Gestione configurazione locale sovrascrive i moduli esistenti nel nodo. Il valore predefinito è false.

Differenze tra settings e protectedSettings

Tutte le impostazioni vengono salvate in un file di testo delle impostazioni nella macchina virtuale. Le proprietà indicate in settings sono proprietà pubbliche. Le proprietà pubbliche non sono crittografate nel file di testo delle impostazioni. Le proprietà indicate in protectedSettings vengono crittografate con un certificato e non vengono visualizzate in testo normale nel file delle impostazioni nella macchina virtuale.

Se la configurazione richiede credenziali, è possibile includerle in protectedSettings:

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

Script di configurazione di esempio

L'esempio seguente illustra il comportamento predefinito per l'estensione DSC, ovvero fornire le impostazioni dei metadati a Gestione configurazione locale ed effettuare la registrazione per il servizio Automation DSC. Gli argomenti di configurazione sono necessari e vengono passati allo script di configurazione predefinito per impostare i metadati di Gestione configurazione locale.

"settings": {
    "configurationArguments": {
        "RegistrationUrl" : "[parameters('registrationUrl1')]",
        "NodeConfigurationName" : "nodeConfigurationNameValue1"
    }
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "registrationKey"
        }
    }
}

Esempio di uso dello script di configurazione in Archiviazione di Azure

L'esempio seguente è tratto da Introduzione al gestore dell'estensione DSC (Desired State Configuration) di Azure. Questo esempio usa modelli di Resource Manager anziché i cmdlet per distribuire l'estensione. Salvare la configurazione di IisInstall.ps1, inserirla in un file ZIP (esempio: iisinstall.zip) e quindi caricare il file in un URL accessibile. Questo esempio usa l'archiviazione BLOB di Azure, ma è possibile scaricare file ZIP da qualsiasi percorso.

Nel modello di Resource Manager il codice seguente indica alla VM di scaricare il file corretto e quindi eseguire la funzione PowerShell appropriata:

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

Esempio d'uso dei valori di registrazione di Automazione di Azure di riferimento

L'esempio seguente ottiene i valori RegistrationUrl e RegistrationKey facendo riferimento alle proprietà dell'account di Automazione di Azure e usando il metodo listkeys per recuperare la chiave primaria (0). In questo esempio, i parametri automationAccountName e NodeConfigName sono stati forniti al modello.

"settings": {
    "RegistrationUrl" : "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
    "NodeConfigurationName" : "[parameters('NodeConfigName')]"
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-01-15').Keys[0].value]"
        }
    }
}

Aggiornamento da un formato precedente

Eventuali impostazioni presenti in un formato precedente dell'estensione (e che hanno le proprietà pubbliche ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken o Properties) vengono automaticamente adattate al formato corrente dell'estensione ed eseguite come in precedenza.

Lo schema seguente mostra l'aspetto dello schema delle impostazioni precedente:

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

Nome proprietà corrente	Equivalente nello schema precedente
settings.wmfVersion	settings.wmfVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	Prima parte delle impostazioni. ConfigurationFunction (prima di \\)
settings.configuration.function	Seconda parte delle impostazioni. ConfigurationFunction (dopo \\)
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri (senza token di firma di accesso condiviso)
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.advancedOptions.downloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	Token di firma di accesso condiviso di protectedSettings.DataBlobUri

Risoluzione dei problemi

Di seguito sono riportati alcuni degli errori che possono verificarsi e la relativa soluzione.

Valori non validi

"Privacy.dataCollection è '{0}'. Gli unici valori possibili sono '', 'Enable' e 'Disable'". "WmfVersion è '{0}'. Gli unici valori possibili sono: ... e "latest".

Problema: un valore specificato non è consentito.

Soluzione: sostituire il valore non valido con un valore valido. Per altre informazioni, vedere la tabella in Dettagli.

URL non valido

"ConfigurationData.url è '{0}'. URL non valido" "DataBlobUri è '{0}'. URL non valido" "Configuration.url è '{0}'. URL non valido"

Problema: un URL specificato non è valido.

Soluzione: verificare tutti gli URL specificati. Assicurarsi che tutti gli URL si risolvano in percorsi validi a cui l'estensione può accedere nel computer remoto.

Tipo RegistrationKey non valido

"Tipo non valido per il parametro RegistrationKey di tipo PSCredential"

Problema: il valore RegistrationKey in protectedSettings.configurationArguments non può essere fornito per un tipo diverso da PSCredential.

Soluzione: modificare la voce protectedSettings.configurationArguments per RegistrationKey a un tipo PSCredential usando il formato seguente:

"configurationArguments": {
    "RegistrationKey": {
        "userName": "NOT_USED",
        "Password": "RegistrationKey"
    }
}

Tipo ConfigurationArgument non valido

"Tipo configurationArguments {0} non valido"

Problema: la proprietà ConfigurationArguments non si risolve in un oggetto Hash table.

Soluzione: trasformare la proprietà ConfigurationArguments in un oggetto Hash table. Seguire il formato indicato negli esempi precedenti. Prestare attenzione alle virgolette, alle virgole e alle parentesi graffe.

ConfigurationArguments duplicato

"Trovati argomenti duplicati '{0}' in configurationArguments pubblici e protetti"

Problema: ConfigurationArguments nelle impostazioni pubbliche e ConfigurationArguments nelle impostazioni protette hanno proprietà con lo stesso nome.

Soluzione: rimuovere una delle proprietà duplicate.

Proprietà mancanti

"settings.Configuration.function richiede che venga specificato settings.configuration.url o settings.configuration.module"

"settings.Configuration.url richiede che venga specificato settings.configuration.script"

"settings.Configuration.script richiede che venga specificato settings.configuration.url"

"settings.Configuration.url richiede che venga specificato settings.configuration.function"

"protectedSettings.ConfigurationUrlSasToken richiede che venga specificato settings.configuration.url"

"protectedSettings.ConfigurationDataUrlSasToken richiede che venga specificato settings.configurationData.url"

Problema: una proprietà definita richiede un'altra proprietà mancante.

Soluzioni:

• Specificare la proprietà mancante.
• Rimuovere la proprietà che richiede la proprietà mancante.

Passaggi successivi

• Informazioni sull'uso dei set di scalabilità di macchine virtuali con l'estensione DSC di Azure.
• Maggiori dettagli sulla gestione delle credenziali protette di DSC.
• Introduzione al gestore dell'estensione DSC (Desired State Configuration) di Azure.
• Per altre informazioni su PowerShell DSC, passare al centro di documentazione di PowerShell.