Erweiterung zum Konfigurieren des gewünschten Zustands mit Azure Resource Manager-Vorlagen

Artikel
12/20/2024

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 namens Computerkonfiguration verwaltet wird. Die Computerkonfigurationsfunktion kombiniert Features des DSC-Erweiterungshandlers (Desired State Configuration) und die am häufigsten angeforderten Features aus Kundenfeedback. Die Computerkonfiguration umfasst auch die Unterstützung von Hybridcomputern über Arc-fähige Server.

Dieser Artikel beschreibt die Azure Resource Manager-Vorlage für den Handler der Azure-Erweiterung zum Konfigurieren des gewünschten Zustands (Desired State Configuration, DSC).

Hinweis

Möglicherweise werden Ihnen andere Schemabeispiele angezeigt. Das Schema wurde im Release von Oktober 2016 geändert. Weitere Informationen finden Sie im Abschnitt zum Update von einem vorherigen Format.

Bicep-Beispiel für eine VM

Die DSC-Erweiterung erbt die Standardwerte für die Erweiterungseigenschaften. Weitere Informationen finden Sie unter VirtualMachineExtension Class (VirtualMachineExtension-Klasse).

@description('URI of the configuration package')
param configUri string

@description('first configuration parameter')
param arg1 string

@description('second configuration parameter')
@secure()
param arg2 string

var configName = split(split(configUri, '/')[4], '.')[0]

resource vm 'Microsoft.Compute/virtualMachines@2023-09-01' existing = {
  name: srvName
}

resource configuration_dscext 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: 'configurationname_dscext'
  parent: vm
  location: location
  properties: {
    publisher: 'Microsoft.Powershell'
    type: 'DSC'
    typeHandlerVersion: '2.77'
    autoUpgradeMinorVersion: true
    settings: {
      wmfVersion: 'latest'
      configuration: {
        url: configUri
        script: 'configurationname_dscext.ps1'
        function: 'configurationname_dscext'
      }
      configurationArguments: {
        arg1: arg1
      }
      advancedOptions: {
        rebootNodeIfNeeded: true
      }
    }
    protectedSettings: {
      configurationArguements: {
        arg2: arg2
      }
    }
  }
}

Bicep-Beispiel für Skalierungsgruppen virtueller Windows-Computer

Ein VM-Skalierungsgruppenknoten verfügt über einen Abschnitt, der ein extensionProfile-Attribut enthält. Fügen Sie unter Erweiterungen die Details für die DSC-Erweiterung hinzu.

Die neuesten Details zur Erstellung von Vorlagen, die Erweiterungen für Skalierungsgruppen für virtuelle Computer bereitstellen, finden Sie im Dokument Microsoft.Compute virtualMachineScaleSets

Die DSC-Erweiterung erbt die Standardwerte für die Erweiterungseigenschaften. Weitere Informationen finden Sie unter VirtualMachineScaleSetExtension Class (VirtualMachineScaleSetExtension-Klasse).

„Settings“ im Vergleich zu „protectedSettings“

Alle Einstellungen werden auf dem virtuellen Computer in einer Einstellungstextdatei gespeichert. Eigenschaften unter Einstellungen sind öffentliche Eigenschaften. Öffentliche Eigenschaften werden nicht in der Einstellungstextdatei verschlüsselt. Eigenschaften unter protectedSettings sind mit einem Zertifikat verschlüsselt und werden in der Einstellungsdatei auf dem virtuellen Computer nicht als Nur-Text angezeigt.

Wenn die Konfiguration Anmeldeinformationen erfordert, können diese in protectedSettings enthalten sein:

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

Beispiel für die Verwendung des Konfigurationsskripts in Azure Storage

Das folgende Beispiel stammt aus dem Abschnitt DSC Erweiterung: Handler-Übersicht. In diesem Beispiel werden Resourcen Manager-Vorlagen anstelle von Cmdlets zum Bereitstellen der Erweiterung verwendet. Speichern Sie die Konfiguration „IisInstall.ps1“, fügen Sie sie einer ZIP-Datei hinzu (Beispiel: iisinstall.zip), und laden Sie die Datei unter einer zugänglichen URL hoch. In diesem Beispiel wird Azure Blob Storage verwendet. Sie können ZIP-Dateien jedoch von beliebigen Speicherorten herunterladen.

