ملحق Desired State Configuration مع قوالب Azure Resource Manager
إشعار
قبل تمكين ملحق DSC، نود أن تعرف أن إصدارا أحدث من DSC متاح الآن بشكل عام، تتم إدارته بواسطة ميزة تكوين الجهاز المسمى Azure Automange. تجمع ميزة تكوين الجهاز بين ميزات معالج ملحق تكوين الحالة المطلوبة (DSC) وتكوين حالة أتمتة Azure والميزات الأكثر شيوعا المطلوبة من ملاحظات العملاء. يتضمن تكوين الجهاز أيضا دعم الجهاز المختلط من خلال خوادم Arc الممكنة.
توضح هذه المقالة قالب Azure Resource Manager معالج ملحق تكوين الحالة المطلوبة (DSC). تستخدم العديد من الأمثلة RegistrationURL (المقدمة كسلسلة) ومفتاح التسجيل (المقدمة كPSCredential للتوافق مع Azure Automation. للحصول على تفاصيل حول الحصول على هذه القيم، راجع استخدام تكوين تعريف DSC لتسجيل الأجهزة المختلطة.
إشعار
قبل تمكين ملحق DSC، نود أن تعرف أن إصدارا أحدث من DSC متاح الآن بشكل عام، تتم إدارته بواسطة ميزة تكوين الجهاز المسمى Azure Automange. تجمع ميزة تكوين الجهاز بين ميزات معالج ملحق تكوين الحالة المطلوبة (DSC) وتكوين حالة أتمتة Azure والميزات الأكثر شيوعا المطلوبة من ملاحظات العملاء. يتضمن تكوين الجهاز أيضا دعم الجهاز المختلط من خلال خوادم Arc الممكنة.
إشعار
قد ترى أمثلة مخططات مختلفة قليلا. حدث التغيير في المخطط في إصدار أكتوبر 2016. للتفاصيل، يرجى الاطلاع على تحديث من تنسيق سابق.
مثال قالب لجهاز ظاهري Windows
ينتقل المقتطف التالي إلى قسم الموارد في القالب. يرث ملحق DSC خصائص الملحق الافتراضية. لمزيد من المعلومات، راجع فئة VirtualMachineExtension.
{
"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"
}
]
}
}
}
مثال قالب لمجموعات مقاييس الجهاز الظاهري Windows
تحتوي عقدة مجموعة مقياس الجهاز الظاهري على قسم خصائص يحتوي على سمة VirtualMachineProfile, extensionProfile. ضمن الإضافات، أضف تفاصيل ملحق DSC.
يرث ملحق DSC خصائص الملحق الافتراضية. لمزيد من المعلومات، راجع فئة VirtualMachineScaleSetExtension.
"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"
}
]
}
}
}
]
}
معلومات مفصلة عن الإعدادات
استخدم المخطط التالي في قسم الإعدادات من ملحق Azure DSC في قالب Resource Manager.
للحصول على قائمة بالوسيطات المتوفرة للبرنامج النصي الافتراضي للتكوين، راجع البرنامج النصي الافتراضي للتكوين.
"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"
}
التفاصيل
اسم الخاصية | كتابة | الوصف |
---|---|---|
settings.wmfVersion | سلسلة | يحدد إصدار Windows Management Framework (WMF) الواجب تثبيته على الجهاز الظاهري. يؤدي تعيين هذه الخاصية إلى أحدث تثبيت لأحدث إصدار من WMF. حالياً، القيم الوحيدة الممكنة لهذه الخاصية هي 4.0و 5.0و5.1و الأحدث. تخضع هذه القيم الممكنة للتحديثات. القيمة الافتراضية هي الأحدث. |
settings.configuration.url | سلسلة | يحدد موقع عنوان URL الذي يمكن تنزيل ملف .zip تكوين DSC منه. إذا كان عنوان URL المقدم يتطلب رمزا مميزا لـ SAS للوصول إليه، فقم بتعيين الخاصية protectedSettings.configurationUrlSasToken إلى قيمة رمز SAS المميز الخاص بك. هذه الخاصية مطلوبة إذا تم تعريف settings.configuration.script أو settings.configuration.function. إذا لم يتم إعطاء أي قيمة لهذه الخصائص، فإن الملحق يستدعي البرنامج النصي الافتراضي للتكوين لتعيين بيانات تعريف Configuration Manager الموقع (LCM)، ويجب توفير الوسيطات. |
settings.configuration.script | سلسلة | يحدد اسم ملف البرنامج النصي الذي يحتوي على تعريف تكوين DSC الخاص بك. يجب أن يكون هذا البرنامج النصي في المجلد الجذر لملف .zip الذي تم تنزيله من عنوان URL المحدد بواسطة الخاصية settings.configuration.url. هذه الخاصية مطلوبة إذا تم تعريف settings.configuration.url أو settings.configuration.script. إذا لم يتم إعطاء أي قيمة لهذه الخصائص، فإن الملحق يستدعي البرنامج النصي الافتراضي للتكوين لتعيين بيانات تعريف LCM، ويجب توفير الوسيطات. |
settings.configuration.function | سلسلة | يحدد اسم تكوين DSC الخاص بك. يجب تضمين التكوين المسمى في البرنامج النصي الذي يحدده settings.configuration.script. هذه الخاصية مطلوبة إذا تم تعريف settings.configuration.url أو settings.configuration.function. إذا لم يتم إعطاء أي قيمة لهذه الخصائص، فإن الملحق يستدعي البرنامج النصي الافتراضي للتكوين لتعيين بيانات تعريف LCM، ويجب توفير الوسيطات. |
settings.configurationArguments | المجموعة | يحدد أي معلمات تريد تمريرها إلى تكوين DSC الخاص بك. هذه الخاصية غير مشفرة. |
settings.configurationData.url | سلسلة | يحدد عنوان URL الذي يمكنك تنزيل ملف بيانات التكوين (.psd1) منه لاستخدامه كإدخال لتكوين DSC. إذا كان عنوان URL المقدم يتطلب رمزا مميزا لـ SAS للوصول إليه، فقم بتعيين الخاصية protectedSettings.configurationDataUrlSasToken إلى قيمة رمز SAS المميز الخاص بك. |
settings.privacy.dataCollection | سلسلة | تمكين مجموعة بيانات تتبع الاستخدام أو تعطيلها القيم الوحيدة الممكنة لهذه الخاصية هي تمكين أو تعطيل أو '' أو $null. يؤدي ترك هذه الخاصية فارغة أو خالية إلى تمكين القياس عن بعد. القيمة الافتراضية هي ''. لمزيد من المعلومات، راجع جمع بيانات ملحق Azure DSC. |
settings.advancedOptions.downloadMappings | المجموعة | يحدد المواقع البديلة التي يمكن تنزيل WMF منها. لمزيد من المعلومات، راجع ملحق Azure DSC 2.8 وكيفية تعيين تنزيلات تبعيات الملحقات إلى موقعك الخاص. |
protectedSettings.configurationArguments | المجموعة | يحدد أي معلمات تريد تمريرها إلى تكوين DSC الخاص بك. هذه الخاصية مشفرة. |
protectedSettings.configurationUrlSasToken | سلسلة | يحدد الرمز المميز SAS لاستخدامه للوصول إلى عنوان URL الذي يحدده settings.configuration.url. هذه الخاصية مشفرة. |
protectedSettings.configurationDataUrlSasToken | سلسلة | يحدد الرمز المميز SAS لاستخدامه للوصول إلى عنوان URL الذي يحدده settings.configurationData.url. هذه الخاصية مشفرة. |
البرنامج النصي للتكوين الافتراضي
لمزيد من المعلومات حول القيم التالية، راجع الإعدادات الأساسية Configuration Manager المحلية. يمكنك استخدام البرنامج النصي الافتراضي لتكوين ملحق DSC لتكوين خصائص LCM المسردة في الجدول التالي فقط.
اسم الخاصية | كتابة | الوصف |
---|---|---|
protectedSettings.configurationArguments.RegistrationKey | PSCredential | الخاصية المطلوبة. يحدد المفتاح المستخدم لعقدة للتسجيل في خدمة التشغيل التلقائي لـ Azure ككلمة مرور لكائن بيانات اعتماد PowerShell. يمكن اكتشاف هذه القيمة تلقائيا باستخدام أسلوب listkeys مقابل حساب التنفيذ التلقائي. انظر المثال. |
settings.configurationArguments.RegistrationUrl | سلسلة | الخاصية المطلوبة. يحدد عنوان URL لنقطة نهاية التنفيذ التلقائي حيث تحاول العقدة التسجيل. يمكن اكتشاف هذه القيمة تلقائيا باستخدام أسلوب reference مقابل حساب التنفيذ التلقائي. |
settings.configurationArguments.NodeConfigurationName | سلسلة | الخاصية المطلوبة. يحدد تكوين العقدة في حساب التنفيذ التلقائي لتعيينه إلى العقدة. |
settings.configurationArguments.ConfigurationMode | سلسلة | يحدد وضع LCM. تتضمن الخيارات الصالحة ApplyOnlyو ApplyandMonitorو ApplyandAutoCorrect. القيمة الافتراضية هي ApplyandMonitor. |
settings.configurationArguments.RefreshFrequencyMins | UInt32 | يحدد عدد المرات التي يحاول فيها LCM التحقق من التحديثات باستخدام حساب التشغيل التلقائي. القيمة الافتراضية هي 30. أدنى قيمة هي 15. |
settings.configurationArguments.ConfigurationModeFrequencyMins | UInt32 | يحدد عدد المرات التي يقوم فيها LCM بالتحقق من صحة التكوين الحالي. القيمة الافتراضية هي 15. أدنى قيمة هي 15. |
settings.configurationArguments.RebootNodeIfNeeded | boolean | يحدد ما إذا كان يمكن إعادة تشغيل العقدة تلقائيا إذا طلبت عملية DSC ذلك. القيمة الافتراضية هي خطأ. |
settings.configurationArguments.ActionAfterReboot | سلسلة | تحديد ما يحدث بعد إعادة التشغيل عند تطبيق تكوين ما. الخيارات الصالحة هي ContinueConfiguration و StopConfiguration. القيمة الافتراضية هي ContinueConfiguration. |
settings.configurationArguments.AllowModuleOverwrite | boolean | يحدد ما إذا كان LCM يستبدل الوحدات النمطية الموجودة على العقدة. القيمة الافتراضية هي خطأ. |
الإعدادات مقابل الإعدادات المحمية
يتم حفظ جميع الإعدادات في ملف نصي للإعدادات على الجهاز الظاهري. الخصائص المدرجة ضمن الإعدادات هي خصائص عامة. لا يتم تشفير الخصائص العامة في الملف النصي للإعدادات. يتم تشفير الخصائص المدرجة ضمن protectedSettings بشهادة ولا تظهر بنص عادي في ملف الإعدادات على الجهاز الظاهري.
إذا كان التكوين يحتاج إلى بيانات اعتماد، فيمكنك تضمين بيانات الاعتماد في protectedSettings:
"protectedSettings": {
"configurationArguments": {
"parameterOfTypePSCredential1": {
"userName": "UsernameValue1",
"password": "PasswordValue1"
}
}
}
مثال نص التكوين
يوضح المثال التالي السلوك الافتراضي لملحق DSC، وهو توفير إعدادات بيانات التعريف إلى LCM والتسجيل في خدمة DSC التلقائية. وسيطات التكوين مطلوبة. يتم تمرير وسيطات التكوين إلى النص الافتراضي للتكوين لتعيين بيانات تعريف LCM.
"settings": {
"configurationArguments": {
"RegistrationUrl" : "[parameters('registrationUrl1')]",
"NodeConfigurationName" : "nodeConfigurationNameValue1"
}
},
"protectedSettings": {
"configurationArguments": {
"RegistrationKey": {
"userName": "NOT_USED",
"Password": "registrationKey"
}
}
}
مثال على استخدام البرنامج النصي للتكوين في Azure Storage
المثال التالي مأخوذ من نظرة عامة على معالج ملحق DSC.
يستخدم هذا المثال قوالب Resource Manager بدلا من cmdlets لتوزيع الملحق.
احفظ تكوين IisInstall.ps1، وضعه في ملف .zip (على سبيل المثال: iisinstall.zip
)، ثم قم بتحميل الملف في عنوان URL يمكن الوصول إليه.
يستخدم هذا المثال تخزين Azure Blob، ولكن يمكنك تنزيل ملفات .zip من أي موقع عشوائي.
في قالب Resource Manager، التعليمة البرمجية التالية ترشد الجهاز الظاهري لتنزيل الملف الصحيح ثم قم بتشغيل دالة PowerShell المناسبة:
"settings": {
"configuration": {
"url": "https://demo.blob.core.windows.net/iisinstall.zip",
"script": "IisInstall.ps1",
"function": "IISInstall"
}
},
"protectedSettings": {
"configurationUrlSasToken": "odLPL/U1p9lvcnp..."
}
مثال على استخدام قيم تسجيل أتمتة Azure المشار إليها
يحصل المثال التالي على RegistrationUrl وRegistrationKey من خلال الرجوع إلى خصائص حساب Azure Automation واستخدام طريقة listkeys لاسترداد المفتاح الأساسي (0). في هذا المثال، تم توفير المعلمات automationAccountName و 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]"
}
}
}
التحديث من تنسيق سابق
أي إعدادات في تنسيق سابق من الملحق (والتي تحتوي على الخصائص العامة ModulesUrl أو ModuleSourceأوModuleVersion أو ConfigurationFunction أو SasToken أو Properties) تتكيف تلقائيا مع التنسيق الحالي للإضافة. يشتغلون تماما كما في السابق.
يوضح المخطط التالي الشكل الذي بدا عليه مخطط الإعدادات السابقة:
"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"
}
إليك كيفية تكيف التنسيق السابق مع التنسيق الحالي:
اسم الخاصية الحالي | مكافئ المخطط السابق |
---|---|
settings.wmfVersion | settings.wmfVersion |
settings.configuration.url | settings.ModulesUrl |
settings.configuration.script | الجزء الأول من الإعدادات. ConfigurationFunction (قبل \\) |
settings.configuration.function | الجزء الأول من الإعدادات. ConfigurationFunction (قبل \\) |
settings.configuration.module.name | settings.ModuleSource |
settings.configuration.module.version | settings.ModuleVersion |
settings.configurationArguments | settings.Properties |
settings.configurationData.url | protectedSettings.DataBlobUri (بدون رمز SAS) |
settings.privacy.dataCollection | settings.Privacy.dataCollection |
settings.advancedOptions.downloadMappings | settings.AdvancedOptions.DownloadMappings |
protectedSettings.configurationArguments | protectedSettings.Properties |
protectedSettings.configurationUrlSasToken | settings.SasToken |
protectedSettings.configurationDataUrlSasToken | رمز SAS المميز من protectedSettings.DataBlobUri |
استكشاف الأخطاء وإصلاحها
فيما يلي بعض الأخطاء التي قد تواجهها وكيف يمكنك إصلاحها.
قيم غير صالحة
"Privacy.dataCollection هو '{0}'. القيم الوحيدة الممكنة هي "تمكين" و "تعطيل". "WmfVersion هو '{0}'. القيم المُحتملة الوحيدة هي … و"الأحدث".
المشكلة: القيمة المقدمة غير مسموح بها.
الحل: تغيير قيمة غير صالحة إلى قيمة صالحة. لمزيد من المعلومات، راجع الجدول في التفاصيل.
عنوان URL غير صالح
"ConfigurationData.url هو '{0}'. هذا ليس URL صالح" "DataBlobUri هو ''{0}. هذا ليس URL صالح" "Configuration.url هو ''{0}. هذا ليس URL صالح.
المشكلة: URL المقدم غير صالح.
الحل: تحقق من جميع عناوين URL المقدمة. تأكد من أن جميع عناوين URL تتحلل إلى مواقع صالحة يمكن للملحق الوصول إليها على الجهاز البعيد.
RegistrationKey غير صالح
"نوع غير صالح لـ RegistrationKey من النوع PSCredential."
المشكلة: لا يمكن توفير قيمة مفتاح التسجيل في protectedSettings.configurationArguments كأي نوع آخر غير PSCredential.
الحل: تغيير إدخال protectedSettings.configurationArguments الخاص بك لـ RegistrationKey إلى نوع PSCredential باستخدام التنسيق التالي:
"configurationArguments": {
"RegistrationKey": {
"userName": "NOT_USED",
"Password": "RegistrationKey"
}
}
نوع ConfigurationArgument غير صالح
نوع ConfigurationArgument غير صالح {0}"
المشكلة: لا يمكن حل الخاصية ConfigurationArguments إلى كائن جدول التجزئة.
الحل: اجعل خاصية ConfigurationArgumentsالخاصة بك إلى جدول تجزئة. اتبع التنسيق المقدم في الأمثلة السابقة. راقب علامات الاقتباس والفواصل والأقواس.
Duplicate ConfigurationArguments
"العثور على وسيطات مكررة '{0}' في كل من الوسيطات العامة والمحمية"
المشكلة: تحتوي ConfigurationArguments في الإعدادات العامة و ConfigurationArguments في الإعدادات المحمية على خصائص تحمل نفس الاسم.
الحل: إزالة إحدى الخصائص المكررة.
الخصائص المفقودة
"يتطلب settings.Configuration.function تحديد settings.configuration.url أو settings.configuration.module "
"يتطلب settings.Configuration.url تحديد settings.configuration.script "
"يتطلب settings.Configuration.scriptl تحديد settings.configuration.url "
"يتطلب settings.Configuration.url تحديد settings.configuration.function "
"يتطلب protectedSettings.ConfigurationUrlSasToken تحديد settings.configuration.url"
"يتطلب protectedSettings.ConfigurationDataUrlSasToken تحديد settings.configurationData.url"
المشكلة: تحتاج الخاصية المحددة إلى خاصية أخرى، وهي مفقودة.
الحلول:
- توفير الخاصيات المفقودة.
- قم بإزالة الخاصية التي تحتاج إلى الخاصية المفقودة.
الخطوات التالية
- تعرف على كيفية استخدام مجموعات مقاييس الجهاز الظاهري مع ملحق Azure DSC.
- يمكنك العثور على مزيد من التفاصيل حول إدارة بيانات الاعتماد الآمنة في DSC.
- احصل على مقدمة حول معالج ملحقات Azure DSC.
- لمزيد من المعلومات حول PowerShell DSC، انتقل إلى مركز وثائق PowerShell.