مشاركة عبر

ملحق 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"

المشكلة: تحتاج الخاصية المحددة إلى خاصية أخرى، وهي مفقودة.

الحلول‏‎:

  • توفير الخاصيات المفقودة.
  • قم بإزالة الخاصية التي تحتاج إلى الخاصية المفقودة.

الخطوات التالية