Introduktion till tilläggshanteraren för Azure Desired State ConfigurationIntroduction to the Azure Desired State Configuration extension handler

Azure VM-agenten och de associerade tilläggen ingår i Microsoft Azure infrastruktur tjänster.The Azure VM Agent and associated extensions are part of Microsoft Azure infrastructure services. VM-tillägg är program varu komponenter som utökar VM-funktioner och fören klar olika hanterings åtgärder för virtuella datorer.VM extensions are software components that extend VM functionality and simplify various VM management operations.

Det främsta användnings fallet för Azures tillägg för önskad tillstånds konfiguration (DSC) är att starta en virtuell dator till tjänsten Azure Automation State Configuration (DSC).The primary use case for the Azure Desired State Configuration (DSC) extension is to bootstrap a VM to the Azure Automation State Configuration (DSC) service. Tjänsten ger fördelar som omfattar pågående hantering av VM-konfigurationen och integrering med andra operativa verktyg, till exempel Azure-övervakning.The service provides benefits that include ongoing management of the VM configuration and integration with other operational tools, such as Azure Monitoring. Att använda tillägget för att registrera virtuella datorer till tjänsten är en flexibel lösning som även fungerar i Azure-prenumerationer.Using the extension to register VM's to the service provides a flexible solution that even works across Azure subscriptions.

Du kan använda DSC-tillägget oberoende av Automation DSC tjänsten.You can use the DSC extension independently of the Automation DSC service. Detta kommer dock bara att push-överföra en konfiguration till den virtuella datorn.However, this will only push a configuration to the VM. Ingen kontinuerlig rapportering är tillgänglig, förutom lokalt på den virtuella datorn.No ongoing reporting is available, other than locally in the VM.

Den här artikeln innehåller information om båda scenarierna: använda DSC-tillägget för automatisering onboarding och använda DSC-tillägget som ett verktyg för att tilldela konfigurationer till virtuella datorer med hjälp av Azure SDK.This article provides information about both scenarios: using the DSC extension for Automation onboarding, and using the DSC extension as a tool for assigning configurations to VMs by using the Azure SDK.

FörutsättningarPrerequisites

  • Lokal dator: om du vill interagera med tillägget för Azure VM måste du antingen använda Azure Portal eller Azure PowerShell SDK.Local machine: To interact with the Azure VM extension, you must use either the Azure portal or the Azure PowerShell SDK.
  • Gästa Gent: den virtuella Azure-dator som konfigureras av DSC-konfigurationen måste vara ett operativ system som stöder Windows Management Framework (WMF) 4,0 eller senare.Guest Agent: The Azure VM that's configured by the DSC configuration must be an OS that supports Windows Management Framework (WMF) 4.0 or later. En fullständig lista över OS-versioner som stöds finns i versions historik för DSC-tillägg.For the full list of supported OS versions, see the DSC extension version history.

Termer och begreppTerms and concepts

Den här guiden förutsätter att du är bekant med följande begrepp:This guide assumes familiarity with the following concepts:

  • Konfiguration: ett DSC-konfigurationsobjekt.Configuration: A DSC configuration document.
  • Node: ett mål för en DSC-konfiguration.Node: A target for a DSC configuration. I det här dokumentet refererar noden alltid till en virtuell Azure-dator.In this document, node always refers to an Azure VM.
  • Konfigurations data: en. psd1-fil med miljö data för en konfiguration.Configuration data: A .psd1 file that has environmental data for a configuration.

ArkitekturArchitecture

Azure DSC-tillägget använder Azure VM agent Framework för att leverera, införa och rapportera om DSC-konfigurationer som körs på virtuella Azure-datorer.The Azure DSC extension uses the Azure VM Agent framework to deliver, enact, and report on DSC configurations running on Azure VMs. DSC-tillägget accepterar ett konfigurations dokument och en uppsättning parametrar.The DSC extension accepts a configuration document and a set of parameters. Om ingen fil anges bäddas ett standard konfigurations skript in med tillägget.If no file is provided, a default configuration script is embedded with the extension. Standard konfigurations skriptet används endast för att ange metadata i den lokala Configuration Manager.The default configuration script is used only to set metadata in Local Configuration Manager.

