Freigeben über


PowerShell DSC-Erweiterung

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.