Sekitar sebulan yang lalu, saya punya pilihan: apakah akan menulis modul untuk boneka "to the table" (yaitu, untuk infrastruktur internal) atau membuatnya universal, buka sumbernya dan publikasikan di boneka wayang . Tentu saja, akan lebih cepat dan lebih mudah untuk membuat sketsa 2-3 kelas untuk diri sendiri dan tenang, tetapi pengalaman yang diperoleh dalam proses penerbitan modul ini berharga dan saya ingin membaginya. Di RuNet, tidak ada informasi tentang penggunaan kit pengembangan boneka (selanjutnya disebut PDK ), sehingga Anda dapat menganggap ini semacam tutorial.

Tentang apa artikel itu

Dalam proses mengembangkan modul (atau lebih tepatnya, dua), saya menemukan PDK, yang sangat memudahkan pengembangan dan pemeliharaan modul. Yaitu:

• Secara otomatis memformat metadata.json saat memperbarui terakhir
• Pembuatan konfigurasi untuk berbagai sistem CI yang dapat melakukan hal berikut:
  
  • Memeriksa kode ruby ​​dengan rubocop linter
  • Tes Unit Menjalankan
  • Dalam kondisi tertentu - pengisian otomatis kode kerja boneka tempa
• Membuat dokumentasi berbasis tag dalam komentar menggunakan halaman
• Piring [PDK] untuk modul di boneka wayang. Agak, tapi bagus!

Semua tertarik Saya minta kucing!

Sebagai contoh

Jika Anda ingin melihat dan merasakan apa yang dimaksud selama proses membaca, Anda dapat membuka salah satu dari dua (atau keduanya) modul yang disebutkan: clickhouse dan xmlsimple . Keduanya dikembangkan menggunakan PDK dan alat-alat lain yang dijelaskan dalam artikel.

Isi

• Tentang apa artikel itu
  
  • Sebagai contoh
• Apa itu PDK?
  
  • Instalasi
  • Konten PDK
  • Buat modul
  • kelas baru
  • type_type baru
  • penyedia & tugas baru
  • Menghasilkan dokumentasi dengan string boneka
  • Kustomisasi template
  • Menjalankan berbagai CI
  • Bonus: kami menulis unit test untuk kelas, tipe dan fungsi
• Alih-alih output

Apa itu PDK?

Dari dokumentasi resmi:

Buat modul lengkap dengan kelas, tipe yang ditentukan, dan tugas, dan uji dan validasi pekerjaan Anda saat Anda pergi. PDK menyediakan struktur modul yang lengkap, templat untuk kelas, tipe yang ditentukan, dan tugas, dan infrastruktur pengujian. Anda dapat memvalidasi dan menguji modul Anda terhadap berbagai sistem operasi dan beberapa versi Wayang.

Dalam terjemahan gratis saya:

Memungkinkan Anda membuat modul lengkap dengan kelas, jenis, tugas, dan tes untuk memverifikasi operasi modul. PDK menyediakan struktur dan template lengkap untuk semua hal di atas. Dengan menggunakan alat ini, Anda dapat memeriksa pengoperasian modul dengan berbagai versi boneka, serta dalam berbagai OS.

Kedengarannya bagus? Ya, begitulah sebenarnya. Sampai saat ketika saya mulai mengerjakan modul, yang diputuskan untuk menulis segera untuk open source, saya tidak mencurigai alat ini, dan sekarang saya bermaksud untuk mentransfer seluruh infrastruktur internal untuk menggunakan PDK.

Saya akan menjelaskan cara memasukkannya, dan alat serta perintah apa yang dikandungnya.

Instalasi

Halaman instalasi resmi . Dengan menggunakan tautan ini, Anda hampir dijamin menemukan cara yang tepat untuk memasang PDK di host Anda. Jika karena alasan tertentu Anda tidak beruntung dan OS Anda tidak ada, selalu ada bundaran di formulir:

 gem install pdk 

Faktanya, PDK hanyalah permata, dan sudah diatur seperti itu.

Konten PDK

Secara umum, PDK tidak lebih dari satu set permata untuk memfasilitasi pengembangan modul. Ini berisi alat-alat berikut:

Buat modul

PDK terpasang, sekarang Anda bisa bermain-main. Perintah pdk help paling sederhana pdk help menampilkan perintah yang tersedia. Misalkan kita berada di folder tempat Anda memiliki semua modul lainnya. Lalu mari kita buat yang baru:

 $ 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'. 

Utilitas ini mengajukan pertanyaan untuk mengisi file metadata.json, dan hasilnya persis seperti yang ditunjukkan: modul dan file tambahan dikompilasi dari template dari git.

