Dalam proyek-proyek besar, yang terdiri dari puluhan dan ratusan layanan yang saling berinteraksi, pendekatan terhadap dokumentasi sebagai kode - dokumen sebagai kode - menjadi semakin wajib.
Saya akan menunjukkan bagaimana Anda dapat menerapkan filosofi ini dalam realitas layanan rahasia, atau lebih tepatnya, saya akan mulai dari tahap pertama implementasinya: otomatisasi memperbarui data dalam dokumentasi.
Tool kit
Prinsip "dokumentasi sebagai kode" menyiratkan penggunaan alat yang sama saat menulis dokumentasi seperti ketika membuat kode: bahasa markup teks, sistem kontrol versi, tinjauan kode dan pengujian otomatis. Tujuan utama: untuk menciptakan kondisi bagi seluruh tim untuk bekerja bersama pada hasil akhir - basis pengetahuan yang lengkap dan instruksi tentang penggunaan layanan produk individual. Selanjutnya, saya akan berbicara tentang alat khusus yang kami pilih untuk menyelesaikan masalah ini.
Sebagai bahasa markup teks, kami memutuskan untuk menggunakan yang paling universal - reStructuredText . Selain sejumlah besar arahan yang menyediakan semua fungsi dasar untuk penataan teks, bahasa ini mendukung format final utama, termasuk HTML yang diperlukan untuk proyek kami.
File dikonversi dari .rst ke .html menggunakan generator dokumentasi Sphinx . Ini memungkinkan Anda membuat situs statis yang dapat Anda buat sendiri atau gunakan tema yang sudah jadi . Proyek kami menggunakan dua tema yang sudah jadi - stanford-theme dan bootstrap-theme . Yang kedua berisi subtopik yang memungkinkan Anda untuk mengatur skema warna yang berbeda untuk elemen antarmuka utama.
Untuk akses yang mudah dan cepat ke versi dokumentasi saat ini, kami menggunakan situs statis yang dihosting oleh mesin virtual yang dapat diakses dari jaringan area lokal dari tim pengembangan.
File sumber proyek disimpan dalam repositori Bitbucket, dan situs ini dihasilkan hanya dari file yang ada di cabang master. Memperbarui data di dalamnya hanya dimungkinkan melalui pull-request, yang memungkinkan Anda untuk memeriksa semua bagian baru dari dokumentasi sebelum dipublikasikan di domain publik.
Karena antara penyelesaian bagian baru dari dokumentasi dan pengirimannya ke situs itu perlu untuk memeriksa isinya, proses kunci dalam seluruh rantai adalah proses membangun situs dan memperbarui data pada host. Prosedur ini harus diulang setiap kali setelah permintaan tarik dengan pembaruan bergabung dengan cabang utama proyek.
Untuk mengimplementasikan logika ini memungkinkan Jenkins - sistem integrasi pengembangan yang berkelanjutan, dalam kasus kami - dokumentasi. Saya akan memberi tahu Anda lebih banyak tentang pengaturan di bagian:
- Menambahkan Node Baru ke Jenkins
- Deskripsi Jenkinsfile
- Integrasi Jenkins dan Bitbucket
Menambahkan Node Baru ke Jenkins
Untuk membuat dan memperbarui dokumentasi di situs, Anda harus mendaftarkan mesin yang disiapkan sebelumnya sebagai agen Jenkins untuk ini.
Persiapan mesin
Menurut persyaratan Jenkins , semua komponen yang termasuk dalam sistem, termasuk mesin master dan semua node agen terdaftar, harus memiliki JDK atau JRE yang diinstal. Dalam kasus kami, JDK 8 akan digunakan, untuk instalasi yang cukup untuk menjalankan perintah:
sudo apt-get -y install java-1.8.0-openjdk git
Mesin master akan terhubung ke agen untuk melakukan tugas yang ditugaskan di atasnya. Untuk melakukan ini, Anda perlu membuat pengguna di agen yang di dalamnya semua operasi akan dilakukan, dan di mana semua file yang dihasilkan Jenkins akan disimpan dalam folder rumah. Pada sistem Linux, jalankan saja perintah:
sudo adduser jenkins \--shell /bin/bash su jenkins
Untuk membuat koneksi antara mesin master dan agen, Anda harus mengkonfigurasi SSH dan menambahkan kunci otorisasi yang diperlukan. Kami akan menghasilkan kunci pada agen, setelah itu kami akan menambahkan kunci publik ke file authorized_keys untuk pengguna jenkins .
Kami akan membangun situs dengan dokumentasi dalam wadah Docker menggunakan gambar python yang sudah jadi: 3.7 . Ikuti instruksi dalam dokumentasi resmi untuk menginstal Docker pada agen. Untuk menyelesaikan proses instalasi, Anda harus menyambung kembali ke agen. Verifikasi pemasangan dengan menjalankan perintah yang memuat gambar uji:
docker run hello-world
Agar tidak harus menjalankan perintah Docker atas nama pengguna super (sudo), cukup menambahkan grup pengguna docker yang dibuat pada tahap instalasi, atas nama yang perintahnya akan dieksekusi.
sudo usermod -aG docker $USER
Jenkins Konfigurasi Node Baru
Karena menghubungkan ke agen memerlukan otorisasi, Anda harus menambahkan kredensial yang sesuai dalam pengaturan Jenkins. Petunjuk terperinci tentang cara melakukan ini pada mesin Windows disediakan dalam dokumentasi Jenkins resmi .
PENTING: Pengidentifikasi yang ditentukan di bagian Konfigurasi Jenkins -> Kelola lingkungan build -> Nama Node -> Konfigurasikan dalam parameter Tag digunakan di Jenkinsfile untuk menunjukkan agen tempat semua operasi akan dilakukan.
Deskripsi Jenkinsfile
Akar repositori proyek berisi Jenkinsfile , yang berisi instruksi untuk:
- Mempersiapkan lingkungan build dan menginstal dependensi
- Buat situs menggunakan Sphinx
- memperbarui informasi host.
Petunjuk ditetapkan menggunakan arahan khusus, aplikasi yang akan kami pertimbangkan lebih lanjut pada contoh file yang digunakan dalam proyek.
Indikasi Agen
Pada awal Jenkinsfile, tentukan label agen di Jenkins , yang akan melakukan semua operasi. Untuk melakukan ini, gunakan arahan agen :
agent { label '-' }
Persiapan lingkungan
Untuk menjalankan perintah build situs sphinx-build, Anda perlu mengatur variabel lingkungan di mana jalur data aktual akan disimpan. Juga, untuk memperbarui informasi pada host, Anda harus menentukan terlebih dahulu jalur tempat data situs dengan dokumentasi disimpan. Arahan lingkungan memungkinkan Anda untuk menetapkan nilai-nilai ini ke variabel:
environment { SPHINX_DIR = '.' //, Sphinx BUILD_DIR = 'project_home_built' // SOURCE_DIR = 'project_home_source' // .rst .md DEPLOY_HOST = 'username@127.1.1.0:/var/www/html/' //@IP__:__ }
Tindakan utama
Instruksi utama yang akan dieksekusi di Jenkinsfile terkandung dalam arahan tahap , yang terdiri dari langkah-langkah yang berbeda yang dijelaskan oleh arahan panggung . Contoh sederhana dari pipa CI tiga tahap:
pipeline { agent any stages { stage('Build') { steps { echo 'Building..' } } stage('Test') { steps { echo 'Testing..' } } stage('Deploy') { steps { echo 'Deploying....' } } } }
Luncurkan wadah Docker dan instal dependensi
Pertama, jalankan wadah Docker dengan gambar python yang sudah jadi : 3.7 . Untuk melakukan ini, gunakan perintah run docker dengan flag --rm dan -i . Kemudian secara berurutan lakukan hal berikut:
- instal python virtualenv ;
- membuat dan mengaktifkan lingkungan virtual baru;
- instal di dalamnya semua dependensi yang diperlukan tercantum dalam file
requirement.txt, yang disimpan di root repositori proyek.
stage('Install Dependencies') { steps { sh ''' docker run --rm -i python:3.7 python3 -m pip install --user --upgrade pip python3 -m pip install --user virtualenv python3 -m virtualenv pyenv . pyenv/bin/activate pip install -r \${SPHINX\_DIR}/requirements.txt ''' } }
Bangun situs dengan dokumentasi
Sekarang mari kita membangun situs. Untuk melakukan ini, jalankan perintah sphinx-build dengan flag berikut:
-q : hanya peringatan dan kesalahan log;
-w : menulis log ke file yang ditentukan setelah flag;
-b : nama pembuat situs;
-d : tentukan direktori untuk menyimpan file yang di-cache - acar doktree.
Sebelum memulai perakitan, menggunakan perintah rm -rf hapus perakitan dan log situs sebelumnya. Jika terjadi kesalahan pada salah satu tahapan, log eksekusi sphinx-build akan muncul di konsol Jenkins .
stage('Build') { steps { // clear out old files sh 'rm -rf ${BUILD_DIR}' sh 'rm -f ${SPHINX_DIR}/sphinx-build.log' sh ''' ${WORKSPACE}/pyenv/bin/sphinx-build -q -w ${SPHINX_DIR}/sphinx-build.log \ -b html \ -d ${BUILD_DIR}/doctrees ${SOURCE\_DIR} ${BUILD\_DIR} ''' } post { failure { sh 'cat ${SPHINX_DIR}sphinx-build.log' } } }
Host pembaruan situs
Dan akhirnya, kami akan memperbarui informasi tentang host yang melayani situs dengan dokumentasi produk yang tersedia di lingkungan lokal. Dalam implementasi saat ini, host adalah mesin virtual yang sama yang terdaftar sebagai agen Jenkins untuk tugas merakit dan memperbarui dokumentasi.
Sebagai alat sinkronisasi, kami menggunakan utilitas rsync . Agar berfungsi dengan benar, perlu untuk mengkonfigurasi koneksi SSH antara wadah Docker, di mana situs dengan dokumentasi itu pergi, dan tuan rumah.
Untuk mengkonfigurasi koneksi SSH menggunakan Jenkinsfile , plugin berikut ini harus diinstal di Jenkins :
- Plugin SSH Agent - memungkinkan Anda untuk menggunakan langkah
sshagent dalam skrip untuk memberikan kredensial dari form nama pengguna / kunci . - Plugin SSH Credentials - memungkinkan Anda untuk menyimpan kredensial form username / key di pengaturan Jenkins .
Setelah menginstal plugin, Anda harus menentukan kredensial saat ini untuk menghubungkan ke host dengan mengisi formulir di bagian Kredensial :
- ID : pengidentifikasi yang akan digunakan dalam Jenkinsfile dalam langkah
sshagent untuk menunjukkan kredensial tertentu ( docs-deployer ); - Nama pengguna : nama pengguna di mana operasi pembaruan data situs akan dilakukan (pengguna harus memiliki akses tulis ke folder
/var/html host); - Kunci Pribadi : kunci pribadi untuk mengakses host;
- Passphrase : kata sandi untuk kunci, jika ditetapkan pada tahap pembuatan.
Di bawah ini adalah kode skrip yang menghubungkan melalui SSH dan memperbarui informasi pada host menggunakan variabel sistem yang ditentukan pada tahap mempersiapkan lingkungan dengan jalur ke data yang diperlukan. Hasil dari perintah rsync ditulis ke log, yang akan ditampilkan di konsol Jenkins jika terjadi kesalahan sinkronisasi.
stage('Deploy') { steps { sshagent(credentials: ['docs-deployer']) { sh ''' #!/bin/bash rm -f ${SPHINX_DIR}/rsync.log RSYNCOPT=(-aze 'ssh -o StrictHostKeyChecking=no') rsync "${RSYNCOPT[@]}" \ --delete \ ${BUILD_DIR_CI} ${DEPLOY_HOST}/ ''' } } post { failure { sh 'cat ${SPHINX_DIR}/rsync.log' } } }
Integrasi Jenkins dan Bitbucket
Ada banyak cara untuk mengatur interaksi Jenkins dan Bitbucket , tetapi dalam proyek kami kami memutuskan untuk menggunakan Parameterized Builds untuk plugin Jenkins . Dokumentasi resmi berisi instruksi terperinci untuk menginstal plugin, serta pengaturan yang harus ditentukan untuk kedua sistem. Untuk bekerja dengan plugin ini, Anda perlu membuat pengguna Jenkins dan menghasilkan token khusus untuknya yang akan memungkinkan pengguna ini untuk masuk ke sistem.
Membuat token pengguna dan API
Untuk membuat pengguna baru di Jenkins , buka Pengaturan Jenkins -> Manajemen Pengguna -> Buat Pengguna , dan isi semua kredensial yang diperlukan dalam formulir.
Mekanisme otentikasi yang memungkinkan skrip atau aplikasi pihak ketiga untuk menggunakan Jenkins API tanpa benar-benar mentransmisikan kata sandi pengguna adalah token API khusus yang dapat dihasilkan untuk setiap pengguna Jenkins . Untuk melakukan ini:
- masuk ke konsol manajemen menggunakan detail pengguna yang dibuat sebelumnya;
- pergi ke Konfigurasi Jenkins -> Manajemen Pengguna ;
- klik pada ikon roda gigi di sebelah kanan nama pengguna di mana mereka diizinkan dalam sistem;
- temukan API Token dalam daftar parameter dan klik tombol Tambahkan Token baru ;
- di bidang yang muncul, tentukan pengenal token API dan klik tombol Generate ;
- mengikuti prompt di layar, salin dan simpan token API yang dihasilkan.
Sekarang dalam pengaturan server Bitbucket , Anda dapat menentukan pengguna default untuk terhubung ke Jenkins .
Kesimpulan
Jika sebelumnya proses terdiri dari beberapa langkah:
- Unduh pembaruan ke repositori
- menunggu konfirmasi kebenaran;
- menyusun situs web dengan dokumentasi;
- memperbarui informasi tentang tuan rumah;
sekarang cukup klik satu tombol Gabung di Bitbucket. Jika setelah memeriksanya tidak diperlukan untuk membuat perubahan pada file sumber, versi dokumentasi saat ini diperbarui segera setelah mengkonfirmasi kebenaran data.
Ini sangat menyederhanakan tugas penulis teknis, menyelamatkannya dari sejumlah besar tindakan manual, dan manajer proyek mendapatkan alat yang mudah untuk melacak tambahan dokumentasi dan umpan balik.
Mengotomatiskan proses ini adalah langkah pertama dalam membangun infrastruktur manajemen dokumentasi. Di masa depan, kami berencana untuk menambahkan tes otomatis yang akan memeriksa kebenaran tautan eksternal yang digunakan dalam dokumentasi, dan juga ingin membuat objek antarmuka interaktif yang dibangun ke dalam tema siap pakai untuk Sphinx .
Terima kasih kepada mereka yang membaca ini untuk perhatian, segera kami akan terus berbagi detail membuat dokumentasi di proyek kami!