När tillägget anropas för första gången installeras en version av WMF med hjälp av följande logik:When the extension is called for the first time, it installs a version of WMF by using the following logic:

  • Om Azure VM OS är Windows Server 2016 vidtas ingen åtgärd.If the Azure VM OS is Windows Server 2016, no action is taken. Windows Server 2016 har redan den senaste versionen av PowerShell installerad.Windows Server 2016 already has the latest version of PowerShell installed.
  • Om wmfVersion -egenskapen har angetts installeras den versionen av WMF, om inte den versionen är inkompatibel med den virtuella datorns operativ system.If the wmfVersion property is specified, that version of WMF is installed, unless that version is incompatible with the VM's OS.
  • Om ingen wmfVersion -egenskap anges installeras den senaste tillämpliga versionen av WMF.If no wmfVersion property is specified, the latest applicable version of WMF is installed.

Installation av WMF kräver en omstart.Installing WMF requires a restart. Efter omstarten laddar tillägget. zip-filen som anges i egenskapen modulesUrl , om den har angetts.After restarting, the extension downloads the .zip file that's specified in the modulesUrl property, if provided. Om den här platsen finns i Azure Blob Storage kan du ange en SAS-token i egenskapen sasToken för att komma åt filen.If this location is in Azure Blob storage, you can specify an SAS token in the sasToken property to access the file. När. zip har hämtats och packats upp körs konfigurations funktionen som definieras i configurationFunction för att generera en MOF-fil (Managed Object Format).After the .zip is downloaded and unpacked, the configuration function defined in configurationFunction runs to generate an .mof(Managed Object Format) file. Tillägget körs sedan Start-DscConfiguration -Force med hjälp av den genererade MOF-filen.The extension then runs Start-DscConfiguration -Force by using the generated .mof file. Tillägget fångar utdata och skriver den till Azures status kanal.The extension captures output and writes it to the Azure status channel.

Standard konfigurations skriptDefault configuration script

Azure DSC-tillägget innehåller ett standard konfigurations skript som är avsett att användas när du registrerar en virtuell dator till tjänsten Azure Automation DSC.The Azure DSC extension includes a default configuration script that's intended to be used when you onboard a VM to the Azure Automation DSC service. Skript parametrarna är justerade med de konfigurerbara egenskaperna för lokal Configuration Manager.The script parameters are aligned with the configurable properties of Local Configuration Manager. Skript parametrar finns i standard konfigurations skript i önskat tillstånds konfigurations tillägg med Azure Resource Manager mallar.For script parameters, see Default configuration script in Desired State Configuration extension with Azure Resource Manager templates. Det fullständiga skriptet finns i mallen för Azure snabb start i GitHub.For the full script, see the Azure quickstart template in GitHub.

Information om registrering med tjänsten Azure Automation State Configuration (DSC)Information for registering with Azure Automation State Configuration (DSC) service

När du använder DSC-tillägget för att registrera en nod med tillstånds konfigurations tjänsten måste tre värden anges.When using the DSC Extension to register a node with the State Configuration service, three values will need to be provided.

  • RegistrationUrl – https-adressen för det Azure Automation kontotRegistrationUrl - the https address of the Azure Automation account
  • RegistrationKey – en delad hemlighet som används för att registrera noder med tjänstenRegistrationKey - a shared secret used to register nodes with the service
  • NodeConfigurationName – namnet på den Node-konfiguration (MOF) som ska hämtas från tjänsten för att konfigurera Server rollenNodeConfigurationName - the name of the Node Configuration (MOF) to pull from the service to configure the server role

Den här informationen kan visas i Azure Portal eller så kan du använda PowerShell.This information can be seen in the Azure portal or you can use PowerShell.

(Get-AzAutomationRegistrationInfo -ResourceGroupName <resourcegroupname> -AutomationAccountName <accountname>).Endpoint
(Get-AzAutomationRegistrationInfo -ResourceGroupName <resourcegroupname> -AutomationAccountName <accountname>).PrimaryKey

För konfigurations namnet för noden, se till att nodens konfiguration finns i konfiguration av Azure-tillstånd.For the Node Configuration name, make sure the node configuration exists in Azure State Configuration. Om den inte gör det returnerar tilläggs distributionen ett haveri.If it does not, the extension deployment will return a failure. Kontrol lera också att du använder namnet på nodens konfiguration och inte konfigurationen.Also make sure you are using the name of the Node Configuration and not the Configuration. En konfiguration definieras i ett skript som används för att kompilera Node-konfigurationen (MOF-filen).A Configuration is defined in a script that is used to compile the Node Configuration (MOF file). Namnet är alltid konfigurationen följt av en punkt . och antingen localhost eller ett särskilt dator namn.The name will always be the Configuration followed by a period . and either localhost or a specific computer name.

