قبل شهر تقريبًا ، كان لدي خيار: إما كتابة الوحدة النمطية للدمية "على الطاولة" (أي للبنية التحتية الداخلية) أو لجعلها عالمية ، وفتح المصدر ونشرها على صياغة الدمية . بالطبع ، سيكون من الأسرع والأسهل رسم بسرعة 2-3 علامات لنفسك وتهدئة ، ولكن التجربة التي اكتسبتها أثناء نشر الوحدة النمطية قيمة وأريد أن أشاركها. في RuNet ، لا توجد معلومات حول استخدام مجموعة تطوير العرائس (المشار إليها فيما يلي باسم PDK ) ، لذلك يمكنك اعتبار هذا نوعًا من البرنامج التعليمي.

ما هو المقال حول

في عملية تطوير وحدة نمطية (أو بالأحرى اثنين) ، اكتشفت PDK ، مما يسهل إلى حد كبير تطوير وصيانة الوحدات. وهي:

• تنسيق metadata.json تلقائيًا عند التحديث الأخير
• إنشاء التكوين لأنظمة CI المختلفة التي يمكنها القيام بما يلي:
  
  • التحقق من رمز روبي مع rubocop linter
  • تشغيل وحدة الاختبارات
  • في ظل ظروف معينة - التعبئة التلقائية للدمى صياغة قانون العمل
• توليد الوثائق القائمة على العلامة في التعليقات باستخدام الفناء
• لوحة [PDK] للوحدة النمطية على صياغة الدمية. تافه ، ولكن لطيفة!

كل المهتمين أطلب قطة!

كأمثلة

إذا كنت تريد أن تنظر وتشعر بالمعنى المقصود أثناء عملية القراءة ، فيمكنك فتح إحدى الوحدتين المذكورتين (أو كليهما) المذكورة: clickhouse و xmlsimple . تم تطويرهما باستخدام PDK والأدوات الأخرى الموضحة في المقالة.

المحتويات

• ما هو المقال حول
  
  • كأمثلة
• ما هو PDK
  
  • التثبيت
  • PDK المحتوى
  • إنشاء وحدة نمطية
  • فئة جديدة
  • نوع تعريف جديد
  • مزود جديد ومهمة
  • توليد الوثائق مع سلاسل دمية
  • قالب التخصيص
  • تشغيل مختلف CI
  • المكافأة: نكتب اختبارات وحدة للفئات والأنواع والوظائف
• بدلا من الإخراج

ما هو PDK

من الوثائق الرسمية:

إنشاء وحدة نمطية كاملة مع الفئات ، وأنواع محددة ، والمهام ، واختبار والتحقق من عملك كما تذهب. يوفر PDK بنية وحدة نمطية كاملة وقوالب للفئات وأنواع ومهام محددة وبنية تحتية للاختبار. يمكنك التحقق من صحة واختبار الوحدة النمطية الخاصة بك مقابل أنظمة التشغيل المختلفة وإصدارات متعددة من العرائس.

في الترجمة المجانية:

يتيح لك إنشاء وحدة نمطية كاملة مع الفئات والأنواع والمهام والاختبارات للتحقق من تشغيل الوحدة النمطية. يوفر PDK بنية كاملة وقوالب لكافة ما سبق. باستخدام هذه الأداة ، يمكنك التحقق من تشغيل الوحدة مع الإصدارات المختلفة من الدمى ، وكذلك في أنظمة التشغيل المختلفة.

تبدو جيدة؟ حسنًا ، هذا ما يحدث بالفعل. حتى اللحظة التي بدأت فيها العمل على الوحدة النمطية ، والتي تقرر الكتابة فورًا من أجل المصدر المفتوح ، لم أكن أظن أن هذه الأداة ، وأعتزم الآن نقل البنية التحتية الداخلية بأكملها لاستخدام PDK.

سوف أصف كيفية وضعه ، والأدوات والأوامر التي يحتوي عليها.

التثبيت

صفحة التثبيت الرسمية . باستخدام هذا الرابط ، تكون مضمونًا تقريبًا للعثور على الطريقة الصحيحة لتثبيت PDK على مضيفك. إذا كنت محظوظًا ولسبب ما لم يكن نظام التشغيل لديك موجودًا ، فهناك دائمًا دوار في النموذج:

 gem install pdk 

في الواقع ، PDK مجرد جوهرة ، ويتم ضبطها على هذا النحو.

PDK المحتوى

بشكل عام ، PDK ليس أكثر من مجموعة من الأحجار الكريمة لتسهيل تطوير الوحدة. يحتوي على الأدوات التالية:

إنشاء وحدة نمطية