Sebuah komentar kecil - templite sering berubah, termasuk beberapa bug kritis yang telah diperbaiki baru-baru ini. Karena itu, lebih baik menggunakan bukan default dari PDK yang diinstal, tetapi versi terbaru. Benar, ada sisi lain: ketika menggunakan argumen --template-url , PDK menambahkan parameter ini ke file ~.pdk/cache/answers.json dan, dilihat dari keterlambatan dalam eksekusi lebih lanjut dari perintah pdk , ia mencoba untuk mengunduhnya. Jadi hapus parameter ini dari answers.json , atau jangan gunakan saat membuat modul dan ubah di metadata.json .

Mari kita lanjutkan langkah-langkah selanjutnya yang bisa dilakukan menggunakan PDK.

kelas baru

 $ 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 

Perintah ini menciptakan 2 file: manifes itu sendiri untuk kelas dan file spesifikasi untuk mengujinya. Saya akan membahas tag untuk dokumentasi nanti secara lebih rinci.

type_type baru

 $ 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. 

Semua sama: manifes untuk jenis sumber daya dan file spesifikasi.

penyedia & tugas baru

PDK juga dapat membuat penyedia atau tugas baru, tetapi saya tidak bekerja sama dengan mereka, jadi saya akan dengan jujur ​​mengatakan bahwa lebih baik mempelajari topik ini lebih dalam jika perlu.

Menghasilkan dokumentasi dengan string boneka

Saya tidak benar-benar mengerti mengapa puppet strings bukan bagian dari toolkit PDK, tapi ini a la vie. Jika selama pengembangan Anda menempatkan tag dengan benar untuk halaman, maka ada 2 cara utama untuk memberikan dokumentasi kepada pengguna:

• Hasilkan sebagai HTML / Markdown / JSON dan letakkan di sebelah kode. Ini dilakukan dengan perintah puppet string generate [--format FORMAT] , di mana formatnya dapat dihilangkan atau diatur ke json / markdown .
  
  • Sebagai standar untuk dokumentasi, biasanya memiliki file REFERENCE.md di root repositori, yang dihasilkan oleh puppet strings generate --format markdown .
• Publikasikan ke repositori dengan kode (asalkan ada di github) github-pages. Ini cukup sederhana, Anda memerlukan 3 perintah:
  

   #  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 

Tampaknya tidak ada keajaiban, tetapi pada output kita memiliki modul dengan instruksi. Nilai tambahnya adalah bahwa meskipun Anda tidak menjelaskan, katakanlah, masing-masing parameter menggunakan tag @param , output akan tetap berupa kelas / tipe / fungsi dengan deskripsi parameter yang minimal dengan jenis dan nilai default. Menurut pendapat saya, bahkan ini lebih baik daripada tidak sama sekali, dan akan membuat modul lebih menarik untuk digunakan.

Tentu saja, semua ini dapat diotomatisasi dan ditambahkan sebagai tahap CI. Itu akan sempurna. Tangan saya belum mencapai, tetapi sedang mengumpulkan debu di tumpukan. Jika tiba-tiba seseorang mengatakan sesuatu tentang topik ini - saya akan berterima kasih. Sebagai pemikiran: setidaknya tambahkan tanda centang untuk melihat apakah REFERENSI.md berubah setelah menjalankan string-boneka. Dan jika demikian, anggap tes gagal.

Kustomisasi template

Dokumentasi untuk templat terletak di repositori pdk-templates . Singkatnya, semuanya dikonfigurasi menggunakan file .sync.yml di direktori root modul, dan perubahan diterapkan menggunakan perintah pdk update . Setiap parameter file ini adalah nama file lain di direktori modul, yang harus diubah dengan satu atau lain cara. Sebagian besar parameter untuk masing-masing templat saya harus memilih "dengan sentuhan", melihat kode sumber, sering - dengan coba-coba. Dokumentasi di sini terkadang jauh tertinggal. Sayangnya, hampir tidak ada lagi yang bisa dikatakan, kecuali untuk memberikan tautan ke contoh dari repositori Anda sendiri.

Saya akan dengan cepat menggambarkan beberapa parameter yang saya ubah menggunakan .sync.yml dari contoh di atas:

• Gemfile : dua Gemfile ditambahkan sebagai dependensi dalam grup yang berbeda: pdk dalam grup pengembangan; xml-sederhana di grup dependensi. Saat memulai tes, grup system_tests tidak diinstal, jadi saya menambahkan ketergantungan ke grup lain.
• spec/spec_helper.rb : metode moking telah diubah, ambang batas cakupan tes minimum telah ditambahkan, di bawah ini pengujian dianggap gagal.
• .travis.yml : file ini telah dipoles sejak lama, karena digunakan untuk memeriksa basis kode dan memuat modul yang sudah selesai pada puppet-forge. Perubahan:
  
  • Pengguna dan kata sandi terenkripsi untuk mengisi modul pada boneka-menempa. Anda dapat membaca lebih lanjut tentang menggunakan boneka-forge dengan Travis di sini .
  • Urutan tes telah dibuat → penyebaran dengan peluncuran yang terakhir hanya dengan tes yang berhasil.
  • Menambahkan tahap penerapan modul ke puppet-forge, asalkan CI diluncurkan dari tag dimulai dengan karakter "v".
