Desired State Configuration bővítmény Azure Resource Manager-sablonokkal

Cikk
06/01/2023

Megjegyzés

A DSC-bővítmény engedélyezése előtt szeretnénk tudni, hogy a DSC egy újabb verziója már általánosan elérhető, amelyet az Azure Automange nevű gépkonfiguráció egyik funkciója felügyel. A gépkonfigurációs funkció egyesíti a Desired State Configuration (DSC) bővítménykezelőjének funkcióit, a Azure Automation State Configuration és a leggyakrabban kért funkciókat az ügyfelek visszajelzései alapján. A gépkonfiguráció a hibrid gépek Arc-kompatibilis kiszolgálókon keresztüli támogatását is magában foglalja.

Ez a cikk a Desired State Configuration (DSC) bővítménykezelőjének Azure Resource Manager sablonját ismerteti. Számos példa a RegistrationURL (sztringként megadva) és RegistrationKey (PSCredentialként) használatával készíti elő a Azure Automation. Az értékek beszerzésével kapcsolatos részletekért lásd: DSC-metakonfigurálás használata hibrid gépek regisztrálásához.

Megjegyzés

Előfordulhat, hogy kissé eltérő sémabeli példákat tapasztal. A séma módosítása a 2016. októberi kiadásban történt. Részletekért lásd: Frissítés egy korábbi formátumból.

Példa sablon egy Windows rendszerű virtuális gépre

Az alábbi kódrészlet a sablon Erőforrás szakaszában található. A DSC-bővítmény örökli az alapértelmezett bővítménytulajdonságokat. További információ: VirtualMachineExtension osztály.

