PowerShell DSC-Erweiterung

Artikel
06/01/2023

Hinweis

Bevor Sie die DSC-Erweiterung aktivieren, möchten wir Sie darauf hinweisen, dass jetzt eine neuere Version von DSC allgemein verfügbar ist, die von einer Funktion von Azure Automanage namens Computerkonfiguration verwaltet wird. Die Computerkonfigurationsfunktion kombiniert Funktionen des DSC-Erweiterungshandlers (Desired State Configuration), der Azure Automation State Configuration und die am häufigsten angeforderten Funktionen aus Kundenfeedback. Die Computerkonfiguration umfasst auch die Unterstützung von Hybridcomputern über Arc-fähige Server.

Übersicht

Die PowerShell-DSC-Erweiterung für Windows wird von Microsoft veröffentlicht und unterstützt. Die Erweiterung lädt eine PowerShell-DSC-Konfiguration auf einer Azure-VM hoch und wendet diese an. Die DSC-Erweiterung richtet einen Aufruf an PowerShell DSC, um die empfangene DSC-Konfiguration auf der VM in Kraft zu setzen. Dieses Dokument enthält ausführliche Informationen zu den unterstützten Plattformen, Konfigurationen und Bereitstellungsoptionen für die DSC-VM-Erweiterung für Windows.

Voraussetzungen

Betriebssystem

Die DSC-Erweiterung unterstützt die folgenden Betriebssysteme:

Windows Server 2022, Windows Server 2019, Windows Server 2016, Windows Server 2012R2, Windows Server 2012, Windows Server 2008 R2 SP1, Windows Client 7/8.1/10

Internetkonnektivität

Für die DSC-Erweiterung ist es erforderlich, dass der virtuelle Zielcomputer in der Lage ist, mit Azure zu kommunizieren, und der Speicherort des Konfigurationspakets (ZIP-Datei) außerhalb von Azure liegt.

Erweiterungsschema

Der folgende JSON-Code zeigt das Schema für den Bereich mit den Einstellungen der DSC-Erweiterung in einer Azure Resource Manager-Vorlage.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "Microsoft.Powershell.DSC",
  "apiVersion": "2018-10-01",
  "location": "<location>",
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "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": {
            "forcePullAndApply": false,
            "downloadMappings": {
             "specificDependencyKey": "https://myCustomDependencyLocation"
            }
        }
    },
    "protectedSettings": {
        "configurationArguments": {
            "parameterOfTypePSCredential1": {
                "userName": "UsernameValue1",
                "password": "PasswordValue1"
            },
            "parameterOfTypePSCredential2": {
                "userName": "UsernameValue2",
                "password": "PasswordValue2"
            }
        },
        "configurationUrlSasToken": "?g!bber1sht0k3n",
        "configurationDataUrlSasToken": "?dataAcC355T0k3N"
    }
  }
}

Eigenschaftswerte

Name	Wert/Beispiel	Datentyp
apiVersion	2018-10-01	date
publisher	Microsoft.Powershell.DSC	Zeichenfolge
type	DSC	Zeichenfolge
typeHandlerVersion	2.77	int

Eigenschaftswerte der Einstellungen

Name	Datentyp	BESCHREIBUNG
settings.wmfVersion	Zeichenfolge	Gibt die Version von Windows Management Framework an, die auf Ihrem virtuellen Computer installiert sein muss. Wenn diese Eigenschaft auf „latest“ festgelegt ist, wird die aktuelle Version von WMF installiert. Die einzigen derzeit möglichen Werte für diese Eigenschaft sind „4.0“, „5.0“ und „latest“. Diese möglichen Werte werden gelegentlich aktualisiert. Der Standardwert ist „latest“.
settings.configuration.url	Zeichenfolge	Gibt den URL-Speicherort an, von dem die ZIP-Datei Ihrer DSC-Konfiguration herunterzuladen ist. Wenn die bereitgestellte URL ein SAS-Token für den Zugriff erfordert, müssen Sie die protectedSettings.configurationUrlSasToken-Eigenschaft auf den Wert Ihres SAS-Tokens festlegen. Diese Eigenschaft ist erforderlich, wenn „settings.configuration.script“ und/oder „settings.configuration.function“ definiert sind.
settings.configuration.script	Zeichenfolge	Gibt den Dateinamen des Skripts an, das die Definition Ihrer DSC-Konfiguration enthält. Dieses Skript muss sich im Stammverzeichnis der ZIP-Datei befinden, die von der durch die configuration.url-Eigenschaft angegebenen URL heruntergeladen wurde. Diese Eigenschaft ist erforderlich, wenn „settings.configuration.url“ und/oder „settings.configuration.script“ definiert sind.
settings.configuration.function	Zeichenfolge	Gibt den Namen Ihrer DSC-Konfiguration an. Die Konfiguration mit diesem Namen muss im Skript enthalten sein, das durch „configuration.script“ definiert ist. Diese Eigenschaft ist erforderlich, wenn „settings.configuration.url“ und/oder „settings.configuration.function“ definiert sind.
settings.configurationArguments	Collection	Definiert beliebige Parameter, die Sie Ihrer DSC-Konfiguration übergeben möchten. Diese Eigenschaft wird nicht verschlüsselt.
settings.configurationData.url	Zeichenfolge	Gibt die URL an, unter der die Datei mit Ihren Konfigurationsdaten (.pds1) heruntergeladen werden kann, um sie als Eingabe für Ihre DSC-Konfiguration zu nutzen. Wenn die bereitgestellte URL ein SAS-Token für den Zugriff erfordert, müssen Sie die protectedSettings.configurationDataUrlSasToken-Eigenschaft auf den Wert Ihres SAS-Tokens festlegen.
settings.privacy.dataEnabled	Zeichenfolge	Aktiviert bzw. deaktiviert die Erfassung von Telemetriedaten. Die einzig möglichen Werte für diese Eigenschaft sind „Enable“, „Disable“, „''“ oder „$null“. Wird die Eigenschaft leer gelassen oder „null“ angegeben, ist die Telemetrie aktiviert.
settings.advancedOptions.forcePullAndApply	Bool	Diese Einstellung ist dafür ausgelegt, die Arbeitserfahrung im Umgang mit der Erweiterung beim Registrieren von Knoten bei Azure Automation DSC zu verbessern. Wenn der Wert auf `$true` festgelegt ist, wartet die Erweiterung die erste Ausführung der beim Dienst abgerufenen Konfiguration ab, bevor er die Erfolgs-/Fehlermeldung zurückgibt. Wenn der Wert auf „$false“ festgelegt ist, bezieht sich der von der Erweiterung zurückgegebene Status lediglich darauf, ob der Knoten erfolgreich bei Azure Automation State Configuration registriert wurde, und die Knotenkonfiguration wird während der Registrierung nicht ausgeführt.
settings.advancedOptions.downloadMappings	Collection	Definiert alternative Speicherorte zum Herunterladen von Abhängigkeiten wie WMF und .NET.