تثبيت PDK ، الآن يمكنك اللعب حولها. أبسط أمر pdk help سيعرض الأوامر المتاحة. لنفترض أننا في المجلد حيث لديك جميع الوحدات الأخرى. ثم لنقم بإنشاء واحدة جديدة:

 $ pdk new module --template-url=https://github.com/puppetlabs/pdk-templates.git *** We need to create the metadata.json file for this module, so we're going to ask you 5 questions. *** [Q 1/5] If you have a name for your module, add it here. --> dummy [Q 2/5] If you have a Puppet Forge username, add it here. --> felixoid [Q 3/5] Who wrote this module? --> Mikhail f. Shiryaev [Q 4/5] What license does this module code fall under? --> MIT [Q 5/5] What operating systems does this module support? --> RedHat based Linux, Debian based Linux, Windows Metadata will be generated based on this information, continue? Yes pdk (INFO): Module 'dummy' generated at path '/tmp/dummy', from template 'https://github.com/puppetlabs/pdk-templates.git'. 

تسأل الأداة المساعدة أسئلة لملء ملف metadata.json ، ويتضمن الإخراج بالضبط ما هو مبين: الوحدة النمطية والملفات المساعدة التي تم تجميعها من قوالب من البوابة.

ملاحظة صغيرة - temlites تتغير في كثير من الأحيان ، بما في ذلك بعض الأخطاء الحرجة التي تم إصلاحها مؤخرا. لذلك ، من الأفضل عدم استخدام الإعدادات الافتراضية من PDK المثبتة ، ولكن أحدث إصدار. صحيح ، هناك جانب انعكاس: عند استخدام --template-url ، يضيف PDK هذه المعلمة إلى ملف ~.pdk/cache/answers.json ، وإذا حكمنا بالتأخير في تنفيذ أي من أوامر pdk ، فإنه يحاول تنزيلها. لذلك إما أن تزيل هذه المعلمة من answers.json ، أو لا تستخدمها عند إنشاء وحدة نمطية وتغييرها في metadata.json .

دعنا نذهب من خلال الخطوات الإضافية التي يمكن تنفيذها باستخدام PDK.

فئة جديدة

 $ pdk new class dummy::class pdk (INFO): Creating '/tmp/dummy/manifests/class.pp' from template. pdk (INFO): Creating '/tmp/dummy/spec/classes/class_spec.rb' from template. $ cat manifests/class.pp # A description of what this class does # # @summary A short summary of the purpose of this class # # @example # include dummy::class class dummy::class { } $ cat spec/classes/class_spec.rb require 'spec_helper' describe 'dummy::class' do on_supported_os.each do |os, os_facts| context "on #{os}" do let(:facts) { os_facts } it { is_expected.to compile } end end end 

ينشئ هذا الأمر ملفين: البيان نفسه للفئة وملف المواصفات لاختباره. سوف أتطرق إلى العلامات الخاصة بالوثائق لاحقًا بمزيد من التفاصيل.

نوع تعريف جديد

 $ pdk new defined_type type pdk (INFO): Creating '/tmp/dummy/manifests/type.pp' from template. pdk (INFO): Creating '/tmp/dummy/spec/defines/type_spec.rb' from template. 

كل نفس: بيان لنوع المورد وملف المواصفات.

مزود جديد ومهمة

يمكن لـ PDK أيضًا إنشاء موفر أو مهمة جديدة ، لكنني لم أعمل معها عن كثب ، لذلك سأقول بصراحة أنه من الأفضل دراسة هذا الموضوع بتعمق أكبر إذا لزم الأمر.

توليد الوثائق مع سلاسل دمية

أنا لا أفهم حقًا لماذا لا puppet strings جزءًا من مجموعة أدوات PDK ، ومع ذلك ، فهذه ليست la. إذا قمت أثناء التطوير بوضع علامات بشكل صحيح على الفناء ، فهناك طريقتان رئيسيتان لتقديم الوثائق للمستخدم:

• قم بإنشائه كـ HTML / Markdown / JSON ووضعه بجانب الكود. يتم ذلك باستخدام أمر puppet string generate [--format FORMAT] الأمر ، حيث يمكن حذف التنسيق أو تعيينه على json / markdown .
  
  • من المعتاد أن يكون لديك ملف REFERENCE.md في جذر المستودع كمعيار للوثائق ، والذي يتم إنشاؤه بواسطة puppet strings generate --format markdown .
• انشر إلى المستودع برمز (بشرط أن يكون على جيثب) - صفحات جيثب. هذا بسيط للغاية ، تحتاج إلى 3 أوامر:
  

   #  Gemfile.lock,    PDK rm -f Gemfile.lock #     Gemfile   bundle bundle install --path vendor/bundle #   gh-pages   rake-task bundle exec rake strings:gh_pages:update 

