Desired State Configuration tillägg med Azure Resource Manager-mallar

Artikel
06/01/2023

Anteckning

Innan du aktiverar DSC-tillägget vill vi att du ska veta att en nyare version av DSC nu är allmänt tillgänglig, som hanteras av en funktion i Azure Automange med namnet machine configuration. Datorkonfigurationsfunktionen kombinerar funktioner i Desired State Configuration(DSC) tilläggshanterare, Azure Automation State Configuration och de vanligaste begärda funktionerna från kundfeedback. Datorkonfigurationen omfattar även stöd för hybriddatorer via Arc-aktiverade servrar.

Den här artikeln beskriver Azure Resource Manager-mallen för Desired State Configuration-tilläggshanteraren (DSC). Många av exemplen använder RegistrationURL (tillhandahålls som en sträng) och RegistrationKey (tillhandahålls som en PSCredential för att registrera med Azure Automation. Mer information om hur du hämtar dessa värden finns i Använda DSC-metakonfiguration för att registrera hybriddatorer.

Anteckning

Du kan stöta på lite olika schemaexempel. Schemaändringen inträffade i oktober 2016-versionen. Mer information finns i Uppdatera från ett tidigare format.

Mallexempel för en virtuell Windows-dator

Följande kodfragment finns i avsnittet Resurs i mallen. DSC-tillägget ärver standardtilläggsegenskaper. Mer information finns i Klassen 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"
        }
      ]
    }
  }
}

Mallexempel för skalningsuppsättningar för virtuella Windows-datorer

En vm-skalningsuppsättningsnod har ett egenskapsavsnitt som har attributet VirtualMachineProfile, extensionProfile . Under tillägg lägger du till information för DSC-tillägget.

DSC-tillägget ärver standardtilläggsegenskaper. Mer information finns i Klassen 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"
              }
            ]
          }
        }
      }
    ]
  }

Detaljerad information om inställningar

Använd följande schema i inställningsavsnittet i Azure DSC-tillägget i en Resource Manager mall.

En lista över de argument som är tillgängliga för standardkonfigurationsskriptet finns i Standardkonfigurationsskript.

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

Information

Egenskapsnamn	Typ	Beskrivning
settings.wmfVersion	sträng	Anger vilken version av Windows Management Framework (WMF) som ska installeras på den virtuella datorn. Om du ställer in den här egenskapen på senaste installerar du den senaste versionen av WMF. För närvarande är de enda möjliga värdena för den här egenskapen 4.0, 5.0, 5.1 och senaste. Dessa möjliga värden är föremål för uppdateringar. Standardvärdet är det senaste.
settings.configuration.url	sträng	Anger den URL-plats som DSC-konfigurationen ska laddas ned från .zip fil. Om den angivna URL:en kräver en SAS-token för åtkomst anger du egenskapen protectedSettings.configurationUrlSasToken till värdet för din SAS-token. Den här egenskapen krävs om settings.configuration.script eller settings.configuration.function har definierats. Om inget värde anges för dessa egenskaper anropar tillägget standardkonfigurationsskriptet för att ange LCM-metadata (Location Configuration Manager) och argument ska anges.
settings.configuration.script	sträng	Anger filnamnet för skriptet som innehåller definitionen av DSC-konfigurationen. Det här skriptet måste finnas i rotmappen för den .zip fil som laddas ned från url:en som anges av egenskapen settings.configuration.url . Den här egenskapen krävs om settings.configuration.url eller settings.configuration.script har definierats. Om inget värde anges för dessa egenskaper anropar tillägget standardkonfigurationsskriptet för att ange LCM-metadata, och argument ska anges.
settings.configuration.function	sträng	Anger namnet på din DSC-konfiguration. Konfigurationen som heter måste ingå i skriptet som settings.configuration.script definierar. Den här egenskapen krävs om settings.configuration.url eller settings.configuration.function har definierats. Om inget värde anges för dessa egenskaper anropar tillägget standardkonfigurationsskriptet för att ange LCM-metadata, och argument ska anges.
settings.configurationArguments	Samling	Definierar alla parametrar som du vill skicka till din DSC-konfiguration. Den här egenskapen är inte krypterad.
settings.configurationData.url	sträng	Anger från vilken URL du vill ladda ned konfigurationsdatafilen (.psd1) som ska användas som indata för din DSC-konfiguration. Om den angivna URL:en kräver en SAS-token för åtkomst anger du egenskapen protectedSettings.configurationDataUrlSasToken till värdet för din SAS-token.
settings.privacy.dataCollection	sträng	Aktiverar eller inaktiverar telemetrisamling. De enda möjliga värdena för den här egenskapen är Aktivera, Inaktivera, '' eller $null. Om du lämnar den här egenskapen tom eller null aktiveras telemetri. Standardvärdet är ''. Mer information finns i Datainsamling för Azure DSC-tillägg.
settings.advancedOptions.downloadMappings	Samling	Definierar alternativa platser som WMF ska laddas ned från. Mer information finns i Azure DSC-tillägget 2.8 och hur du mappar nedladdningar av tilläggsberoenden till din egen plats.
protectedSettings.configurationArguments	Samling	Definierar alla parametrar som du vill skicka till din DSC-konfiguration. Den här egenskapen är krypterad.
protectedSettings.configurationUrlSasToken	sträng	Anger den SAS-token som ska användas för att komma åt den URL som settings.configuration.url definierar. Den här egenskapen är krypterad.
protectedSettings.configurationDataUrlSasToken	sträng	Anger den SAS-token som ska användas för att komma åt den URL som settings.configurationData.url definierar. Den här egenskapen är krypterad.

