Kívánt állapotkonfigurációs bővítmény Azure Resource Manager-sablonokkal

Cikk
08/25/2024

Feljegyzés

A DSC-bővítmény engedélyezése előtt szeretnénk tudni, hogy a DSC egy újabb verziója á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ő, az Azure Automation State Configuration és az ügyfél visszajelzéseiből leggyakrabban kért funkciókat. A gépkonfiguráció az Arc-kompatibilis kiszolgálókon keresztüli hibrid géptámogatást is magában foglalja.

Ez a cikk a Desired State Configuration (DSC) bővítménykezelő Azure Resource Manager-sablonját ismerteti. Számos példa a RegistrationURL (sztringként van megadva) és a RegistrationKey (PSCredentialként biztosított) használatával készíti elő az Azure Automationt. Az értékek beszerzéséről további információt a hibrid gépek regisztrálása DSC-metakonfigurációval című témakörben talál.

Feljegyzés

Előfordulhat, hogy kissé eltérő séma-példákat tapasztal. A séma módosítása a 2016. októberi kiadásban történt. További 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élda sablon windowsos virtuálisgép-méretezési csoportokhoz

A virtuálisgép-méretezési csoport csomópontja rendelkezik egy tulajdonságszakaszsal , amely VirtualMachineProfile , extensionProfile attribútummal rendelkezik. A bővítmények alatt 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 a következő 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 az Alapértelmezett konfigurációs szkript című témakörben találja.

"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	Leírás
settings.wmfVersion	húr	Megadja a windowsos felügyeleti keretrendszer (WMF) azon verzióját, amelyet telepítenie kell a virtuális gépre. 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, az 5.0, az 5.1 és a legújabb. Ezek a lehetséges értékek frissítések tárgyát képezik. Az alapértelmezett érték a legújabb.
settings.configuration.url	húr	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 a settings.configuration.script vagy a settings.configuration.function definiálásakor szükséges. Ha ezekhez a tulajdonságokhoz nincs érték megadva, a bővítmény meghívja az alapértelmezett konfigurációs szkriptet a Location Configuration Manager (LCM) metaadatainak beállításához, és argumentumokat kell megadni.
settings.configuration.script	húr	Megadja annak a szkriptnek a fájlnevét, amely tartalmazza a DSC-konfiguráció definícióját. 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 a settings.configuration.url vagy a settings.configuration.script definiálásához szükséges. 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	húr	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 a settings.configuration.url vagy a settings.configuration.function definiálásához szükséges. 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	húr	Megadja azt az URL-címet, amelyről le szeretné tölteni a konfigurációs adatokat (.psd1) a DSC-konfiguráció bemeneteként használni. 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	húr	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. A tulajdonság üres vagy null értékének elhagyása lehetővé teszi a telemetriát. Az alapértelmezett érték a "". További információkért lásd az Azure DSC bővítmény adatgyűjtését.
settings.advancedOptions.downloadMappings	Gyűjtemény	Alternatív helyeket határoz meg, ahonnan le szeretné tölteni a WMF-et. További információkért tekintse meg az Azure DSC 2.8-s bővítményét, valamint a bővítményfüggőségek letöltéseinek leképezését 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	húr	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	húr	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 tekintse meg a Local Configuration Manager alapszintű beállításait. A DSC-bővítmény alapértelmezett konfigurációs szkriptjének használatával csak az alábbi táblázatban felsorolt LCM-tulajdonságokat konfigurálhatja.

Tulajdonság neve	Típus	Leírás
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Kötelező tulajdonság. Megadja azt a kulcsot, amellyel egy csomópont regisztrálhat az Azure Automation szolgáltatásban Egy PowerShell hitelesítőadat-objektum jelszavaként. Ez az érték automatikusan felderíthető a listkeys metódussal az Automation-fiókon. Lásd a példát.
settings.configurationArguments.RegistrationUrl	húr	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ával .
settings.configurationArguments.NodeConfigurationName	húr	Kötelező tulajdonság. Az Automation-fiók csomópontkonfigurációját adja meg a csomóponthoz rendelve.
settings.configurationArguments.ConfigurationMode	húr	Megadja 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	Megadja, hogy az LCM milyen gyakran kísérel meg ellenőrizni az Automation-fiókot a frissítésekért. 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	Logikai	Megadja, hogy egy csomópont automatikusan újraindítható-e, ha egy DSC-művelet kéri. Az alapértelmezett érték hamis.
settings.configurationArguments.ActionAfterReboot	húr	Megadja, hogy mi történik az újraindítás után egy 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	Logikai	Megadja, hogy az LCM felülírja-e a csomópont meglévő moduljait. Az alapértelmezett érték hamis.

beállítások és protectedSettings

A rendszer az összes beállítást a virtuális gépen lévő beállítások szövegfájljában menti. 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ánysal 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óhoz hitelesítő adatokra van szükség, a hitelesítő adatokat a protectedSettingsben is megadhatja:

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

Példa konfigurá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 biztosít 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 az 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 arra 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 metódust az Azure Automation-fiók tulajdonságaira való hivatkozással, valamint a listkeys metódussal az elsődleges kulcs (0) lekéréséhez. 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ában szereplő beállítások (és amelyek a ModulesUrl, a ModuleSource, a ModuleVersion, a ConfigurationFunction, a SasToken vagy a Properties nyilvános tulajdonságokkal rendelkeznek) automatikusan igazodnak a bővítmény aktuális formátumához. Ugyanúgy futnak, mint korábban.

Az alábbi séma az előző beállításséma kinézetét mutatja:

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

Jelenlegi 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. Kellékek
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 is ''{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ókért tekintse meg a részleteket tartalmazó táblázatot.

Érvénytelen URL-cím

"ConfigurationData.url is ''{0}. Ez nem érvényes URL-cím" "DataBlobUri is '"{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 az összes URL-cím olyan érvényes helyre van feloldva, amelyhez a bővítmény hozzáfér a távoli gépen.

Érvénytelen RegistrationKey-típus

"A PSCredential típusú RegistrationKey paraméter érvénytelen típusa."

Probléma: A registrationKey érték a protectedSettings.configurationArguments fájlban nem adható meg PSCredentialtól eltérő típusként.

Megoldás: Módosítsa a RegistrationKey védettSettings.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: A ConfigurationArguments tulajdonság kivonattáblává alakítása. Kövesse az előző példákban megadott formátumot. Nézze meg az idézőjeleket, a vesszőket és a zárójeleket.

Duplikált ConfigurationArguments

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

Probléma: A nyilvános beállítások ConfigurationArguments és a ConfigurationArguments védett beállításokban ugyanazzal a névvel rendelkeznek.

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 a settings.configuration.module meg legyen adva"

"beállítások. A Configuration.url-címhez meg kell adni a settings.configuration.script parancsprogramot"

"beállítások. A Configuration.script megköveteli, hogy a settings.configuration.url meg legyen adva"

"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, hogy a settings.configurationData.url meg legyen adva"

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énysel.
További információ a DSC biztonságos hitelesítő adatok kezeléséről.
Ismerkedjen meg az Azure DSC bővítménykezelőével.
A PowerShell DSC-vel kapcsolatos további információkért látogasson el a PowerShell dokumentációs központjába.

Megosztás a következőn keresztül: