Tutorial: Menyebarkan ke kluster Service Fabric

Tutorial ini mencakup beberapa kemungkinan cara penyiapan lingkungan Jenkins Anda serta berbagai cara untuk menyebarkan aplikasi Anda ke kluster Service Fabric setelah dibangun. Ikuti langkah-langkah umum ini agar berhasil mengonfigurasi Jenkins, menarik perubahan dari GitHub, membangun aplikasi, dan menyebarkannya ke kluster Anda:

  1. Pastikan Anda menginstal Prasyarat.
  2. Kemudian ikuti langkah-langkah di salah satu bagian ini untuk menyiapkan Jenkins:
  3. Setelah menyiapkan Jenkins, ikuti langkah-langkah di Membuat dan mengonfigurasi pekerjaan Jenkins untuk menyiapkan GitHub guna memicu Jenkins ketika perubahan dilakukan pada aplikasi Anda dan untuk mengonfigurasi alur pekerjaan Jenkins Anda melalui langkah build guna menarik perubahan dari GitHub dan membangun aplikasi Anda.
  4. Terakhir, konfigurasikan langkah pasca-build pekerjaan Jenkins untuk menyebarkan aplikasi Anda ke kluster Service Fabric. Ada dua cara untuk mengonfigurasi Jenkins untuk menyebarkan aplikasi Anda ke kluster:

Prasyarat

  • Pastikan Git diinstal secara lokal. Anda dapat menginstal versi Git yang sesuai dari halaman unduhan Git berdasarkan sistem operasi Anda. Jika Anda baru mengenal Git, pelajari lebih lanjut dari dokumentasi Git.
  • Artikel ini menggunakan Sampel Memulai Service Fabric di GitHub: https://github.com/Azure-Samples/service-fabric-java-getting-started agar aplikasi dapat membangun dan menyebarkan. Anda dapat melakukan fork pada repositori ini untuk mengikuti, atau, dengan beberapa modifikasi pada instruksi, gunakan proyek GitHub Anda sendiri.

Install plug-in Service Fabric di lingkungan Jenkins yang ada

Jika menambahkan plug-in Service Fabric ke lingkungan Jenkins yang ada, Anda perlu melakukan langkah-langkah berikut:

Setelah menginstal prasyarat yang diperlukan untuk lingkungan Anda, Anda dapat mencari plug-in Azure Service Fabric di pasar Jenkins dan menginstalnya.

Setelah menginstal plug-in, lewati ke depan untuk Membuat dan mengonfigurasi pekerjaan Jenkins.

Menyiapkan Jenkins di dalam kluster Service Fabric

Anda dapat mengatur Jenkins baik di dalam atau di luar kluster Service Fabric. Bagian berikut menunjukkan cara menyiapkannya di dalam kluster saat menggunakan akun penyimpanan Azure guna menyimpan status instans kontainer.

  1. Pastikan Anda memiliki kluster Linux Service Fabric dengan Docker yang diinstal. Kluster Service Fabric yang berjalan di Azure sudah terinstal Docker. Jika menjalankan kluster secara lokal (lingkungan dev OneBox), periksa apakah Docker diinstal di komputer Anda dengan perintah docker info tersebut. Jika belum, instal menggunakan perintah berikut.

    sudo apt-get install wget
    wget -qO- https://get.docker.io/ | sh
    

    Catatan

    Pastikan port 8081 ditentukan sebagai titik akhir kustom pada kluster. Jika menggunakan kluster lokal, pastikan port 8081 terbuka pada mesin host dan memiliki alamat IP yang menghadap ke publik.

  2. Kloning aplikasi menggunakan perintah berikut:

    git clone https://github.com/suhuruli/jenkins-container-application.git
    cd jenkins-container-application
    
  3. Pertahankan status kontainer Jenkins dalam berbagi file:

    1. Buat akun penyimpanan Azure di wilayah yang sama dengan kluster Anda dengan nama seperti sfjenkinsstorage1.

    2. Buat Berbagi File di Akun penyimpanan dengan nama seperti sfjenkins.

    3. Klik Sambungkan untuk berbagi file dan perhatikan nilai yang ditampilkannya di Menyambungkan dari Linux, nilainya akan terlihat mirip dengan yang di bawah ini:

      sudo mount -t cifs //sfjenkinsstorage1.file.core.windows.net/sfjenkins [mount point] -o vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777
      

    Catatan

    Untuk memasang berbagi cifs, Anda harus menginstal paket cifs-utils di node kluster.

  4. Perbarui nilai placeholder dalam skrip setupentrypoint.sh dengan detail penyimpanan azure dari langkah 2.

    vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
    
    • Ganti [REMOTE_FILE_SHARE_LOCATION] dengan nilai //sfjenkinsstorage1.file.core.windows.net/sfjenkins dari output koneksi pada langkah 2 di atas.
    • Ganti [FILE_SHARE_CONNECT_OPTIONS_STRING] dengan nilai vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777 dari langkah 2 di atas.
  5. Khusus Kluster Aman:

    Untuk mengonfigurasi penyebaran aplikasi pada kluster aman dari Jenkins, sertifikat kluster harus dapat diakses dalam kontainer Jenkins. Dalam file ApplicationManifest.xml , pada tag ContainerHostPolicies, tambahkan referensi sertifikat ini dan perbarui nilai thumbprint dengan sertifikat kluster tersebut.

    <CertificateRef Name="MyCert" X509FindValue="[Thumbprint]"/>
    

    Selain itu, tambahkan baris berikut pada tag ApplicationManifest (root) di file ApplicationManifest.xml dan perbarui nilai thumbprint dengan sertifikat kluster tersebut.

    <Certificates>
      <SecretsCertificate X509FindType="FindByThumbprint" X509FindValue="[Thumbprint]" />
    </Certificates> 
    
  6. Sambungkan ke kluster dan instal aplikasi kontainer.

    Kluster Aman

    sfctl cluster select --endpoint https://PublicIPorFQDN:19080  --pem [Pem] --no-verify # cluster connect command
    bash Scripts/install.sh
    

    Perintah sebelumnya mengambil sertifikat dalam format PEM. Jika sertifikat Anda dalam format PFX, Anda dapat menggunakan perintah berikut untuk mengonversinya. Jika file PFX Anda tidak dilindungi kata sandi, tentukan parameter passin sebagai -passin pass:.

    openssl pkcs12 -in cert.pfx -out cert.pem -nodes -passin pass:<password>
    

    Kluster Tidak Aman

    sfctl cluster select --endpoint http://PublicIPorFQDN:19080 # cluster connect command
    bash Scripts/install.sh
    

    Kluster ini menginstal kontainer Jenkins pada kluster, dan dapat dipantau menggunakan Service Fabric Explorer.

    Catatan

    Mungkin perlu beberapa menit agar gambar Jenkins diunduh di kluster.

  7. Di browser, buka http://PublicIPorFQDN:8081. Di sini menyediakan jalur kata sandi admin awal yang diperlukan untuk masuk.

  8. Lihat Service Fabric Explorer untuk menentukan node mana yang dijalankan oleh kontainer Jenkins. Secure Shell (SSH) masuk ke node ini.

    ssh user@PublicIPorFQDN -p [port]
    
  9. Dapatkan ID instans kontainer menggunakan docker ps -a.

  10. Secure Shell (SSH) masuk ke kontainer dan tempel jalur yang ditampilkan di portal Jenkins. Misalnya, jika di portal menunjukkan jalur PATH_TO_INITIAL_ADMIN_PASSWORD, jalankan perintah berikut:

    docker exec -t -i [first-four-digits-of-container-ID] /bin/bash   # This takes you inside Docker shell
    
    cat PATH_TO_INITIAL_ADMIN_PASSWORD # This displays the password value
    
  11. Di halaman Memulai Jenkins, pilih opsi Pilih plug-in untuk diinstal, pilih kotak centang Tidak Ada , dan klik instal.

  12. Buat pengguna atau pilih untuk melanjutkan sebagai admin.

Setelah menyiapkan Jenkins, lewati ke Membuat dan mengonfigurasi pekerjaan Jenkins.

Menyiapkan Jenkins di luar kluster Service Fabric