In der Resource Manager-Vorlage weist der folgende Code den virtuellen Computer an, die richtige Datei herunterzuladen und die entsprechende PowerShell-Funktion auszuführen:

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

Aktualisieren vom vorherigen Format

Alle Einstellungen im vorherigen Format der Erweiterung (und mit den öffentlichen Eigenschaften ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken oder Properties) werden automatisch an das aktuelle Format angepasst. Sie werden wie gehabt ausgeführt.

Das frühere Einstellungsschema sah folgendermaßen aus:

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

So wird das frühere Format an das aktuelle Format angepasst:

Name der aktuellen Eigenschaft	Entsprechung im früheren Schema
settings.wmfVersion	settings.wmfVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	Erster Teil von settings.ConfigurationFunction (vor //)
settings.configuration.function	Zweiter Teil von settings.ConfigurationFunction (nach //)
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri (ohne SAS-Token)
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.advancedOptions.downloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	SAS-Token aus „protectedSettings.DataBlobUri“

Problembehandlung

Hier finden Sie einige Fehler, die auftreten können, und die entsprechenden Behebungen.

Ungültige Werte

„Privacy.dataCollection ist '{0}'. Die einzig möglichen Werte sind '', 'Aktivieren' und 'Deaktivieren'.“ „WmfVersion ist '{0}'. Einzig mögliche Werte sind ... und 'neueste'.“

Problem: Ein bereitgestellter Wert ist nicht zulässig.

Lösung: Ändern Sie den ungültigen Wert in einen gültigen Wert.

Ungültige URL

„ConfigurationData.url ist '{0}'. Dies ist keine gültige URL“ „DataBlobUri ist '{0}'. Dies ist keine gültige URL“ „Configuration.url ist '{0}'. Dies ist keine gültige URL“

Problem: Eine bereitgestellte URL ist ungültig.

Lösung: Überprüfen Sie alle angegebenen URLs. Stellen Sie sicher, dass alle URLs in gültige Speicherorte aufgelöst werden, auf die die Erweiterung auf dem Remotecomputer zugreifen kann.

Ungültiger ConfigurationArgument-Typ

„Ungültiger ConfigurationArguments-Typ {0}“

Problem: Die Eigenschaft ConfigurationArguments kann nicht zu einem Hashtabellenobjekt aufgelöst werden.

Lösung: Machen Sie aus der Eigenschaft ConfigurationArguments eine Hashtabelle. Verwenden Sie dabei das Format aus den vorherigen Beispielen. Achten Sie auf Anführungszeichen, Kommas und Klammern.

„ConfigurationArguments“ doppelt vorhanden

„Doppelte Argumente '{0}' sowohl in öffentlichen als auch geschützten configurationArguments-Elementen gefunden“

Problem: ConfigurationArguments in öffentlichen Einstellungen und ConfigurationArguments in geschützten Einstellungen enthalten Eigenschaften mit dem gleichen Namen.

Lösung: Entfernen Sie eine der doppelten Eigenschaften.

Fehlende Eigenschaften

„settings.Configuration.function erfordert die Angabe von settings.configuration.url oder settings.configuration.module“

„settings.Configuration.url erfordert die Angabe von settings.configuration.script“

„settings.Configuration.script erfordert die Angabe von settings.configuration.url“

„settings.Configuration.url erfordert die Angabe von settings.configuration.function“

„protectedSettings.ConfigurationUrlSasToken erfordert die Angabe von settings.configuration.url“

„protectedSettings.ConfigurationDataUrlSasToken erfordert die Angabe von settings.configurationData.url“

Problem: Eine definierte Eigenschaft benötigt eine andere Eigenschaft, die nicht vorhanden ist.

Lösungen:

Geben Sie die fehlende Eigenschaft an.
Entfernen Sie die Eigenschaft, die die fehlende Eigenschaft benötigt.

Nächste Schritte

Erfahren Sie mehr über das Verwenden von VM-Skalierungsgruppen mit der Azure DSC-Erweiterung.
Weitere Informationen finden Sie unter Sichere Verwaltung von Anmeldeinformationen durch DSC.
Lesen Sie die Einführung in den Azure DSC-Erweiterungshandler.
Weitere Informationen zu PowerShell DSC finden Sie im PowerShell-Dokumentationscenter.

Freigeben über