يبدو أنه ليس سحرًا ، ولكن عند الإخراج ، لدينا وحدة نمطية تحتوي على تعليمات. الإيجابيات هي أنه حتى لو لم تصف ، على سبيل المثال ، كل معلمة تستخدم علامة @param ، فسيظل الإخراج فئة / نوع / وظيفة مع الحد الأدنى من وصف المعلمات بالنوع والقيمة الافتراضية. في رأيي المتواضع ، حتى هذا أفضل من لا شيء ، وسيجعل الوحدة أكثر جاذبية للاستخدام.

بالطبع ، يمكن أتمتة كل هذا وإضافته كمرحلة CI. سيكون ذلك مثاليا. لم تصل يدي بعد ، لكنها تتراكم في الغبار. إذا كان شخص ما لديه فجأة ما يقوله حول هذا الموضوع - سأكون ممتنًا. كأفكار: قم بإضافة الاختيار على الأقل لمعرفة ما إذا كان REFERENCE.md يتغير بعد تشغيل سلاسل الدمى. وإذا كان الأمر كذلك ، فكر في فشل الاختبارات.

قالب التخصيص

توجد وثائق القوالب في مستودع قوالب pdk . باختصار ، يتم تكوين كل شيء باستخدام ملف .sync.yml في الدليل الجذر للوحدة النمطية ، ويتم تطبيق التغييرات باستخدام أمر pdk update . كل معلمة من هذا الملف هو اسم ملف آخر في دليل الوحدة النمطية ، والتي يجب تغييرها بطريقة أو بأخرى. معظم المعلمات لكل من القوالب اضطررت إلى تحديد "عن طريق اللمس" ، والنظر في شفرة المصدر ، في كثير من الأحيان - عن طريق التجربة والخطأ. الوثائق هنا في بعض الأحيان متأخرة كثيرا. لسوء الحظ ، لا يوجد شيء تقوله تقريبًا ، باستثناء إعطاء رابط لمثال من مستودعك الخاص.

سوف أصف بسرعة بعض المعلمات التي قمت بتغييرها باستخدام .sync.yml من المثال أعلاه:

• Gemfile : تم إضافة اثنين من Gemfile كتبعيات في مجموعات مختلفة: pdk في مجموعة التطوير ؛ XML بسيطة في مجموعة التبعيات. عند بدء الاختبارات ، لم يتم تثبيت مجموعة system_tests ، لذا أضفت التبعية إلى مجموعة أخرى.
• spec/spec_helper.rb : تم تغيير طريقة spec/spec_helper.rb ، وتم إضافة الحد الأدنى لتغطية التغطية للاختبار ، والذي تعتبر الاختبارات أدناه فاشلة فيه.
• .travis.yml : لقد تم تلميع هذا الملف لفترة طويلة ، حيث يتم استخدامه للتحقق من قاعدة الشفرة وتحميل الوحدة النمطية الجاهزة في لعبة الدمية. التغييرات:
  
  • المستخدم وكلمة المرور المشفرة لملء الوحدة النمطية على الدمية صياغة. يمكنك قراءة المزيد حول نشر لعبة الدمية مع ترافيس هنا .
  • تم إنشاء سلسلة من الاختبارات → النشر مع إطلاق الأخير فقط مع الاختبارات الناجحة.
  • تمت إضافة مرحلة نشر الوحدة النمطية إلى العرائس ، بشرط أن يتم إطلاق CI من العلامة التي تبدأ بالحرف "v".
• Rakefile : إضافة بعض الاستثناءات ل linter.

تشغيل مختلف CI

كل شيء بسيط جدا هنا. مباشرة بعد إنشاء الوحدة باستخدام PDK ، يبدأ التحقق من الصحة في الناقل ، ترافيس وجيتلاب. لتشغيل الاختبارات ، يكون كل شيء جاهزًا تمامًا خارج الصندوق ، .sync.yml نفس .sync.yml . ليس لدي تفضيلات معينة ، لذلك لن أوصي بأي شيء. مجرد استخدام كل ما هو أكثر ملاءمة.

المكافأة: نكتب اختبارات وحدة للفئات والأنواع والوظائف

هذه النقطة تتجاوز إلى حد بعيد المواد الأساسية التي خططت لوصفها ، لكن يبدو لي أنها مفيدة جدًا.