Anda dapat menyiapkan Jenkins di dalam atau di luar kluster Service Fabric. Bagian berikut menunjukkan cara menyiapkannya di luar kluster.

  1. Pastikan Docker diinstal di komputer Anda dengan menjalankan docker info di terminal. Output menunjukkan apakah layanan Docker sedang berjalan.

  2. Jika Docker tidak diinstal, jalankan perintah berikut:

    sudo apt-get install wget
    wget -qO- https://get.docker.io/ | sh
    
  3. Tarik gambar kontainer Service Fabric Jenkins: docker pull rapatchi/jenkins:latest. Gambar ini dilengkapi dengan plug-in Service Fabric Jenkins yang telah diinstal sebelumnya.

  4. Jalankan gambar kontainer: docker run -itd -p 8080:8080 rapatchi/jenkins:latest

  5. Dapatkan ID instans gambar kontainer. Anda dapat mencantumkan semua kontainer Docker dengan perintah docker ps –a

  6. Masuk ke portal Jenkins dengan langkah-langkah berikut:

    1. Masuk ke shell Jenkins dari host Anda. Gunakan empat digit pertama ID kontainer. Misalnya, jika ID kontainer adalah 2d24a73b5964, gunakan 2d24.

      docker exec -it [first-four-digits-of-container-ID] /bin/bash
      
    2. Dari shell Jenkins, dapatkan kata sandi admin untuk instans kontainer Anda:

      cat /var/jenkins_home/secrets/initialAdminPassword
      
    3. Untuk masuk ke dasbor Jenkins, buka URL berikut di browser web: http://<HOST-IP>:8080. Gunakan kata sandi dari langkah sebelumnya untuk membuka kunci Jenkins.

    4. (Opsional.) Setelah masuk untuk pertama kalinya, Anda dapat membuat akun pengguna Anda sendiri dan menggunakannya untuk langkah-langkah berikut, atau Anda dapat terus menggunakan akun administrator. Jika membuat pengguna, Anda harus melanjutkan dengan pengguna tersebut.

  7. Siapkan GitHub untuk bekerja dengan Jenkins dengan menggunakan langkah-langkah dalam Menghasilkan kunci SSH baru dan menambahkannya ke agen SSH.

    • Gunakan instruksi yang disediakan GitHub untuk menghasilkan kunci SSH, dan untuk menambahkan kunci SSH ke akun GitHub yang menghosting repositori.

    • Jalankan perintah yang disebutkan dalam tautan sebelumnya di shell Jenkins Docker (dan bukan pada host Anda).

    • Untuk masuk ke shell Jenkins dari host Anda, gunakan perintah berikut:

      docker exec -t -i [first-four-digits-of-container-ID] /bin/bash
      

Pastikan kluster atau komputer tempat gambar kontainer Jenkins yang dihosting memiliki alamat IP yang menghadap publik. Hal ini memungkinkan instans Jenkins menerima pemberitahuan dari GitHub.

Setelah menyiapkan Jenkins, lanjutkan ke bagian berikutnya, Membuat dan mengonfigurasi pekerjaan Jenkins.

Membuat dan mengonfigurasi pekerjaan Jenkins

