Rozšíření Desired State Configuration pomocí šablon Azure Resource Manageru

Článek
08/25/2024

Poznámka:

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

Tento článek popisuje šablonu Azure Resource Manageru pro obslužnou rutinu rozšíření DSC (Desired State Configuration). V mnoha příkladech se k onboardingu se službou Azure Automation používá RegistrationURL (poskytovaný jako řetězec) a RegistrationKey (zadaný jako PSCredential ). 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 narazit na mírně odlišné příklady schématu. Ve verzi z října 2016 došlo ke změně schématu. 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 uvedený v části Prostředek šablony. Rozšíření DSC dědí výchozí vlastnosti rozšíření. Další informace naleznete 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í s atributem 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 naleznete 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 Manageru použijte následující schéma.

Seznam argumentů dostupných pro výchozí konfigurační skript naleznete 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"
}

Detaily

Název vlastnosti	Type	Popis
settings.wmfVersion	string	Určuje verzi rozhraní WMF (Windows Management Framework), která by se měla na virtuálním počítači nainstalovat. Nastavením této vlastnosti na nejnovější nainstaluje nejnovější verzi WMF. V současné době jsou jedinými možnými hodnotami pro tuto vlastnost 4.0, 5.0, 5.1 a nejnovější. Tyto možné hodnoty podléhají aktualizacím. Výchozí hodnota je nejnovější.
settings.configuration.url	string	Určuje umístění adresy URL, ze kterého se má stáhnout konfigurační .zip soubor DSC. Pokud zadaná adresa URL vyžaduje token SAS pro přístup, nastavte vlastnost protectedSettings.configurationUrlSasToken na hodnotu vašeho tokenu SAS. Tato vlastnost se vyžaduje, pokud jsou definovány settings.configuration.script nebo settings.configuration.function . Pokud pro tyto vlastnosti není zadána žádná hodnota, rozšíření volá výchozí konfigurační skript pro nastavení metadat nástroje Location Configuration Manager (LCM) a měly by být zadány argumenty.
settings.configuration.script	string	Určuje název souboru skriptu, který obsahuje definici konfigurace DSC. Tento skript musí být v kořenové složce souboru .zip staženého z adresy URL určené vlastností settings.configuration.url . Tato vlastnost se vyžaduje, 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	string	Určuje název konfigurace DSC. Název konfigurace musí být součástí skriptu, který definuje settings.configuration.script . Tato vlastnost se vyžaduje, 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	string	Určuje adresu URL, ze které chcete stáhnout soubor konfiguračních dat (.psd1), který se má použít jako vstup pro konfiguraci DSC. Pokud zadaná adresa URL vyžaduje token SAS pro přístup, nastavte vlastnost protectedSettings.configurationDataUrlSasToken na hodnotu vašeho tokenu SAS.
settings.privacy.dataCollection	string	Povolí nebo zakáže shromažďování telemetrie. Jediné možné hodnoty pro tuto vlastnost jsou Enable, Disable, '' nebo $null. Ponechání této vlastnosti prázdné nebo null povolí telemetrii. 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 o rozšíření Azure DSC 2.8 a o tom, jak mapovat 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 zašifrovaná.
protectedSettings.configurationUrlSasToken	string	Určuje token SAS, který se má použít pro přístup k adrese URL, kterou definuje settings.configuration.url . Tato vlastnost je zašifrovaná.
protectedSettings.configurationDataUrlSasToken	string	Určuje token SAS, který se má použít pro přístup k adrese URL, kterou definuje settings.configurationData.url . Tato vlastnost je zašifrovaná.

Výchozí konfigurační skript

Další informace o následujících hodnotách naleznete v tématu Základní nastavení nástroje Local Configuration Manager. Výchozí konfigurační skript rozšíření DSC můžete použít ke konfiguraci pouze vlastností LCM uvedených v následující tabulce.