لذلك ، لدينا وحدة نمطية تحتوي على بيانات ومكتبة ، والتي بدورها تحتوي على فئات وأنواع ووظائف (لا ننسى أيضًا المهام ومقدمي الخدمات ، لكن ليس لدي أي خبرة في هذا الجزء). نظرًا لوجود أي رمز لغرض التغيير ، سيكون من الجميل ، من الواضح ، تراكبه مع الاختبارات للتأكد من شيئين:

• لا تؤدي التغييرات إلى كسر السلوك الحالي (أو تغييرات السلوك مع الاختبارات)
• تظهر بياناتك بالضبط ما تتوقعه وتستخدم كل الموارد التي تتوقعها.

يوفر Puppetlabs امتدادًا لإطار rspec يسمى puppet-rspec . ارتباطات إلى وثائق اختبار الفئات وأنواعها ووظائفها . لا تكون كسول جدا للنظر عن كثب ، وهناك أقسام أخرى.

البدء في استخدامه بسيط للغاية ، حتى دون معرفة روبي. إذا تم إنشاء فئات أو أنواع ، كما هو موضح أعلاه ، باستخدام pdk new <thing> ، فإن ملف *_spec.rb موجود أيضًا بالفعل. لذلك ، لنفترض أن لدينا dummy::class . لاختباره ، يجب إنشاء ملف spec/classes/class_spec.rb بالمحتويات التالية:

 require 'spec_helper' describe 'dummy::class' do on_supported_os.each do |os, os_facts| context "on #{os}" do let(:facts) { os_facts } it { is_expected.to compile } end end end 

يمكنك التحقق عن طريق تشغيل pdk test unit من الدليل الجذر للوحدة النمطية.

هذا كل ما نحتاجه تقريبا. الآن يبقى لاستكمال class_spec.rb بالضروري is_expected مع الشروط المناسبة. على سبيل المثال ، للتحقق من أن الفصل يحتوي على file {'/file/path': } مع بعض المعلمات ، يمكنك القيام بذلك:

 it do is_expected.to contain_file('/file/path').with( 'ensure' => 'file', 'mode' => '0644' ) end 

يمكنك تعيين معلمات الفصل باستخدام let(:params) { {'param1' => 'value'} } ، فمن الممكن إجراء الاختبارات في ظل ظروف الإدخال المختلفة عن طريق وضع كل it داخل أقسام context 'some description' {} المحددة context 'some description' {} . من الممكن التحقق من التبعيات بين الموارد وبين الفئات: إذا كان من المفترض ، على سبيل المثال ، أن يحتوي تعريف الفئة على is_expected.to contain_class('parent_class_name') ، فيمكنك إضافة is_expected.to contain_class('parent_class_name') . تحتاج إلى التحقق من السلوك في نظام التشغيل المختلفة؟ من الممكن أيضًا: أن نشير ببساطة في سياق منفصل إلى الحقائق الضرورية:

 context 'with Debian' do let(:facts) do { os: { architecture: 'amd64', distro: { codename: 'stretch', id: 'Debian', release: { full: '9.6', major: '9', minor: '6', }, }, family: 'Debian', name: 'Debian', release: { full: '9.6', major: '9', minor: '6', }, selinux: { enabled: false, }, }, osfamily: 'Debian', } end it { is_expected.to something } end 

بشكل عام ، بقدر ما تمكنت من ملاحظة عملية كتابة الاختبارات ، فإن الإطار يتيح لك فحص كل ما قد يلزم. وساعدني وجود الاختبارات ذات مرة عندما تم نقل بعض المعلمات من الفصول الفرعية إلى الطبقة العليا للوحدة: فقد أظهرت أن إعادة إنشاء المباني لم يكسر شيئًا ، ولم يتغير سلوك الوحدة بأكملها.

بدلا من الإخراج

نظرًا لأنه يمكن فهمه بالفعل من التجويد العام لهذه المقالة ، فإنني متشجع للغاية من مقدار ما جعل Puppet من العمل باستخدام الوحدات النمطية ويتجلى بسهولة بفضل PDK. الإجراءات الروتينية تلقائية ، ويتم استخدام القوالب حيثما كان ذلك ممكنًا ، وتتوفر التكوينات الخاصة بـ CI الشائعة خارج الصندوق. قد يبدو وكأنه نوع من النفقات العامة ، وقد لا يجلب الاستخدام الثمار المتوقعة ، لكنه بالتأكيد يستحق كل هذا العناء. إذا قارنت كيفية تطوير وحدات بدون PDK وبدون ذلك ، فبالنسبة لي يبدو الأمر كما يلي:

التنمية بدون اللحى PDK	تطوير PDK

حاول أن تجعل الحياة أسهل لنفسك وزملائك. سأكون سعيدًا للإجابة على الأسئلة المحتملة.

قد يكون الانحلال معنا!