{
  "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éldasablon Windows rendszerű virtuálisgép-méretezési csoportokhoz

A virtuálisgép-méretezési csoport csomópontja rendelkezik egy virtualMachineProfile, extensionProfile attribútummal rendelkező tulajdonságokat tartalmazó szakaszsal. A Bővítmények területen adja meg a DSC-bővítmény részleteit.

A DSC-bővítmény örökli az alapértelmezett bővítménytulajdonságokat. További információ: VirtualMachineScaleSetExtension osztály.

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

Részletes beállítások

Használja az alábbi sémát az Azure DSC-bővítmény beállítások szakaszában egy Resource Manager sablonban.

Az alapértelmezett konfigurációs szkripthez elérhető argumentumok listáját lásd: Alapértelmezett konfigurációs szkript.

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

Részletek

Tulajdonság neve	Típus	Description
settings.wmfVersion	sztring	Megadja a virtuális gépre telepíteni kívánt Windows Management Framework (WMF) verzióját. Ha ezt a tulajdonságot a legújabbra állítja, a WMF legújabb verzióját telepíti. Jelenleg ennek a tulajdonságnak az egyetlen lehetséges értéke a 4.0, 5.0, 5.1 és újabb. Ezekre a lehetséges értékekre frissítések vonatkoznak. Az alapértelmezett érték a legújabb.
settings.configuration.url	sztring	Megadja azt az URL-címet, ahonnan le szeretné tölteni a DSC-konfigurációs .zip fájlt. Ha a megadott URL-címhez SAS-jogkivonat szükséges a hozzáféréshez, állítsa a protectedSettings.configurationUrlSasToken tulajdonságot az SAS-jogkivonat értékére. Ez a tulajdonság akkor szükséges, ha a settings.configuration.script vagy a settings.configuration.function definiálva van. Ha ezekhez a tulajdonságokhoz nincs megadva érték, a bővítmény meghívja az alapértelmezett konfigurációs szkriptet a Hely Configuration Manager (LCM) metaadatainak beállításához, és argumentumokat kell megadni.
settings.configuration.script	sztring	Megadja annak a szkriptnek a fájlnevét, amely a DSC-konfiguráció definícióját tartalmazza. Ennek a szkriptnek a settings.configuration.url tulajdonság által megadott URL-címről letöltött .zip fájl gyökérmappájában kell lennie. Ez a tulajdonság akkor szükséges, ha a settings.configuration.url vagy a settings.configuration.script definiálva van. Ha ezekhez a tulajdonságokhoz nincs megadva érték, a bővítmény meghívja az alapértelmezett konfigurációs szkriptet az LCM-metaadatok beállításához, és meg kell adni az argumentumokat.
settings.configuration.function	sztring	Megadja a DSC-konfiguráció nevét. A névvel ellátott konfigurációnak szerepelnie kell a settings.configuration.script által definiált szkriptben. Ez a tulajdonság akkor szükséges, ha a settings.configuration.url vagy settings.configuration.function meg van határozva. Ha ezekhez a tulajdonságokhoz nincs megadva érték, a bővítmény meghívja az alapértelmezett konfigurációs szkriptet az LCM-metaadatok beállításához, és meg kell adni az argumentumokat.
settings.configurationArguments	Gyűjtemény	Meghatározza azokat a paramétereket, amelyeket át szeretne adni a DSC-konfigurációnak. Ez a tulajdonság nincs titkosítva.
settings.configurationData.url	sztring	Megadja azt az URL-címet, amelyről a DSC-konfiguráció bemeneteként használni kívánt konfigurációs adatfájlt (.psd1) le szeretné tölteni. Ha a megadott URL-címhez SAS-jogkivonat szükséges a hozzáféréshez, állítsa a protectedSettings.configurationDataUrlSasToken tulajdonságot az SAS-jogkivonat értékére.
settings.privacy.dataCollection	sztring	Engedélyezi vagy letiltja a telemetriai gyűjteményt. Ennek a tulajdonságnak az egyetlen lehetséges értéke az Engedélyezés, a Letiltás, a "" vagy a $null. Ha ezt a tulajdonságot üresen vagy null értékként hagyja, lehetővé teszi a telemetriai adatokat. Az alapértelmezett érték a "". További információ: Azure DSC-bővítmény adatgyűjtése.
settings.advancedOptions.downloadMappings	Gyűjtemény	Meghatározza azokat a másodlagos helyeket, ahonnan le szeretné tölteni a WMF-et. További információ: Azure DSC extension 2.8 és a bővítményfüggőségek letöltéseinek leképezése a saját helyére.
protectedSettings.configurationArguments	Gyűjtemény	Meghatározza azokat a paramétereket, amelyeket át szeretne adni a DSC-konfigurációnak. Ez a tulajdonság titkosítva van.
protectedSettings.configurationUrlSasToken	sztring	Megadja a settings.configuration.url által definiált URL-cím eléréséhez használandó SAS-jogkivonatot. Ez a tulajdonság titkosítva van.
protectedSettings.configurationDataUrlSasToken	sztring	Megadja a settings.configurationData.url által definiált URL-cím eléréséhez használandó SAS-jogkivonatot. Ez a tulajdonság titkosítva van.

Alapértelmezett konfigurációs szkript

Az alábbi értékekkel kapcsolatos további információkért lásd: Helyi Configuration Manager alapszintű beállítások. A DSC-bővítmény alapértelmezett konfigurációs szkriptjével csak az alábbi táblázatban felsorolt LCM-tulajdonságokat konfigurálhatja.

Tulajdonság neve	Típus	Description
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Kötelező tulajdonság. Megadja azt a kulcsot, amelyet egy csomópont a Azure Automation szolgáltatásban való regisztrációhoz használ egy PowerShell-hitelesítőadat-objektum jelszavaként. Ez az érték automatikusan felderíthető a listkeys metódussal az Automation-fiókban. Lásd a példát.
settings.configurationArguments.RegistrationUrl	sztring	Kötelező tulajdonság. Annak az Automation-végpontnak az URL-címét adja meg, ahol a csomópont regisztrálni próbál. Ez az érték automatikusan felderíthető az Automation-fiók referenciametódusának használatával.
settings.configurationArguments.NodeConfigurationName	sztring	Kötelező tulajdonság. Az Automation-fiók csomópontkonfigurációját adja meg a csomóponthoz való hozzárendeléshez.
settings.configurationArguments.ConfigurationMode	sztring	Meghatározza az LCM módját. Az érvényes beállítások közé tartozik az ApplyOnly, az ApplyandMonitor és az ApplyandAutoCorrect. Az alapértelmezett érték az ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Meghatározza, hogy az LCM milyen gyakran kísérel meg frissítéseket keresni az Automation-fiókkal. Az alapértelmezett érték 30. A minimális érték 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Meghatározza, hogy az LCM milyen gyakran ellenőrzi az aktuális konfigurációt. Az alapértelmezett érték 15. A minimális érték 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Meghatározza, hogy egy csomópont automatikusan újraindítható-e, ha egy DSC-művelet kéri. Az alapértelmezett érték hamis.
settings.configurationArguments.ActionAfterReboot	sztring	Megadja, hogy mi történik az újraindítás után a konfiguráció alkalmazásakor. Az érvényes beállítások a ContinueConfiguration és a StopConfiguration. Az alapértelmezett érték a ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Meghatározza, hogy az LCM felülírja-e a csomóponton lévő meglévő modulokat. Az alapértelmezett érték hamis.

beállítások és protectedSettings

Az összes beállítás a virtuális gépen található beállítások szövegfájljában lesz mentve. A beállítások között felsorolt tulajdonságok nyilvános tulajdonságok. A nyilvános tulajdonságok nincsenek titkosítva a beállítások szövegfájljában. A protectedSettings alatt felsorolt tulajdonságok tanúsítványokkal vannak titkosítva, és nem jelennek meg egyszerű szövegben a virtuális gép beállításfájljában.

Ha a konfigurációnak hitelesítő adatokra van szüksége, a hitelesítő adatokat a protectedSettings fájlba is felveheti:

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

Példakonfigurációs szkriptre

Az alábbi példa a DSC-bővítmény alapértelmezett viselkedését mutatja be, amely metaadat-beállításokat ad meg az LCM-nek, és regisztrál az Automation DSC szolgáltatásban. Konfigurációs argumentumokra van szükség. A konfigurációs argumentumokat a rendszer átadja az alapértelmezett konfigurációs szkriptnek az LCM-metaadatok beállításához.

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

Példa a konfigurációs szkript használatával az Azure Storage-ban

Az alábbi példa a DSC bővítménykezelő áttekintéséből származik. Ez a példa parancsmagok helyett Resource Manager sablonokat használ a bővítmény üzembe helyezéséhez. Mentse a IisInstall.ps1 konfigurációt, helyezze egy .zip fájlba (például: iisinstall.zip), majd töltse fel a fájlt egy akadálymentes URL-címre. Ez a példa az Azure Blob Storage-t használja, de tetszőleges helyről letöltheti .zip fájlokat.

A Resource Manager sablonban a következő kód utasítja a virtuális gépet, hogy töltse le a megfelelő fájlt, majd futtassa a megfelelő PowerShell-függvényt:

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

Példa hivatkozott Azure Automation regisztrációs értékek használatával

Az alábbi példa lekéri a RegistrationUrl és a RegistrationKey értéket a Azure Automation fióktulajdonságokra hivatkozva, és a listkeys metódussal kéri le az elsődleges kulcsot (0). Ebben a példában az automationAccountName és a NodeConfigName paramétereket adták meg a sablonnak.

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

Frissítés egy korábbi formátumból

A bővítmény korábbi formátumú beállításai (és amelyek a ModulesUrl, a ModuleSource, a ModuleVersion, a ConfigurationFunction, a SasToken vagy a Properties nyilvános tulajdonsággal rendelkeznek) automatikusan igazodnak a bővítmény aktuális formátumához. Ugyanúgy futnak, mint korábban.

Az alábbi séma azt mutatja be, hogy néz ki az előző beállításséma:

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

Az előző formátum a következőképpen igazodik az aktuális formátumhoz:

Aktuális tulajdonságnév	Korábbi sémaegyenérték
settings.wmfVersion	Beállítások. WMFVersion
settings.configuration.url	Beállítások. ModulesUrl
settings.configuration.script	A beállítások első része. ConfigurationFunction (előtt \\)
settings.configuration.function	A beállítások második része. ConfigurationFunction (a \\) után
settings.configuration.module.name	Beállítások. ModuleSource
settings.configuration.module.version	Beállítások. ModuleVersion
settings.configurationArguments	Beállítások. Tulajdonságok
settings.configurationData.url	protectedSettings.DataBlobUri (SAS-jogkivonat nélkül)
settings.privacy.dataCollection	Beállítások. Privacy.dataCollection
settings.advancedOptions.downloadMappings	Beállítások. AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	Beállítások. SasToken
protectedSettings.configurationDataUrlSasToken	SAS-jogkivonat a protectedSettings.DataBlobUri szolgáltatásból

Hibaelhárítás

Íme néhány hiba, amelybe belefuthat, és hogyan háríthatja el őket.

Érvénytelen értékek

"Privacy.dataCollection a ""{0}. Az egyetlen lehetséges érték az "", az "Engedélyezés" és a "Letiltás". "A WmfVersion a ""{0}. Csak a lehetséges értékek... és a "legújabb".

Probléma: A megadott érték nem engedélyezett.

Megoldás: Módosítsa az érvénytelen értéket érvényes értékre. További információért tekintse meg a részleteket tartalmazó táblázatot.

Érvénytelen URL-cím

"ConfigurationData.url: ""{0}. Ez nem érvényes URL-cím: "A DataBlobUri értéke ""{0}. Ez nem érvényes URL-cím" "Configuration.url is '"{0}. Ez nem érvényes URL-cím"

Probléma: A megadott URL-cím érvénytelen.

Megoldás: Ellenőrizze az összes megadott URL-címet. Győződjön meg arról, hogy minden URL-cím olyan érvényes helyre van feloldva, amelyhez a bővítmény hozzáférhet a távoli gépen.

Érvénytelen RegistrationKey-típus

"Érvénytelen típus a PSCredential típusú RegistrationKey paraméterhez."

Probléma: A protectedSettings.configurationArguments registrationKey értéke nem adható meg más típusként, mint PSCredential.

Megoldás: Módosítsa a RegistrationKey protectedSettings.configurationArguments bejegyzését PSCredential típusra a következő formátumban:

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

Érvénytelen ConfigurationArgument-típus

"Érvénytelen configurationArguments típus {0}"

Probléma: A ConfigurationArguments tulajdonság nem oldható fel kivonattábla-objektumra .

Megoldás: Tegye a ConfigurationArguments tulajdonságot kivonattáblává. Kövesse az előző példákban megadott formátumot. Nézze meg az idézőjeleket, a vesszőket és a kapcsos zárójeleket.

ConfigurationArguments duplikálása

"Duplikált argumentumokat talált a{0} nyilvános és a védett configurationArguments elemben is"

Probléma: A nyilvános beállításokBan a ConfigurationArguments és a Védett beállításokban a ConfigurationArguments tulajdonság ugyanazzal a névvel rendelkezik.

Megoldás: Távolítsa el az egyik duplikált tulajdonságot.

Hiányzó tulajdonságok

"beállítások. A Configuration.function megköveteli, hogy a settings.configuration.url vagy settings.configuration.module paraméter meg legyen adva"

"beállítások. A Configuration.url használatához meg kell adni a settings.configuration.script parancsprogramot"

"beállítások. A Configuration.script használatához meg kell adni a settings.configuration.url címet"

"beállítások. A Configuration.url használatához meg kell adni a settings.configuration.function függvényt"

"protectedSettings.ConfigurationUrlSasToken megköveteli, hogy a settings.configuration.url meg legyen adva"

"protectedSettings.ConfigurationDataUrlSasToken megköveteli a settings.configurationData.url megadását"

Probléma: Egy definiált tulajdonságnak szüksége van egy másik tulajdonságra, amely hiányzik.

Megoldások:

Adja meg a hiányzó tulajdonságot.
Távolítsa el a hiányzó tulajdonságot igénylő tulajdonságot.

Következő lépések

Ismerje meg, hogyan használhat virtuálisgép-méretezési csoportokat az Azure DSC-bővítménnyel.
További részletek a DSC biztonságos hitelesítőadat-kezeléséről.
Bevezetés az Azure DSC-bővítménykezelő használatába.
A PowerShell DSC-ről a PowerShell dokumentációs központjában talál további információt.