Název vlastnosti	Type	Popis
protectedSettings.configurationArguments.RegistrationKey	PsCredential	Povinná 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 lze automaticky zjistit pomocí metody listkeys vůči účtu Automation. Podívejte se na příklad.
settings.configurationArguments.RegistrationUrl	string	Povinná vlastnost. Určuje adresu URL koncového bodu automation, kde se uzel pokusí zaregistrovat. Tuto hodnotu lze automaticky zjistit pomocí referenční metody pro účet Automation.
settings.configurationArguments.NodeConfigurationName	string	Povinná vlastnost. Určuje konfiguraci uzlu v účtu Automation, která se má k uzlu přiřadit.
settings.configurationArguments.ConfigurationMode	string	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 u účtu Automation aktualizace. 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 se uzel dá automaticky restartovat, pokud ji operace DSC požádá. Výchozí hodnotou je false.
settings.configurationArguments.ActionAfterReboot	string	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 v uzlu. Výchozí hodnotou je false.

nastavení vs. protectedSettings

Všechna nastavení se ukládají 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 přihlašovací údaje zahrnout do 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é poskytuje nastavení metadat pro LCM a registraci 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í používají šablony Resource Manageru místo rutin. Uložte konfiguraci IisInstall.ps1, umístěte ji do souboru .zip (příklad: iisinstall.zip) a pak soubor nahrajte do přístupné adresy URL. Tento příklad používá službu Azure Blob Storage, ale můžete stáhnout .zip soubory z libovolného umístění.

V šabloně Resource Manageru následující kód dá virtuálnímu počítači pokyn ke stažení správného souboru a spuštění příslušné funkce 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 služby Azure Automation

Následující příklad získá RegistrationUrl a RegistrationKey odkazem na vlastnosti účtu Azure Automation a pomocí metody listkeys načíst primární klíč (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"
}

Tady je postup, jak se předchozí formát přizpůsobí aktuálnímu formátu:

Název aktuální vlastnosti	Předchozí ekvivalent schématu
settings.wmfVersion	nastavení. WMFVersion
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í. ModuleSource
settings.configuration.module.version	nastavení. ModuleVersion
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í problému

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

Neplatné hodnoty

"Privacy.dataCollection je '{0}'. Jedinými možnými hodnotami jsou '', 'Enable' a 'Disable'. "WmfVersion je '{0}'. Pouze možné hodnoty jsou ... a "latest".

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

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

Neplatná adresa URL

"ConfigurationData.url je '{0}'. Toto není platná adresa URL DataBlobUri je .{0} Toto není platná adresa URL " Configuration.url je '{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 pomocí následujícího formátu:

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

Neplatný typ ConfigurationArgument

"Neplatný typ {0}configurationArguments"

Problém: Vlastnost ConfigurationArguments nemůže 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. Sledujte uvozovky, čárky a složené závorky.

Duplicitní konfigurační archivy

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

Problém: ConfigurationArguments ve veřejných nastaveních a ConfigurationArguments v chráněných nastaveních 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 bylo zadáno nastavení.configuration.url nebo settings.configuration.module.

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

"nastavení. Configuration.script vyžaduje, aby bylo zadáno nastavení.configuration.url.

"nastavení. Configuration.url vyžaduje, aby bylo zadáno nastavení.configuration.function.

"protectedSettings.ConfigurationUrlSasToken vyžaduje, aby bylo zadáno nastavení.configuration.url"

"protectedSettings.ConfigurationDataUrlSasToken vyžaduje, aby bylo zadáno nastavení.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

Seznamte se s používáním škálovacích sad virtuálních počítačů s rozšířením Azure DSC.
Další podrobnosti o zabezpečené správě přihlašovacích údajů DSC
Získejte úvod do obslužné rutiny rozšíření Azure DSC.
Další informace o PowerShell DSC najdete v centru dokumentace k PowerShellu.

Sdílet prostřednictvím