Desired State Configuration-extensie met Azure Resource Manager-sjablonen

Notitie

Voordat u de DSC-extensie inschakelt, willen we graag weten dat een nieuwere versie van DSC nu algemeen beschikbaar is, beheerd door een functie van azure Automange benoemde machineconfiguratie. De functie voor machineconfiguratie combineert functies van de DSC-extensiehandler (Desired State Configuration), Azure Automation State Configuration en de meest aangevraagde functies van feedback van klanten. Machineconfiguratie omvat ook ondersteuning voor hybride machines via servers met Arc.

In dit artikel wordt de Azure Resource Manager-sjabloon voor de DSC-extensiehandler (Desired State Configuration) beschreven. Veel van de voorbeelden maken gebruik van RegistrationURL (geleverd als een tekenreeks) en RegistrationKey (geleverd als PSCredential voor onboarding met Azure Automation). Zie DSC-metaconfiguratie gebruiken om hybride machines te registreren voor meer informatie over het verkrijgen van deze waarden.

Notitie

Voordat u de DSC-extensie inschakelt, willen we graag weten dat een nieuwere versie van DSC nu algemeen beschikbaar is, beheerd door een functie van azure Automange benoemde machineconfiguratie. De functie voor machineconfiguratie combineert functies van de DSC-extensiehandler (Desired State Configuration), Azure Automation State Configuration en de meest aangevraagde functies van feedback van klanten. Machineconfiguratie omvat ook ondersteuning voor hybride machines via servers met Arc.

Notitie

Er kunnen iets andere schemavoorbeelden optreden. De wijziging in het schema is opgetreden in de release van oktober 2016. Zie Bijwerken uit een eerdere indeling voor meer informatie.

Sjabloonvoorbeeld voor een Virtuele Windows-machine

Het volgende codefragment wordt weergegeven in de sectie Resource van de sjabloon. De DSC-extensie neemt standaarduitbreidingseigenschappen over. Zie de klasse VirtualMachineExtension voor meer informatie.

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

Sjabloonvoorbeeld voor virtuele-machineschaalsets van Windows

Een virtuele-machineschaalsetknooppunt heeft een eigenschappensectie met een VirtualMachineProfile, extensionProfile-kenmerk . Voeg onder Extensies de details voor DE DSC-extensie toe.

De DSC-extensie neemt standaarduitbreidingseigenschappen over. Zie de klasse VirtualMachineScaleSetExtension voor meer informatie.

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

Gedetailleerde informatie over instellingen

Gebruik het volgende schema in de sectie Instellingen van de Azure DSC-extensie in een Resource Manager-sjabloon.

Zie Het standaardconfiguratiescript voor een lijst met de argumenten die beschikbaar zijn voor het standaardconfiguratiescript.

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

DETAILS