Standardkonfigurationsskript

Mer information om följande värden finns i Lokala Configuration Manager grundläggande inställningar. Du kan använda standardkonfigurationsskriptet för DSC-tillägget för att konfigurera de LCM-egenskaper som visas i följande tabell.

Egenskapsnamn	Typ	Beskrivning
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Nödvändig egenskap. Anger den nyckel som används för att en nod ska registreras med Azure Automation-tjänsten som lösenord för ett PowerShell-autentiseringsobjekt. Det här värdet kan identifieras automatiskt med hjälp av listkeys-metoden mot Automation-kontot. Se exemplet.
settings.configurationArguments.RegistrationUrl	sträng	Obligatorisk egenskap. Anger URL:en för Automation-slutpunkten där noden försöker registrera sig. Det här värdet kan identifieras automatiskt med hjälp av referensmetoden mot Automation-kontot.
settings.configurationArguments.NodeConfigurationName	sträng	Obligatorisk egenskap. Anger nodkonfigurationen i Automation-kontot som ska tilldelas till noden.
settings.configurationArguments.ConfigurationMode	sträng	Anger läget för LCM. Giltiga alternativ är ApplyOnly, ApplyandMonitor och ApplyandAutoCorrect. Standardvärdet är ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Anger hur ofta LCM försöker kontrollera uppdateringar med Automation-kontot. Standardvärdet är 30. Minimivärdet är 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Anger hur ofta LCM validerar den aktuella konfigurationen. Standardvärdet är 15. Minimivärdet är 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Anger om en nod kan startas om automatiskt om en DSC-åtgärd begär den. Standardvärdet är false.
settings.configurationArguments.ActionAfterReboot	sträng	Anger vad som händer efter en omstart när du tillämpar en konfiguration. Giltiga alternativ är ContinueConfiguration och StopConfiguration. Standardvärdet är ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Anger om LCM skriver över befintliga moduler på noden. Standardvärdet är false.

inställningar jämfört med skyddadeInställningar

Alla inställningar sparas i en textfil för inställningar på den virtuella datorn. Egenskaper som anges under inställningar är offentliga egenskaper. Offentliga egenskaper krypteras inte i textfilen för inställningar. Egenskaper som anges under skyddadeInställningar krypteras med ett certifikat och visas inte i oformaterad text i inställningsfilen på den virtuella datorn.

Om konfigurationen behöver autentiseringsuppgifter kan du inkludera autentiseringsuppgifterna i protectedSettings:

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

Exempel på konfigurationsskript

I följande exempel visas standardbeteendet för DSC-tillägget, som är att tillhandahålla metadatainställningar till LCM och registrera med Automation DSC-tjänsten. Konfigurationsargument krävs. Konfigurationsargument skickas till standardkonfigurationsskriptet för att ange LCM-metadata.

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

Exempel med konfigurationsskriptet i Azure Storage

Följande exempel är från översikten över DSC-tilläggshanteraren. I det här exemplet används Resource Manager mallar i stället för cmdletar för att distribuera tillägget. Spara IisInstall.ps1-konfigurationen, placera den i en .zip fil (exempel: iisinstall.zip) och ladda sedan upp filen i en tillgänglig URL. I det här exemplet används Azure Blob Storage, men du kan ladda ned .zip filer från valfri plats.

I mallen Resource Manager instruerar följande kod den virtuella datorn att ladda ned rätt fil och kör sedan lämplig PowerShell-funktion:

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

Exempel med refererade Azure Automation registreringsvärden