DSC-tillägg i Resource Manager-mallarDSC extension in Resource Manager templates

I de flesta fall är distributions mallar för Resource Manager det förväntade sättet att arbeta med DSC-tillägget.In most scenarios, Resource Manager deployment templates are the expected way to work with the DSC extension. Mer information och exempel på hur du inkluderar DSC-tillägget i distributions mallar för Resource Manager finns i önskat tillstånds konfigurations tillägg med Azure Resource Manager mallar.For more information and for examples of how to include the DSC extension in Resource Manager deployment templates, see Desired State Configuration extension with Azure Resource Manager templates.

PowerShell-cmdletar för DSC-tilläggDSC extension PowerShell cmdlets

PowerShell-cmdletar som används för att hantera DSC-tillägget används bäst i interaktiva fel söknings-och informations insamlings scenarier.The PowerShell cmdlets that are used to manage the DSC extension are best used in interactive troubleshooting and information-gathering scenarios. Du kan använda cmdlet: ar för att paketera, publicera och övervaka distributioner av DSC-tillägg.You can use the cmdlets to package, publish, and monitor DSC extension deployments. Cmdletar för DSC-tillägget har inte uppdaterats för att fungera med standard konfigurations skriptet.Cmdlets for the DSC extension aren't yet updated to work with the default configuration script.

Cmdleten Publish-AzVMDscConfiguration tar i en konfigurations fil, söker efter beroende DSC-resurser och skapar sedan en zip-fil.The Publish-AzVMDscConfiguration cmdlet takes in a configuration file, scans it for dependent DSC resources, and then creates a .zip file. Zip-filen innehåller de konfigurations-och DSC-resurser som behövs för att införa konfigurationen.The .zip file contains the configuration and DSC resources that are needed to enact the configuration. Cmdleten kan också skapa paketet lokalt med hjälp av parametern -OutputArchivePath .The cmdlet can also create the package locally by using the -OutputArchivePath parameter. Annars publicerar cmdlet. zip-filen till Blob Storage och skyddar den sedan med en SAS-token.Otherwise, the cmdlet publishes the .zip file to blob storage, and then secures it with an SAS token.

Konfigurations skriptet. ps1 som cmdleten skapar finns i. zip-filen i roten i arkivmappen.The .ps1 configuration script that the cmdlet creates is in the .zip file at the root of the archive folder. Mappen module placeras i mappen Arkiv i resurser.The module folder is placed in the archive folder in resources.

Cmdlet : en Set-AzVMDscExtension infogar de inställningar som PowerShell DSC-tillägget kräver i ett konfigurations objekt för virtuell dator.The Set-AzVMDscExtension cmdlet injects the settings that the PowerShell DSC extension requires into a VM configuration object.

Cmdlet: en Get-AzVMDscExtension hämtar DSC-tilläggets status för en angiven virtuell dator.The Get-AzVMDscExtension cmdlet retrieves the DSC extension status of a specific VM.

Cmdlet: en Get-AzVMDscExtensionStatus hämtar STATUSEN för DSC-konfigurationen som hanteras av DSC-tilläggs hanteraren.The Get-AzVMDscExtensionStatus cmdlet retrieves the status of the DSC configuration that's enacted by the DSC extension handler. Den här åtgärden kan utföras på en enskild virtuell dator eller en grupp med virtuella datorer.This action can be performed on a single VM or on a group of VMs.

Cmdlet: en Remove-AzVMDscExtension tar bort tilläggs hanteraren från en angiven virtuell dator.The Remove-AzVMDscExtension cmdlet removes the extension handler from a specific VM. Den här cmdleten tar inte bort konfigurationen, avinstallerar WMF eller ändrar de tillämpade inställningarna på den virtuella datorn.This cmdlet does not remove the configuration, uninstall WMF, or change the applied settings on the VM. Den tar bara bort tilläggs hanteraren.It only removes the extension handler.