• Rakefile : menambahkan beberapa pengecualian untuk linter.

Menjalankan berbagai CI

Semuanya cukup sederhana di sini. Segera setelah membuat modul menggunakan PDK, validasi dimulai di appveyor, travis, dan gitlab-ci. Untuk menjalankan tes, semuanya siap langsung dari kotak, untuk penyetelan, .sync.yml sama .sync.yml . Saya tidak punya preferensi tertentu, jadi saya tidak akan merekomendasikan apa pun. Cukup gunakan apa pun yang lebih nyaman.

Bonus: kami menulis unit test untuk kelas, tipe dan fungsi

Poin ini melampaui sedikit bahan dasar yang saya rencanakan untuk dijelaskan, tetapi bagi saya tampaknya sangat berguna.

Jadi, kami memiliki modul dengan manifes dan perpustakaan, yang, pada gilirannya, berisi kelas, jenis dan fungsi (kami juga tidak melupakan tugas dan penyedia, tetapi di bagian ini saya tidak memiliki keahlian). Karena ada kode apa pun untuk tujuan perubahan, alangkah baiknya, tentu saja, overlay dengan tes untuk memastikan 2 hal:

• Perubahan tidak merusak perilaku saat ini (atau perubahan perilaku dengan tes)
• Manifes Anda melakukan persis apa yang Anda harapkan dan menggunakan semua sumber daya yang Anda harapkan.

Puppetlabs menyediakan ekstensi untuk kerangka rspec yang disebut puppet-rspec . Tautan ke dokumentasi untuk menguji kelas , tipe, dan fungsi . Jangan terlalu malas melihat dari dekat, ada bagian lain.

Untuk mulai menggunakannya cukup sederhana, tanpa tahu ruby. Jika kelas atau tipe dibuat, seperti yang ditunjukkan di atas, menggunakan pdk new <thing> , maka file *_spec.rb juga sudah ada. Jadi, misalkan kita memiliki dummy::class . Untuk mengujinya, file spec/classes/class_spec.rb harus dibuat dengan konten berikut:

 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 

Anda dapat memverifikasi dengan menjalankan pdk test unit dari direktori root modul.

Itu hampir semua yang kita butuhkan. Sekarang tinggal menambahkan class_spec.rb is_expected dengan kondisi yang sesuai. Misalnya, untuk memeriksa bahwa kelas berisi sumber daya file {'/file/path': } dengan parameter tertentu, Anda dapat melakukan ini:

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

Anda dapat mengatur parameter kelas menggunakan let(:params) { {'param1' => 'value'} } , dimungkinkan untuk melakukan pengujian di bawah berbagai kondisi input dengan menempatkan masing-masing di dalam bagian context 'some description' {} dipilih context 'some description' {} . Dimungkinkan untuk memeriksa kedua dependensi antara sumber daya dan antara kelas: jika diasumsikan, misalnya, bahwa deklarasi kelas berisi inherits , maka Anda dapat menambahkan is_expected.to contain_class('parent_class_name') . Perlu memeriksa perilaku di OS yang berbeda? Itu juga mungkin: kami hanya menunjukkan dalam konteks terpisah fakta-fakta yang diperlukan:

 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 

Secara umum, sejauh yang saya berhasil perhatikan dalam proses menulis tes, kerangka ini memungkinkan Anda untuk memeriksa hampir semua yang mungkin diperlukan. Dan kehadiran tes pernah membantu saya ketika beberapa parameter dipindahkan dari kelas anak ke kelas atas modul: mereka menunjukkan bahwa refactoring tidak merusak apa pun, dan perilaku seluruh modul tidak berubah.

Alih-alih output

Karena sudah dapat dipahami dari intonasi umum artikel, saya sangat terdorong oleh seberapa banyak Wayang bekerja dengan modul dan memanifestasikan lebih mudah berkat PDK. Tindakan rutin dilakukan secara otomatis, templat digunakan sedapat mungkin, konfigurasi untuk CI populer tersedia di luar kotak. Ini mungkin tampak seperti semacam overhead, dan penggunaannya mungkin tidak menghasilkan buah yang diharapkan, tetapi itu pasti sepadan. Jika Anda membandingkan cara mengembangkan modul tanpa dan dengan PDK, maka bagi saya tampilannya seperti ini:

Pengembangan tanpa jenggot PDK	Pengembangan PDK

Coba, letakkan, buat hidup lebih mudah untuk Anda dan kolega Anda. Saya akan dengan senang hati menjawab pertanyaan potensial.

Semoga atomisasi bersama kita!