Eigenschaftswerte geschützter Einstellungen

Name	Datentyp	Beschreibung
protectedSettings.configurationArguments	Zeichenfolge	Definiert beliebige Parameter, die Sie Ihrer DSC-Konfiguration übergeben möchten. Diese Eigenschaft wird verschlüsselt.
protectedSettings.configurationUrlSasToken	Zeichenfolge	Gibt das SAS-Token für den Zugriff auf durch „configuration.url“ definierte URL an. Diese Eigenschaft wird verschlüsselt.
protectedSettings.configurationDataUrlSasToken	Zeichenfolge	Gibt das SAS-Token für den Zugriff auf durch „configurationData.url“ definierte URL an. Diese Eigenschaft wird verschlüsselt.

Bereitstellung von Vorlagen

Azure-VM-Erweiterungen können mithilfe von Azure Resource Manager-Vorlagen bereitgestellt werden. Vorlagen sind ideal, wenn Sie virtuelle Computer bereitstellen, die nach der Bereitstellung konfiguriert werden müssen. Eine Resource Manager-Beispielvorlage mit der DSC-Erweiterung für Windows finden Sie im Azure-Schnellstartkatalog.

Problembehandlung und Support

Problembehandlung

Daten zum Status von Erweiterungsbereitstellungen können über das Azure-Portal und mithilfe der Azure-Befehlszeilenschnittstelle abgerufen werden. Führen Sie über die Azure-Befehlszeilenschnittstelle den folgenden Befehl aus, um den Bereitstellungsstatus von Erweiterungen für einen bestimmten virtuellen Computer anzuzeigen.

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

Das Erweiterungspaket wird an diesem Speicherort auf der Azure-VM heruntergeladen und bereitgestellt.

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}

Die Statusdatei der Erweiterung enthält den untergeordneten Status und die Erfolgs-/Fehlercodes des Status zusammen mit der ausführlichen Fehlermeldung und einer Beschreibung für jede Erweiterungsausführung.

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}\Status\{0}.Status  -> {0} being the sequence number

Ausgabeprotokolle der Erweiterung werden im folgenden Verzeichnis protokolliert:

C:\WindowsAzure\Logs\Plugins\{Extension_Name}\{Extension_Version}

Fehlercodes und ihre Bedeutung

Fehlercode	Bedeutung	Mögliche Aktion
1000	Allgemeiner Fehler	Die Nachricht für diesen Fehler wird durch die spezifische Ausnahme in Erweiterungsprotokollen bereitgestellt.
52	Fehler bei der Installation der Erweiterung	Die Nachricht für diesen Fehler wird durch die spezifische Ausnahme bereitgestellt.
1002	Fehler bei der Installation von WMF	Dies ist ein Fehler bei der Installation von WMF.
1004	Ungültiges ZIP-Paket	Ungültige ZIP-Datei. Fehler beim Entpacken der ZIP-Datei.
1100	Argumentfehler	Weist auf ein Problem in der vom Benutzer bereitgestellten Eingabe hin. Die Nachricht für den Fehler wird durch die spezifische Ausnahme bereitgestellt.

Support

Sollten Sie beim Lesen dieses Artikels feststellen, dass Sie weitere Hilfe benötigen, können Sie sich über das MSDN Azure-Forum oder über das Stack Overflow-Forum mit Azure-Experten in Verbindung setzen. Alternativ dazu haben Sie die Möglichkeit, einen Azure-Supportfall zu erstellen. Rufen Sie die Azure-Support-Website auf, und wählen Sie „Support erhalten“ aus. Informationen zur Nutzung von Azure-Support finden Sie unter Microsoft Azure-Support-FAQ.