Eigenschapsnaam	Type	Description
settings.wmfVersion	tekenreeks	Hiermee geeft u de versie van Windows Management Framework (WMF) op die moet worden geïnstalleerd op uw VIRTUELE machine. Als u deze eigenschap instelt op de meest recente versie van WMF, wordt de meest recente versie van WMF geïnstalleerd. Momenteel zijn de enige mogelijke waarden voor deze eigenschap 4.0, 5.0, 5.1 en nieuwste. Deze mogelijke waarden zijn onderhevig aan updates. De standaardwaarde is de meest recente.
settings.configuration.url	tekenreeks	Hiermee geeft u de URL-locatie van waaruit u uw DSC-configuratie .zip bestand moet downloaden. Als voor de opgegeven URL een SAS-token is vereist voor toegang, stelt u de eigenschap protectedSettings.configurationUrlSasToken in op de waarde van uw SAS-token. Deze eigenschap is vereist als settings.configuration.script of settings.configuration.function zijn gedefinieerd. Als er geen waarde wordt opgegeven voor deze eigenschappen, roept de extensie het standaardconfiguratiescript aan om metagegevens van Location Configuration Manager (LCM) in te stellen en moeten argumenten worden opgegeven.
settings.configuration.script	tekenreeks	Hiermee geeft u de bestandsnaam op van het script dat de definitie van uw DSC-configuratie bevat. Dit script moet zich in de hoofdmap van het .zip-bestand bevinden dat is gedownload van de URL die is opgegeven door de eigenschap settings.configuration.url . Deze eigenschap is vereist als settings.configuration.url of settings.configuration.script is gedefinieerd. Als er geen waarde wordt opgegeven voor deze eigenschappen, roept de extensie het standaardconfiguratiescript aan om LCM-metagegevens in te stellen en moeten argumenten worden opgegeven.
settings.configuration.function	tekenreeks	Hiermee geeft u de naam van uw DSC-configuratie. De configuratie met de naam moet worden opgenomen in het script dat settings.configuration.script definieert. Deze eigenschap is vereist als settings.configuration.url of settings.configuration.function zijn gedefinieerd. Als er geen waarde wordt opgegeven voor deze eigenschappen, roept de extensie het standaardconfiguratiescript aan om LCM-metagegevens in te stellen en moeten argumenten worden opgegeven.
settings.configurationArguments	Verzameling	Definieert parameters die u wilt doorgeven aan uw DSC-configuratie. Deze eigenschap is niet versleuteld.
settings.configurationData.url	tekenreeks	Hiermee geeft u de URL op van waaruit u uw configuratiegegevensbestand (.psd1) moet downloaden om te gebruiken als invoer voor uw DSC-configuratie. Als voor de opgegeven URL een SAS-token is vereist voor toegang, stelt u de eigenschap protectedSettings.configurationDataUrlSasToken in op de waarde van uw SAS-token.
settings.privacy.dataCollection	tekenreeks	Hiermee schakelt u telemetrieverzameling in of uit. De enige mogelijke waarden voor deze eigenschap zijn Inschakelen, Uitschakelen, '' of $null. Als u deze eigenschap leeg of null laat, wordt telemetrie ingeschakeld. De standaardwaarde is ''. Zie het verzamelen van azure DSC-extensiegegevens voor meer informatie.
settings.advancedOptions.downloadMappings	Verzameling	Definieert alternatieve locaties van waaruit WMF moet worden gedownload. Zie Azure DSC-extensie 2.8 voor meer informatie en hoe u downloads van de extensieafhankelijkheden toe te wijzen aan uw eigen locatie.
protectedSettings.configurationArguments	Verzameling	Definieert parameters die u wilt doorgeven aan uw DSC-configuratie. Deze eigenschap is versleuteld.
protectedSettings.configurationUrlSasToken	tekenreeks	Hiermee geeft u het SAS-token op dat moet worden gebruikt voor toegang tot de URL die settings.configuration.url definieert. Deze eigenschap is versleuteld.
protectedSettings.configurationDataUrlSasToken	tekenreeks	Hiermee geeft u het SAS-token op dat moet worden gebruikt voor toegang tot de URL die door settings.configurationData.url wordt gedefinieerd. Deze eigenschap is versleuteld.

Standaardconfiguratiescript

Zie De basisinstellingen van Local Configuration Manager voor meer informatie over de volgende waarden. U kunt het standaardconfiguratiescript voor de DSC-extensie gebruiken om alleen de LCM-eigenschappen te configureren die worden vermeld in de volgende tabel.