Viktig information om cmdlets för DSC-tillägg i Resource Manager:Important information about Resource Manager DSC extension cmdlets:

  • Azure Resource Manager-cmdlet: ar är synkrona.Azure Resource Manager cmdlets are synchronous.
  • Parametrarna ResourceGroupName, VMName, ArchiveStorageAccountName, version och location krävs.The ResourceGroupName, VMName, ArchiveStorageAccountName, Version, and Location parameters are all required.
  • ArchiveResourceGroupName är en valfri parameter.ArchiveResourceGroupName is an optional parameter. Du kan ange den här parametern när ditt lagrings konto tillhör en annan resurs grupp än den där den virtuella datorn skapas.You can specify this parameter when your storage account belongs to a different resource group than the one where the VM is created.
  • Använd den automatiska uppdaterings växeln för att automatiskt uppdatera tilläggs hanteraren till den senaste versionen när den är tillgänglig.Use the AutoUpdate switch to automatically update the extension handler to the latest version when it's available. Den här parametern har möjlighet att starta om den virtuella datorn när en ny version av WMF lanseras.This parameter has the potential to cause restarts on the VM when a new version of WMF is released.

Kom igång med cmdletarGet started with cmdlets

Azure DSC-tillägget kan använda DSC-konfigurationsobjekt för att konfigurera virtuella Azure-datorer direkt under distributionen.The Azure DSC extension can use DSC configuration documents to directly configure Azure VMs during deployment. Det här steget registrerar inte noden som ska automatiseras.This step doesn't register the node to Automation. Noden hanteras inte centralt.The node is not centrally managed.

I följande exempel visas ett enkelt exempel på en konfiguration.The following example shows a simple example of a configuration. Spara konfigurationen lokalt som iisInstall.ps1.Save the configuration locally as iisInstall.ps1.

configuration IISInstall
{
    node "localhost"
    {
        WindowsFeature IIS
        {
            Ensure = "Present"
            Name = "Web-Server"
        }
    }
}

Följande kommandon placerar iisInstall.ps1-skriptet på den angivna virtuella datorn.The following commands place the iisInstall.ps1 script on the specified VM. Kommandona kör också konfigurationen och rapporterar sedan om status.The commands also execute the configuration, and then report back on status.

$resourceGroup = 'dscVmDemo'
$vmName = 'myVM'
$storageName = 'demostorage'
#Publish the configuration script to user storage
Publish-AzVMDscConfiguration -ConfigurationPath .\iisInstall.ps1 -ResourceGroupName $resourceGroup -StorageAccountName $storageName -force
#Set the VM to run the DSC configuration
Set-AzVMDscExtension -Version '2.76' -ResourceGroupName $resourceGroup -VMName $vmName -ArchiveStorageAccountName $storageName -ArchiveBlobName 'iisInstall.ps1.zip' -AutoUpdate -ConfigurationName 'IISInstall'

Azure CLI-distributionAzure CLI deployment

Azure CLI kan användas för att distribuera DSC-tillägget till en befintlig virtuell dator.The Azure CLI can be used to deploy the DSC extension to an existing virtual machine.

För en virtuell dator som kör Windows:For a virtual machine running Windows:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name Microsoft.Powershell.DSC \
  --publisher Microsoft.Powershell \
  --version 2.77 --protected-settings '{}' \
  --settings '{}'

För en virtuell dator som kör Linux:For a virtual machine running Linux:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name DSCForLinux \
  --publisher Microsoft.OSTCExtensions \
  --version 2.7 --protected-settings '{}' \
  --settings '{}'

Azure Portal funktionerAzure portal functionality

Så här konfigurerar du DSC i portalen:To set up DSC in the portal:

  1. Gå till en virtuell dator.Go to a VM.
  2. Under Inställningar väljer du Tillägg.Under Settings, select Extensions.
  3. På den nya sidan som skapas väljer du + Lägg till och väljer sedan PowerShell Desired State Configuration.In the new page that's created, select + Add, and then select PowerShell Desired State Configuration.
  4. Klicka på skapa längst ned på sidan tilläggs information.Click Create at the bottom of the extension information page.