Langkah-langkah di bagian ini menunjukkan cara mengonfigurasi pekerjaan Jenkins untuk menanggapi perubahan dalam repo GitHub, mengambil perubahan, dan membangunnya. Di akhir bagian ini, Anda diarahkan ke langkah-langkah terakhir untuk mengonfigurasi pekerjaan guna menyebarkan aplikasi berdasarkan apakah Anda menyebarkan ke lingkungan pengembangan /pengujian atau ke lingkungan produksi.

  1. Di dasbor Jenkins, pilih Item Baru.

  2. Masukkan nama item (misalnya, MyJob). Pilih proyek gaya bebas,dan klik OK.

  3. Halaman Konfigurasi pekerjaan terbuka. (Untuk mendapatkan konfigurasi dari dasbor Jenkins, klik pekerjaan, lalu klik Konfigurasi).

  4. Pada tab Umum, centang kotak untuk proyek GitHub, dan tentukan URL proyek GitHub Anda. URL ini menghosting aplikasi Service Fabric Java yang ingin Anda integrasikan dengan integrasi berkelanjutan Jenkins, alur penyebaran berkelanjutan (CI/CD) (misalnya, https://github.com/{your-github-account}/service-fabric-java-getting-started).

  5. Di tab Manajemen Kode Sumber, pilih Git. Tentukan URL repositori yang menghosting aplikasi Service Fabric Java yang ingin Anda integrasikan dengan alur Jenkins CI/CD (misalnya, https://github.com/{your-github-account}/service-fabric-java-getting-started). Anda juga dapat menentukan cabang mana yang akan dibangun (misalnya, /master).

  6. Konfigurasikan repositori GitHub Anda untuk berbicara dengan Jenkins:

    1. Pada halaman repositori GitHub Anda, buka Pengaturan> Integrasi dan Layanan.

    2. Pilih Tambahkan Layanan, ketik Jenkins,dan pilih plug-in Jenkins-GitHub.

    3. Masukkan URL webhook Jenkins Anda (secara default, seharusnya http://<PublicIPorFQDN>:8081/github-webhook/). Klik layanan tambah/perbarui.

    4. Peristiwa pengujian dikirim ke instans Jenkins Anda. Anda akan melihat tanda centang hijau oleh webhook di GitHub, dan proyek Anda akan dibangun.

  7. Pada tab Pemicu Build di Jenkins, pilih opsi build yang Anda inginkan. Untuk contoh ini, Anda ingin memicu build setiap kali dorongan ke repositori terjadi, jadi pilih pemicu kait GitHub untuk polling GITScm. (Sebelumnya, opsi ini disebut Build ketika perubahan didorong ke GitHub.)

  8. Pada tab Build , lakukan salah satu hal berikut ini tergantung apakah Anda sedang membangun aplikasi Java atau aplikasi .NET Core:

    • Untuk Aplikasi Java: Dari menu menurun Tambah langkah build , pilih Minta Skrip Gradle. Klik Tingkat Lanjut. Di menu tingkat lanjut, tentukan jalur ke Skrip build root untuk aplikasi Anda. Jalur ini mengambil build.gradle dari jalur yang ditentukan dan berfungsi dengan tepat. Untuk aplikasi ActorCounter, ini adalah: ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter.

      Tindakan Build Service Fabric Jenkins

    • Untuk Aplikasi .NET Core: Dari menu menurun Tambah langkah build, pilih Jalankan Shell. Dalam kotak perintah yang muncul, direktori harus diubah terlebih dahulu ke jalur tempat build.sh file berada. Setelah direktori diubah, build.sh skrip dapat dijalankan untuk membangun aplikasi.

      cd /var/jenkins_home/workspace/[Job Name]/[Path to build.sh]  
      ./build.sh
      

      Tangkapan layar berikut menunjukkan contoh perintah yang digunakan untuk membangun sampel Counter Service dengan nama pekerjaan Jenkins CounterServiceApplication .

      Contoh perintah yang digunakan untuk membangun layanan

  9. Untuk mengonfigurasi Jenkins guna menyebarkan aplikasi Anda ke kluster Service Fabric dalam tindakan pasca-build, Anda memerlukan lokasi sertifikat kluster tersebut di kontainer Jenkins Anda. Pilih salah satu hal berikut tergantung apakah kontainer Jenkins Anda berjalan di dalam atau di luar kluster Anda dan perhatikan lokasi sertifikat kluster:

    • Untuk Jenkins yang berjalan di dalam kluster Anda: Jalur ke sertifikat dapat ditemukan dengan menggemakan nilai variabel lingkungan Certificates_JenkinsOnSF_Code_MyCert_PEM dari dalam kontainer.

      echo $Certificates_JenkinsOnSF_Code_MyCert_PEM
      
    • Untuk Jenkins yang berjalan di luar kluster Anda: Ikuti langkah-langkah ini untuk menyalin sertifikat kluster ke kontainer Anda:

      1. Sertifikat Anda harus dalam format PEM. Jika tidak memiliki file PEM, Anda dapat membuatnya dari file PFX sertifikat. Jika file PFX Anda tidak dilindungi kata sandi, jalankan perintah berikut dari host Anda:

        openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:
        

        Jika file PFX dilindungi kata sandi, sertakan kata sandi dalam parameter -passin. Contohnya:

        openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:<password>
        
      2. Untuk mendapatkan ID kontainer untuk kontainer Jenkins Anda, jalankan docker ps dari host Anda.

      3. Salin file PEM ke kontainer Anda dengan perintah Docker berikut:

        docker cp clustercert.pem [first-four-digits-of-container-ID]:/var/jenkins_home
        

Anda hampir selesai! Tetap buka pekerjaan Jenkins. Satu-satunya tugas yang tersisa adalah mengonfigurasi langkah-langkah pasca-build untuk menyebarkan aplikasi Anda ke kluster Service Fabric:

Mengonfigurasi penyebaran menggunakan titik akhir manajemen kluster

Untuk lingkungan pengembangan dan pengujian, Anda dapat menggunakan titik akhir manajemen kluster untuk menyebarkan aplikasi Anda. Mengonfigurasi tindakan pasca-build dengan titik akhir manajemen kluster untuk menyebarkan aplikasi Anda memerlukan jumlah penyiapan paling sedikit. Jika Anda menyebarkan ke lingkungan produksi, lewati ke Depan untuk Mengonfigurasi penyebaran menggunakan kredensial Azure untuk mengonfigurasi perwakilan layanan Microsoft Entra untuk digunakan selama penyebaran.

  1. Dalam pekerjaan Jenkins, klik tab Tindakan Pasca-build.

  2. Dari drop-down Tindakan Pasca-Build, pilih Sebarkan Proyek Service Fabric.

  3. Di Konfigurasi Kluster Service Fabric, pilih tombol radio Isi Titik Akhir Manajemen Service Fabric.

  4. Untuk Host Manajemen, masukkan titik akhir koneksi untuk kluster Anda; misalnya {your-cluster}.eastus.cloudapp.azure.com.

  5. Untuk Kunci Klien dan Sertifikat Klien, masukkan lokasi file PEM di kontainer Jenkins Anda; misalnya /var/jenkins_home/clustercert.pem. (Anda menyalin lokasi sertifikat langkah terakhir Membuat dan mengonfigurasi pekerjaan Jenkins.)

  6. Di Konfigurasi Aplikasi, konfigurasikan Nama Aplikasi, Jenis Aplikasi, dan Jalur (relatif) ke bidang Manifes Aplikasi.

    Service Fabric Jenkins Post-Build Action mengonfigurasi titik akhir manajemen

  7. Klik Verifikasi Konfigurasi. Pada verifikasi yang berhasil, klik Simpan. Alur pekerjaan Jenkins Anda kini dikonfigurasi sepenuhnya. Lewati ke Langkah selanjutnya untuk menguji penyebaran Anda.

Mengonfigurasi penyebaran menggunakan kredensial Azure

Untuk lingkungan produksi, konfigurasi kredensial Azure untuk menyebarkan aplikasi Anda sangat disarankan. Bagian ini menunjukkan kepada Anda cara mengonfigurasi perwakilan layanan Microsoft Entra untuk digunakan untuk menyebarkan aplikasi Anda dalam tindakan pasca-build. Anda dapat menetapkan perwakilan layanan ke peran di direktori Anda untuk membatasi izin pekerjaan Jenkins.

Untuk lingkungan pengembangan dan pengujian, Anda dapat mengonfigurasi kredensial Azure atau titik akhir manajemen kluster guna menyebarkan aplikasi Anda. Untuk detail tentang cara mengonfigurasi titik akhir manajemen kluster, lihat Mengonfigurasi penyebaran menggunakan titik akhir manajemen kluster.

  1. Untuk membuat perwakilan layanan Microsoft Entra dan menetapkan izinnya di langganan Azure Anda, ikuti langkah-langkah dalam Menggunakan portal untuk membuat aplikasi Microsoft Entra dan perwakilan layanan. Perhatikan hal berikut:

    • Saat mengikuti langkah-langkah dalam topik, pastikan untuk menyalin dan menyimpan nilai-nilai berikut: ID Aplikasi, Kunci aplikasi, ID Direktori (ID Penyewa), dan ID Langganan. Anda memerlukannya untuk mengonfigurasi kredensial Azure di Jenkins.
    • Jika tidak memiliki izin yang diperlukan di direktori, Anda harus meminta administrator untuk memberikan izin atau membuat perwakilan layanan untuk Anda, atau Anda harus mengonfigurasi titik akhir manajemen untuk kluster Anda di Tindakan Pasca-Build untuk pekerjaan Anda di Jenkins.
    • Di bagian Buat aplikasi Microsoft Entra, Anda dapat memasukkan URL yang terbentuk dengan baik untuk URL Masuk.
    • Di bagian Menetapkan aplikasi ke Peran , Anda dapat menetapkan aplikasi Anda ke peran Pembaca di grup sumber daya untuk kluster Anda.
  2. Dalam pekerjaan Jenkins, klik tab Tindakan Pasca-build.

  3. Dari drop-down Tindakan Pasca-Build, pilih Sebarkan Proyek Service Fabric.

  4. Di Konfigurasi Kluster Service Fabric, Klik Pilih Kluster Service Fabric. Klik Tambahkan di samping Kredensial Azure. Klik Jenkins untuk memilih Penyedia Kredensial Jenkins.

  5. Di Penyedia Kredensial Jenkins, pilih Perwakilan Layanan Microsoft Azure dari menu menurun Kind.

  6. Gunakan nilai yang Anda simpan saat menyiapkan perwakilan layanan Anda pada Langkah 1 untuk mengatur bidang berikut:

    • ID Klien: ID Aplikasi
    • Rahasia Klien: Kunci aplikasi
    • ID Penyewa: ID Direktori
    • ID Langganan: ID Langganan
  7. Masukkan ID deskriptif yang Anda gunakan untuk memilih kredensial di Jenkins dan Deskripsi singkat. Kemudian klik Verifikasi Perwakilan Layanan. Jika verifikasi berhasil, klik Tambahkan.

    Service Fabric Jenkins memasukkan kredensial Azure

  8. Kembali di Konfigurasi Kluster Service Fabric, pastikan kredensial baru Anda dipilih untuk Kredensial Azure.

  9. Dari menu menurun Grup Sumber Daya , pilih grup sumber daya kluster tempat Anda ingin menyebarkan aplikasi.

  10. Dari menu menurun Service Fabric , pilih kluster tempat Anda ingin menyebarkan aplikasi.

  11. Untuk Kunci Klien dan Sertifikat Klien, masukkan lokasi file PEM di kontainer Jenkins Anda. Contoh: /var/jenkins_home/clustercert.pem.

  12. Di Konfigurasi Aplikasi, konfigurasikan Nama Aplikasi, Jenis Aplikasi, dan Jalur (relatif) ke bidang Manifes Aplikasi. Service Fabric Jenkins Post-Build Action - Mengonfigurasi kredensial Azure

  13. Klik Verifikasi Konfigurasi. Pada verifikasi yang berhasil, klik Simpan. Alur pekerjaan Jenkins Anda kini dikonfigurasi sepenuhnya. Lanjutkan ke Langkah berikutnya untuk menguji penyebaran Anda.

Memecahkan masalah plug-in Jenkins

Jika menemukan bug terkait plug-in Jenkins, ajukan permasalahan di JIRA Jenkins untuk komponen tertentu.

Ide untuk dicoba

GitHub dan Jenkins sekarang dikonfigurasi. Pertimbangkan untuk membuat beberapa perubahan sampel dalam proyek reliable-services-actor-sample/Actors/ActorCounter di fork repositori Anda, https://github.com/Azure-Samples/service-fabric-java-getting-started. Dorong perubahan Anda ke cabang master jarak jauh (atau cabang mana pun yang telah Anda konfigurasikan untuk dikerjakan). Ini memicu pekerjaan Jenkins, MyJob, yang Anda konfigurasi. Ini mengambil perubahan dari GitHub, membangunnya, dan menyebarkan aplikasi ke kluster yang Anda tentukan dalam tindakan pasca-build.

Langkah berikutnya