Eigenschapsnaam	Type	Description
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Vereiste eigenschap. Hiermee geeft u de sleutel op die wordt gebruikt voor een knooppunt om zich bij de Azure Automation-service te registreren als het wachtwoord van een PowerShell-referentieobject. Deze waarde kan automatisch worden gedetecteerd met behulp van de methode listkeys voor het Automation-account. Zie het voorbeeld.
settings.configurationArguments.RegistrationUrl	tekenreeks	Vereiste eigenschap. Hiermee geeft u de URL van het Automation-eindpunt op waar het knooppunt probeert te registreren. Deze waarde kan automatisch worden gedetecteerd met behulp van de referentiemethode voor het Automation-account.
settings.configurationArguments.NodeConfigurationName	tekenreeks	Vereiste eigenschap. Hiermee geeft u de knooppuntconfiguratie in het Automation-account op die moet worden toegewezen aan het knooppunt.
settings.configurationArguments.ConfigurationMode	tekenreeks	Hiermee geeft u de modus voor LCM. Geldige opties zijn ApplyOnly, ApplyandMonitor en ApplyandAutoCorrect. De standaardwaarde is ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Hiermee geeft u op hoe vaak LCM probeert te controleren met het Automation-account voor updates. De standaardwaarde is 30. De minimumwaarde is 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Hiermee geeft u op hoe vaak LCM de huidige configuratie valideert. De standaardwaarde is 15. De minimumwaarde is 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Hiermee geeft u op of een knooppunt automatisch opnieuw kan worden opgestart als een DSC-bewerking dit aanvraagt. De standaardwaarde is Onwaar.
settings.configurationArguments.ActionAfterReboot	tekenreeks	Hiermee geeft u op wat er gebeurt na het opnieuw opstarten bij het toepassen van een configuratie. Geldige opties zijn ContinueConfiguration en StopConfiguration. De standaardwaarde is ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Hiermee geeft u op of LCM bestaande modules op het knooppunt overschrijft. De standaardwaarde is Onwaar.

instellingen versus protectedSettings

Alle instellingen worden opgeslagen in een tekstbestand met instellingen op de virtuele machine. Eigenschappen die worden vermeld onder instellingen zijn openbare eigenschappen. Openbare eigenschappen worden niet versleuteld in het tekstbestand met instellingen. Eigenschappen die worden vermeld onder protectedSettings worden versleuteld met een certificaat en worden niet weergegeven in tekst zonder opmaak in het instellingenbestand op de VIRTUELE machine.

Als de configuratie referenties nodig heeft, kunt u de referenties opnemen in protectedSettings:

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

Voorbeeld van configuratiescript

In het volgende voorbeeld ziet u het standaardgedrag voor de DSC-extensie. Dit is het verstrekken van metagegevensinstellingen aan LCM en het registreren bij de Automation DSC-service. Configuratieargumenten zijn vereist. Configuratieargumenten worden doorgegeven aan het standaardconfiguratiescript om LCM-metagegevens in te stellen.

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

Voorbeeld van het configuratiescript in Azure Storage

Het volgende voorbeeld is afkomstig uit het overzicht van de DSC-extensiehandler. In dit voorbeeld worden Resource Manager-sjablonen gebruikt in plaats van cmdlets om de extensie te implementeren. Sla de configuratie IisInstall.ps1 op, plaats deze in een .zip bestand (bijvoorbeeld: iisinstall.zip) en upload het bestand vervolgens in een toegankelijke URL. In dit voorbeeld wordt Azure Blob Storage gebruikt, maar u kunt .zip bestanden downloaden vanaf elke willekeurige locatie.

In de Resource Manager-sjabloon geeft de volgende code de virtuele machine opdracht om het juiste bestand te downloaden en voer vervolgens de juiste PowerShell-functie uit:

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

Voorbeeld van het gebruik van azure Automation-registratiewaarden waarnaar wordt verwezen

In het volgende voorbeeld worden de RegistrationUrl en RegistrationKey opgehaald door te verwijzen naar de eigenschappen van het Azure Automation-account en de methode listkeys te gebruiken om de primaire sleutel (0) op te halen. In dit voorbeeld zijn de parameters automationAccountName en NodeConfigName aan de sjabloon verstrekt.

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

Bijwerken vanuit een vorige indeling

Alle instellingen in een eerdere indeling van de extensie (en met de openbare eigenschappen ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken of Properties) worden automatisch aangepast aan de huidige indeling van de extensie. Ze lopen net als voorheen.

In het volgende schema ziet u hoe het vorige instellingenschema eruit zag:

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

Zo past de vorige indeling zich aan de huidige indeling aan:

Naam van huidige eigenschap	Vorige schema-equivalent
settings.wmfVersion	Instellingen. WMFVersion
settings.configuration.url	Instellingen. ModulesUrl
settings.configuration.script	Eerste deel van de instellingen. ConfigurationFunction (vóór \\)
settings.configuration.function	Tweede deel van de instellingen. ConfigurationFunction (na \\)
settings.configuration.module.name	Instellingen. ModuleSource
settings.configuration.module.version	Instellingen. ModuleVersion
settings.configurationArguments	Instellingen. Eigenschappen
settings.configurationData.url	protectedSettings.DataBlobUri (zonder SAS-token)
settings.privacy.dataCollection	Instellingen. Privacy.dataCollection
settings.advancedOptions.downloadMappings	Instellingen. AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	Instellingen. SasToken
protectedSettings.configurationDataUrlSasToken	SAS-token van protectedSettings.DataBlobUri

Probleemoplossing

Hier volgen enkele van de fouten die u kunt tegenkomen en hoe u deze kunt oplossen.

Ongeldige waarden

"Privacy.dataCollection is '{0}'. De enige mogelijke waarden zijn '', 'Inschakelen' en 'Uitschakelen'. "WmfVersion is '{0}'. Alleen mogelijke waarden zijn ... en 'latest'.

Probleem: een opgegeven waarde is niet toegestaan.

Oplossing: Wijzig de ongeldige waarde in een geldige waarde. Zie de tabel in Details voor meer informatie.

Ongeldige URL

"ConfigurationData.url is '{0}'. Dit is geen geldige URL' 'DataBlobUri is '{0}'. Dit is geen geldige URL' 'Configuration.url is '{0}'. Dit is geen geldige URL"

Probleem: een opgegeven URL is ongeldig.

Oplossing: Controleer alle opgegeven URL's. Zorg ervoor dat alle URL's worden omgezet naar geldige locaties waartoe de extensie toegang heeft op de externe computer.

Ongeldig type RegistrationKey

"Ongeldig type voor parameter RegistrationKey van type PSCredential."

Probleem: De waarde RegistrationKey in protectedSettings.configurationArguments kan niet worden opgegeven als een ander type dan een PSCredential.

Oplossing: Wijzig de vermelding protectedSettings.configurationArguments voor RegistrationKey in een PSCredential-type met behulp van de volgende indeling:

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

Ongeldig configurationArgument-type

"Ongeldig type {0}configurationArguments "

Probleem: de eigenschap ConfigurationArguments kan niet worden omgezet in een Hash-tabelobject .

Oplossing: Maak van de eigenschap ConfigurationArguments een Hash-tabel. Volg de indeling in de voorgaande voorbeelden. Let op aanhalingstekens, komma's en accolades.

Dubbele ConfigurationArguments

"Dubbele argumenten gevonden "{0}" in zowel openbare als beveiligde configurationArguments"

Probleem: De ConfigurationArguments in openbare instellingen en configurationArguments in beveiligde instellingen hebben eigenschappen met dezelfde naam.

Oplossing: Verwijder een van de dubbele eigenschappen.

Ontbrekende eigenschappen

"instellingen. Configuration.function vereist dat settings.configuration.url of settings.configuration.module is opgegeven"

"instellingen. Configuration.url vereist dat settings.configuration.script is opgegeven"

"instellingen. Configuration.script vereist dat settings.configuration.url is opgegeven"

"instellingen. Configuration.url vereist dat settings.configuration.function is opgegeven"

"protectedSettings.ConfigurationUrlSasToken vereist dat settings.configuration.url is opgegeven"

"protectedSettings.ConfigurationDataUrlSasToken vereist dat settings.configurationData.url is opgegeven"

Probleem: een gedefinieerde eigenschap heeft een andere eigenschap nodig, die ontbreekt.

Oplossingen:

• Geef de ontbrekende eigenschap op.
• Verwijder de eigenschap waarvoor de ontbrekende eigenschap nodig is.

Volgende stappen

• Meer informatie over het gebruik van virtuele-machineschaalsets met de Azure DSC-extensie.
• Meer informatie over het veilige referentiebeheer van DSC.
• Krijg een inleiding tot de Azure DSC-extensiehandler.
• Ga naar het PowerShell-documentatiecentrum voor meer informatie over PowerShell DSC.