Portalen samlar in följande ingångar:The portal collects the following input:

  • Konfigurations moduler eller skript: det här fältet är obligatoriskt (formuläret har inte uppdaterats för standard konfigurations skriptet).Configuration Modules or Script: This field is mandatory (the form has not been updated for the default configuration script). Konfigurations moduler och-skript kräver en. ps1-fil som har ett konfigurations skript eller en. zip-fil med konfigurations skriptet. ps1 på roten.Configuration modules and scripts require a .ps1 file that has a configuration script or a .zip file with a .ps1 configuration script at the root. Om du använder en. zip-fil måste alla beroende resurser tas med i modulens mappar i. zip-filen.If you use a .zip file, all dependent resources must be included in module folders in the .zip. Du kan skapa. zip-filen med hjälp av cmdleten Publish-AzureVMDscConfiguration-OutputArchivePath som ingår i Azure PowerShell SDK.You can create the .zip file by using the Publish-AzureVMDscConfiguration -OutputArchivePath cmdlet that's included in the Azure PowerShell SDK. Zip-filen överförs till din användar-blob-lagring och skyddas av en SAS-token.The .zip file is uploaded to your user blob storage and secured by an SAS token.

  • Konfiguration av modulens kvalificerade namn: du kan inkludera flera konfigurations funktioner i en. ps1-fil.Module-qualified Name of Configuration: You can include multiple configuration functions in a .ps1 file. Ange namnet på Configuration. ps1-skriptet följt av \ och namnet på konfigurations funktionen.Enter the name of the configuration .ps1 script followed by \ and the name of the configuration function. Om t. ex. ps1-skriptet har namnet configuration.ps1 och konfigurationen är skriptet iisinstall, anger configuration.ps1 \iisinstall.For example, if your .ps1 script has the name configuration.ps1 and the configuration is IisInstall, enter configuration.ps1\IisInstall.

  • Konfigurations argument: om konfigurations funktionen tar argument anger du dem här i formatet argumentName1 = värde1, argumentName2 = värde2.Configuration Arguments: If the configuration function takes arguments, enter them here in the format argumentName1=value1,argumentName2=value2. Det här formatet är ett annat format där konfigurations argument godkänns i PowerShell-cmdletar eller Resource Manager-mallar.This format is a different format in which configuration arguments are accepted in PowerShell cmdlets or Resource Manager templates.

  • PSD1-fil för konfigurations data: om konfigurationen kräver en konfigurations data fil i .psd1 använder du det här fältet för att välja data filen och ladda upp den till blob-lagringen för användare.Configuration Data PSD1 File: If your configuration requires a configuration data file in .psd1, use this field to select the data file and upload it to your user blob storage. Konfigurations data filen skyddas av en SAS-token i Blob Storage.The configuration data file is secured by an SAS token in blob storage.

  • WMF-version: anger den version av Windows Management Framework (WMF) som ska installeras på den virtuella datorn.WMF Version: Specifies the version of Windows Management Framework (WMF) that should be installed on your VM. Om du anger den här egenskapen till senaste installeras den senaste versionen av WMF.Setting this property to latest installs the most recent version of 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.Currently, the only possible values for this property are 4.0, 5.0, 5.1, and latest. Dessa möjliga värden är beroende av uppdateringar.These possible values are subject to updates. Standardvärdet är senaste.The default value is latest.

  • Data insamling: anger om tillägget ska samla in telemetri.Data Collection: Determines if the extension will collect telemetry. Mer information finns i data insamling för Azure DSC-tillägg.For more information, see Azure DSC extension data collection.

  • Version: anger vilken version av DSC-tillägget som ska installeras.Version: Specifies the version of the DSC extension to install. Information om versioner finns i versions historik för DSC-tillägg.For information about versions, see DSC extension version history.

  • Del version för automatisk uppgradering: det här fältet mappar till AutoUpdate -växeln i-cmdletarna och aktiverar tillägget till att uppdateras automatiskt till den senaste versionen under installationen.Auto Upgrade Minor Version: This field maps to the AutoUpdate switch in the cmdlets and enables the extension to automatically update to the latest version during installation. Ja instruerar tilläggs hanteraren att använda den senaste tillgängliga versionen och ingen kommer att tvinga den angivna versionen att installeras.Yes will instruct the extension handler to use the latest available version and No will force the Version specified to be installed. Att välja nej eller Nej är inte detsamma som att välja Nej.Selecting neither Yes nor No is the same as selecting No.

LoggarLogs

Loggar för tillägget lagras på följande plats: C:\WindowsAzure\Logs\Plugins\Microsoft.Powershell.DSC\<version number>Logs for the extension are stored in the following location: C:\WindowsAzure\Logs\Plugins\Microsoft.Powershell.DSC\<version number>

Nästa stegNext steps