I följande exempel hämtas RegistrationUrl och RegistrationKey genom att referera till egenskaperna för Azure Automation-kontot och använda metoden listkeys för att hämta primärnyckeln (0). I det här exemplet angavs parametrarna automationAccountName och NodeConfigName till mallen.

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

Uppdatera från ett tidigare format

Alla inställningar i ett tidigare format av tillägget (och som har de offentliga egenskaperna ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken eller Properties) anpassas automatiskt till det aktuella formatet för tillägget. De springer precis som de gjorde förut.

Följande schema visar hur det tidigare inställningsschemat såg ut:

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

Så här anpassar sig det tidigare formatet till det aktuella formatet:

Aktuellt egenskapsnamn	Tidigare schemamotsvarighet
settings.wmfVersion	Inställningar. WMFVersion
settings.configuration.url	Inställningar. ModulesUrl
settings.configuration.script	Första delen av inställningarna. ConfigurationFunction (före \\)
settings.configuration.function	Andra delen av inställningarna. ConfigurationFunction (efter \\)
settings.configuration.module.name	Inställningar. ModuleSource
settings.configuration.module.version	Inställningar. ModuleVersion
settings.configurationArguments	Inställningar. Egenskaper
settings.configurationData.url	protectedSettings.DataBlobUri (utan SAS-token)
settings.privacy.dataCollection	Inställningar. Privacy.dataCollection
settings.advancedOptions.downloadMappings	Inställningar. AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	Inställningar. SasToken
protectedSettings.configurationDataUrlSasToken	SAS-token från protectedSettings.DataBlobUri

Felsökning

Här följer några av de fel som du kan stöta på och hur du kan åtgärda dem.

Ogiltiga värden

"Privacy.dataCollection är '{0}'. De enda möjliga värdena är "", "Aktivera" och "Inaktivera". "WmfVersion är '{0}'. Endast möjliga värden är ... och "senaste".

Problem: Ett angivet värde tillåts inte.

Lösning: Ändra det ogiltiga värdet till ett giltigt värde. Mer information finns i tabellen i Information.

Ogiltig URL

"ConfigurationData.url är '{0}'. Det här är inte en giltig URL: "DataBlobUri är "{0}". Det här är inte en giltig URL: "Configuration.url är "{0}". Detta är inte en giltig URL"

Problem: En angivet URL är inte giltig.

Lösning: Kontrollera alla dina angivna URL:er. Kontrollera att alla URL:er matchar giltiga platser som tillägget kan komma åt på fjärrdatorn.

Ogiltig RegistrationKey-typ

"Ogiltig typ för parametern RegistrationKey av typen PSCredential."

Problem: Värdet RegistrationKey i protectedSettings.configurationArguments kan inte anges som någon annan typ än en PSCredential.

Lösning: Ändra posten protectedSettings.configurationArguments för RegistrationKey till en PSCredential-typ med följande format:

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

Ogiltig ConfigurationArgument-typ

"Ogiltig configurationArguments-typ {0}"

Problem: Egenskapen ConfigurationArguments kan inte matcha ett Hash-tabellobjekt .

Lösning: Gör egenskapen ConfigurationArguments till en Hash-tabell. Följ formatet i föregående exempel. Håll utkik efter citattecken, kommatecken och klammerparenteser.

Duplicera ConfigurationArguments

"Hittade duplicerade argument "{0} i både offentliga och skyddade configurationArguments"

Problem: ConfigurationArguments i offentliga inställningar och ConfigurationArguments i skyddade inställningar har egenskaper med samma namn.

Lösning: Ta bort en av dubblettegenskaperna.

Egenskaper som saknas

"inställningar. Configuration.function kräver att settings.configuration.url eller settings.configuration.module anges"

"inställningar. Configuration.url kräver att settings.configuration.script anges"

"inställningar. Configuration.script kräver att settings.configuration.url anges"

"inställningar. Configuration.url kräver att settings.configuration.function anges"

"protectedSettings.ConfigurationUrlSasToken kräver att settings.configuration.url anges"

"protectedSettings.ConfigurationDataUrlSasToken kräver att settings.configurationData.url anges"

Problem: En definierad egenskap behöver en annan egenskap som saknas.

Lösningar:

Ange egenskapen som saknas.
Ta bort egenskapen som behöver egenskapen som saknas.

Nästa steg

Lär dig mer om hur du använder VM-skalningsuppsättningar med Azure DSC-tillägget.
Mer information om DSC:s hantering av säkra autentiseringsuppgifter finns.
Få en introduktion till Azure DSC-tilläggshanteraren.
Mer information om PowerShell DSC finns i PowerShell-dokumentationscentret.