Desired State Configuration rozšíření pomocí šablon Azure Resource Manager

Článek
06/01/2023

Poznámka

Než povolíte rozšíření DSC, chtěli bychom, abyste věděli, že novější verze DSC je teď obecně dostupná a spravuje ji funkce Azure Automange s názvem Konfigurace počítače. Funkce konfigurace počítače kombinuje funkce obslužné rutiny rozšíření Desired State Configuration (DSC), Azure Automation State Configuration a nejčastěji požadované funkce ze zpětné vazby od zákazníků. Konfigurace počítače zahrnuje také podporu hybridních počítačů prostřednictvím serverů s podporou Arc.

Tento článek popisuje šablonu Azure Resource Manager pro obslužnou rutinu rozšíření Desired State Configuration (DSC). Mnoho příkladů používá RegistrationURL (zadaný jako Řetězec) a RegistrationKey (poskytnutý jako PSCredential pro onboarding s Azure Automation. Podrobnosti o získání těchto hodnot najdete v tématu Použití metakonfigurace DSC k registraci hybridních počítačů.

Poznámka

Můžete se setkat s mírně odlišnými příklady schématu. Ke změně schématu došlo ve verzi z října 2016. Podrobnosti najdete v tématu Aktualizace z předchozího formátu.

Příklad šablony pro virtuální počítač s Windows

Následující fragment kódu je v šabloně v části Prostředek . Rozšíření DSC dědí výchozí vlastnosti rozšíření. Další informace najdete v tématu VirtualMachineExtension – třída.

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

Příklad šablony pro škálovací sady virtuálních počítačů s Windows

Uzel škálovací sady virtuálních počítačů má oddíl vlastností , který má atribut VirtualMachineProfile, extensionProfile . V části rozšíření přidejte podrobnosti o rozšíření DSC.

Rozšíření DSC dědí výchozí vlastnosti rozšíření. Další informace najdete v tématu VirtualMachineScaleSetExtension – třída.

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

Podrobné informace o nastavení

V části nastavení rozšíření Azure DSC v šabloně Resource Manager použijte následující schéma.

Seznam argumentů, které jsou k dispozici pro výchozí konfigurační skript, najdete v tématu Výchozí konfigurační skript.

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

Podrobnosti

Název vlastnosti	Typ	Popis
settings.wmfVersion	řetězec	Určuje verzi Windows Management Framework (WMF), která má být na virtuálním počítači nainstalovaná. Nastavení této vlastnosti na nejnovější nainstaluje nejnovější verzi WMF. V současné době jsou pro tuto vlastnost dostupné pouze hodnoty 4.0, 5.0, 5.1 a nejnovější. Tyto možné hodnoty se mohou aktualizovat. Výchozí hodnota je nejnovější.
settings.configuration.url	řetězec	Určuje umístění adresy URL, ze kterého chcete stáhnout konfigurační .zip soubor DSC. Pokud zadaná adresa URL vyžaduje pro přístup token SAS, nastavte vlastnost protectedSettings.configurationUrlSasToken na hodnotu vašeho tokenu SAS. Tato vlastnost je vyžadována, pokud jsou definovány settings.configuration.script nebo settings.configuration.function . Pokud pro tyto vlastnosti není zadána žádná hodnota, rozšíření zavolá výchozí konfigurační skript pro nastavení metadat location Configuration Manager (LCM) a měly by být zadány argumenty.
settings.configuration.script	řetězec	Určuje název souboru skriptu, který obsahuje definici konfigurace DSC. Tento skript musí být v kořenové složce souboru .zip, který je stažen z adresy URL určené vlastností settings.configuration.url . Tato vlastnost je vyžadována, pokud jsou definovány settings.configuration.url nebo settings.configuration.script . Pokud pro tyto vlastnosti není zadána žádná hodnota, rozšíření volá výchozí konfigurační skript pro nastavení metadat LCM a měly by být zadány argumenty.
settings.configuration.function	řetězec	Určuje název konfigurace DSC. Konfigurace s názvem musí být zahrnuta ve skriptu, který definuje settings.configuration.script . Tato vlastnost je vyžadována, pokud jsou definovány settings.configuration.url nebo settings.configuration.function . Pokud pro tyto vlastnosti není zadána žádná hodnota, rozšíření volá výchozí konfigurační skript pro nastavení metadat LCM a měly by být zadány argumenty.
settings.configurationArguments	Kolekce	Definuje všechny parametry, které chcete předat konfiguraci DSC. Tato vlastnost není šifrovaná.
settings.configurationData.url	řetězec	Určuje adresu URL, ze které se má stáhnout soubor konfiguračních dat (.psd1), který se použije jako vstup pro konfiguraci DSC. Pokud zadaná adresa URL vyžaduje pro přístup token SAS, nastavte vlastnost protectedSettings.configurationDataUrlSasToken na hodnotu tokenu SAS.
settings.privacy.dataCollection	řetězec	Povolí nebo zakáže shromažďování telemetrických dat. Jediné možné hodnoty pro tuto vlastnost jsou Enable, Disable, '' nebo $null. Pokud tuto vlastnost ponecháte prázdnou nebo nulovou, povolí se telemetrie. Výchozí hodnota je ''. Další informace najdete v tématu Shromažďování dat rozšíření Azure DSC.
settings.advancedOptions.downloadMappings	Kolekce	Definuje alternativní umístění, ze kterých se má stáhnout WMF. Další informace najdete v tématu Rozšíření Azure DSC 2.8 a postup mapování stahování závislostí rozšíření na vlastní umístění.
protectedSettings.configurationArguments	Kolekce	Definuje všechny parametry, které chcete předat konfiguraci DSC. Tato vlastnost je šifrovaná.
protectedSettings.configurationUrlSasToken	řetězec	Určuje token SAS, který se má použít pro přístup k adrese URL, kterou definuje settings.configuration.url . Tato vlastnost je šifrovaná.
protectedSettings.configurationDataUrlSasToken	řetězec	Určuje token SAS, který se má použít pro přístup k adrese URL, kterou definuje settings.configurationData.url . Tato vlastnost je šifrovaná.

Výchozí konfigurační skript

Další informace o následujících hodnotách najdete v tématu Místní Configuration Manager základní nastavení. Pomocí výchozího konfiguračního skriptu rozšíření DSC můžete nakonfigurovat pouze vlastnosti LCM uvedené v následující tabulce.

Název vlastnosti	Typ	Popis
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Požadovaná vlastnost. Určuje klíč, který se používá pro uzel k registraci ve službě Azure Automation jako heslo objektu přihlašovacích údajů PowerShellu. Tuto hodnotu je možné automaticky zjistit pomocí metody listkeys pro účet Automation. Podívejte se na příklad.
settings.configurationArguments.RegistrationUrl	řetězec	Požadovaná vlastnost. Určuje adresu URL koncového bodu Automation, kde se uzel pokusí zaregistrovat. Tuto hodnotu je možné automaticky zjistit pomocí referenční metody pro účet Automation.
settings.configurationArguments.NodeConfigurationName	řetězec	Požadovaná vlastnost. Určuje konfiguraci uzlu v účtu Automation, která se má uzlu přiřadit.
settings.configurationArguments.ConfigurationMode	řetězec	Určuje režim pro LCM. Mezi platné možnosti patří ApplyOnly, ApplyandMonitor a ApplyandAutoCorrect. Výchozí hodnota je ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	Uint32	Určuje, jak často se LCM pokusí zkontrolovat aktualizace pomocí účtu Automation. Výchozí hodnota je 30. Minimální hodnota je 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	Uint32	Určuje, jak často LCM ověřuje aktuální konfiguraci. Výchozí hodnota je 15. Minimální hodnota je 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Určuje, jestli je možné uzel automaticky restartovat, pokud to vyžaduje operace DSC. Výchozí hodnota je false.
settings.configurationArguments.ActionAfterReboot	řetězec	Určuje, co se stane po restartování při použití konfigurace. Platné možnosti jsou ContinueConfiguration a StopConfiguration. Výchozí hodnota je ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Určuje, jestli LCM přepíše existující moduly na uzlu. Výchozí hodnota je false.

nastavení vs. protectedSettings

Všechna nastavení se uloží do textového souboru nastavení na virtuálním počítači. Vlastnosti uvedené v nastavení jsou veřejné vlastnosti. Veřejné vlastnosti nejsou v textovém souboru nastavení šifrované. Vlastnosti uvedené v části protectedSettings se šifrují pomocí certifikátu a v souboru nastavení na virtuálním počítači se nezobrazují ve formátu prostého textu.

Pokud konfigurace vyžaduje přihlašovací údaje, můžete je zahrnout do složky protectedSettings:

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

Ukázkový konfigurační skript

Následující příklad ukazuje výchozí chování rozšíření DSC, kterým je poskytnutí nastavení metadat do LCM a registrace ve službě Automation DSC. Argumenty konfigurace jsou povinné. Argumenty konfigurace se předávají výchozímu konfiguračnímu skriptu pro nastavení metadat LCM.

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

Příklad použití konfiguračního skriptu ve službě Azure Storage

Následující příklad je z přehledu obslužné rutiny rozšíření DSC. V tomto příkladu se k nasazení rozšíření místo rutin používají šablony Resource Manager. Uložte konfiguraci IisInstall.ps1, umístěte ji do souboru .zip (příklad: iisinstall.zip) a pak soubor nahrajte na přístupnou adresu URL. Tento příklad používá službu Azure Blob Storage, ale .zip soubory si můžete stáhnout z libovolného umístění.

V šabloně Resource Manager následující kód dává virtuálnímu počítači pokyn, aby si stáhl správný soubor a pak spustil příslušnou funkci PowerShellu:

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

Příklad použití odkazovaných hodnot registrace Azure Automation

Následující příklad získá RegistrationUrl a RegistrationKey odkazováním na vlastnosti účtu Azure Automation a použitím metody listkeys k načtení primárního klíče (0). V tomto příkladu byly šabloně poskytnuty parametry automationAccountName a NodeConfigName .

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

Aktualizace z předchozího formátu

Všechna nastavení v předchozím formátu rozšíření (a která mají veřejné vlastnosti ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken nebo Properties) se automaticky přizpůsobí aktuálnímu formátu rozšíření. Běží stejně jako předtím.

Následující schéma ukazuje, jak vypadalo předchozí schéma nastavení:

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

Předchozí formát se přizpůsobí aktuálnímu formátu:

Název aktuální vlastnosti	Ekvivalent předchozího schématu
settings.wmfVersion	Nastavení. Verze WMF
settings.configuration.url	Nastavení. ModulesUrl
settings.configuration.script	První část nastavení. ConfigurationFunction (před \\)
settings.configuration.function	Druhá část nastavení. ConfigurationFunction (za \\)
settings.configuration.module.name	Nastavení. Zdroj modulu
settings.configuration.module.version	Nastavení. Verze modulu
settings.configurationArguments	Nastavení. Vlastnosti
settings.configurationData.url	protectedSettings.DataBlobUri (bez tokenu SAS)
settings.privacy.dataCollection	Nastavení. Privacy.dataCollection
settings.advancedOptions.downloadMappings	Nastavení. AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	Nastavení. SasToken
protectedSettings.configurationDataUrlSasToken	Token SAS z protectedSettings.DataBlobUri

Řešení potíží

Tady jsou některé chyby, na které můžete narazit, a jak je můžete opravit.

Neplatné hodnoty

"Privacy.dataCollection is '{0}'. Jediné možné hodnoty jsou , "Povolit" a "Disable". WmfVersion je .{0} Pouze možné hodnoty jsou ... a "nejnovější".

Problém: Zadaná hodnota není povolená.

Řešení: Změňte neplatnou hodnotu na platnou hodnotu. Další informace najdete v tabulce v části Podrobnosti.

Neplatná adresa URL

"ConfigurationData.url is '{0}'. Toto není platná adresa URL" "DataBlobUri je '{0}'. Toto není platná adresa URL" "Configuration.url is '{0}'. Toto není platná adresa URL.

Problém: Zadaná adresa URL není platná.

Řešení: Zkontrolujte všechny zadané adresy URL. Ujistěte se, že se všechny adresy URL přeloží na platná umístění, ke kterým má rozšíření přístup na vzdáleném počítači.

Neplatný typ RegistrationKey

Neplatný typ parametru RegistrationKey typu PSCredential

Problém: Hodnotu RegistrationKey v protectedSettings.configurationArguments nelze zadat jako jiný typ než PSCredential.

Řešení: Změňte položku protectedSettings.configurationArguments pro RegistrationKey na typ PSCredential v následujícím formátu:

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

Neplatný typ ConfigurationArgument

Neplatný typ {0}configurationArguments

Problém: Vlastnost ConfigurationArguments se nedá přeložit na objekt tabulky hash .

Řešení: Nastavte vlastnost ConfigurationArguments na tabulku hash. Postupujte podle formátu uvedeného v předchozích příkladech. Dávejte pozor na uvozovky, čárky a složené závorky.

Duplicitní konfiguraceArguments

"Nalezeny duplicitní argumenty '{0} ve veřejné i chráněné konfiguraciArguments"

Problém: ConfigurationArguments ve veřejném nastavení a ConfigurationArguments v chráněném nastavení mají vlastnosti se stejným názvem.

Řešení: Odeberte jednu z duplicitních vlastností.

Chybějící vlastnosti

"nastavení. Configuration.function vyžaduje, aby byla zadána adresa settings.configuration.url nebo settings.configuration.module.

"nastavení. Adresa Configuration.url vyžaduje zadání settings.configuration.script.

"nastavení. Configuration.script vyžaduje, aby byla zadána adresa settings.configuration.url.

"nastavení. Adresa Configuration.url vyžaduje, aby byla zadána funkce settings.configuration.function.

protectedSettings.ConfigurationUrlSasToken vyžaduje, aby byla zadána adresa settings.configuration.url.

protectedSettings.ConfigurationDataUrlSasToken vyžaduje zadání settings.configurationData.url

Problém: Definovaná vlastnost potřebuje jinou vlastnost, která chybí.

Řešení:

Zadejte chybějící vlastnost.
Odeberte vlastnost, která potřebuje chybějící vlastnost.

Další kroky

Přečtěte si o používání škálovacích sad virtuálních počítačů s rozšířením Azure DSC.
Přečtěte si další podrobnosti o zabezpečené správě přihlašovacích údajů DSC.
Seznamte se s obslužnou rutinou rozšíření Azure DSC.
Další informace o PowerShell DSC najdete v centru dokumentace k PowerShellu.

Sdílet prostřednictvím