Mengintegrasikan IoT Central dengan Azure Pipelines untuk integrasi berkelanjutan dan pengiriman berkelanjutan

Integrasi berkelanjutan dan pengiriman berkelanjutan (CI/CD) mengacu pada proses pengembangan dan pengiriman perangkat lunak dalam siklus singkat dan sering menggunakan alur otomatisasi. Artikel ini menunjukkan kepada Anda cara mengotomatiskan build, pengujian, dan penyebaran konfigurasi aplikasi IoT Central. Otomatisasi ini memungkinkan tim pengembangan untuk memberikan rilis yang andal lebih sering.

Integrasi berkelanjutan dimulai dengan penerapan kode Anda ke cabang di repositori kode sumber. Setiap penerapan digabungkan dengan penerapan dari pengembang lain untuk memastikan bahwa tidak ada konflik yang diperkenalkan. Perubahan divalidasi lebih lanjut dengan membuat build dan menjalankan tes otomatis terhadap build tersebut. Proses ini pada akhirnya menghasilkan artefak, atau bundel penyebaran, untuk disebarkan ke lingkungan target. Dalam hal ini, targetnya adalah aplikasi Azure IoT Central.

Sama seperti IoT Central adalah bagian dari solusi IoT Anda yang lebih besar, IoT Central adalah bagian dari alur CI/CD Anda. Alur CI/CD Anda harus menyebarkan seluruh solusi IoT Anda dan semua konfigurasi ke setiap lingkungan dari pengembangan hingga produksi:

IoT Central adalah platform aplikasi sebagai layanan yang memiliki persyaratan penyebaran yang berbeda dari platform sebagai komponen layanan . Untuk IoT Central, Anda menyebarkan konfigurasi dan templat perangkat. Konfigurasi dan templat perangkat ini dikelola dan diintegrasikan ke dalam alur rilis Anda dengan menggunakan API.

Meskipun memungkinkan untuk mengotomatiskan pembuatan aplikasi IoT Central, Anda harus membuat aplikasi di setiap lingkungan sebelum mengembangkan alur CI/CD Anda.

Dengan menggunakan AZURE IoT Central REST API, Anda dapat mengintegrasikan konfigurasi aplikasi IoT Central ke dalam alur rilis Anda.

Panduan ini memandu Anda melalui pembuatan alur baru yang memperbarui aplikasi IoT Central berdasarkan file konfigurasi yang dikelola di GitHub. Panduan ini memiliki instruksi khusus untuk mengintegrasikan dengan Azure Pipelines, tetapi dapat disesuaikan untuk menyertakan IoT Central dalam alur rilis apa pun yang dibangun menggunakan alat seperti Tekton, Jenkins, GitLab, atau GitHub Actions.

Dalam panduan ini, Anda membuat alur yang hanya menerapkan konfigurasi IoT Central ke satu instans aplikasi IoT Central. Anda harus mengintegrasikan langkah-langkah ke dalam alur yang lebih besar yang menyebarkan seluruh solusi Anda dan mempromosikannya dari pengembangan ke QA ke praproduksi ke produksi, melakukan semua pengujian yang diperlukan di sepanjang jalan.

Skrip saat ini tidak mentransfer pengaturan berikut antara instans IoT Central: dasbor, tampilan, pengaturan kustom dalam templat perangkat, paket harga, kustomisasi UX, gambar aplikasi, aturan, pekerjaan terjadwal, pekerjaan tersimpan, dan grup pendaftaran.

Skrip saat ini tidak menghapus pengaturan dari aplikasi IoT Central target yang tidak ada dalam file konfigurasi.

Prasyarat

Anda memerlukan prasyarat berikut untuk menyelesaikan langkah-langkah dalam panduan ini:

• Dua aplikasi IoT Central - satu untuk lingkungan pengembangan Anda dan satu untuk lingkungan produksi Anda. Untuk mempelajari lebih lanjut, lihat Membuat aplikasi IoT Central.
• Dua Azure Key Vault - satu untuk lingkungan pengembangan Anda dan satu untuk lingkungan produksi Anda. Praktik terbaik adalah memiliki Key Vault khusus untuk setiap lingkungan. Untuk mempelajari selengkapnya, lihat Membuat Azure Key Vault dengan portal Azure.
• GitHub akun GitHub.
• Organisasi Azure DevOps. Untuk mempelajari selengkapnya, lihat Membuat organisasi Azure DevOps.
• PowerShell 7 untuk Windows, Mac, atau Linux. Dapatkan PowerShell.
• Modul Azure Az PowerShell diinstal di lingkungan PowerShell 7 Anda. Untuk mempelajari selengkapnya, lihat Menginstal modul Azure Az PowerShell.
• Visual Studio Code atau alat lain untuk mengedit file PowerShell dan JSON.Dapatkan Visual Studio Code.
• Klien Git. Unduh versi terbaru dari Git - Unduhan (git-scm.com).

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

Mengunduh kode sampel

Untuk memulai, fork repositori GitHub IoT Central CI/CD lalu kloning fork Anda ke komputer lokal Anda:

1. Untuk fork repositori GitHub, buka repositori GitHub IoT Central CI/CD dan pilih Fork.

2. Kloning fork repositori Anda ke komputer lokal Anda dengan membuka jendela konsol atau bash dan menjalankan perintah berikut.

   git clone https://github.com/{your GitHub username}/iot-central-CICD-sample
   

Membuat perwakilan layanan

Meskipun Azure Pipelines dapat berintegrasi langsung dengan brankas kunci, alur memerlukan perwakilan layanan untuk beberapa interaksi brankas kunci dinamis seperti mengambil rahasia untuk tujuan ekspor data.

Untuk membuat perwakilan layanan yang dilingkup ke langganan Anda:

1. Jalankan perintah berikut untuk membuat perwakilan layanan baru:

   az ad sp create-for-rbac -n DevOpsAccess --scopes /subscriptions/{your Azure subscription Id} --role Contributor
   

2. Catat kata sandi, appId, dan penyewa saat Anda membutuhkan nilai-nilai ini nanti.

3. Tambahkan kata sandi perwakilan layanan sebagai rahasia yang dipanggil SP-Password ke brankas kunci produksi Anda:

   az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}
   

4. Berikan izin perwakilan layanan untuk membaca rahasia dari brankas kunci:

   az keyvault set-policy --name {your production key vault name} --secret-permissions get list --spn {the appId of the service principal}
   

Hasilkan token IoT Central API

Dalam panduan ini, alur Anda menggunakan token API untuk berinteraksi dengan aplikasi IoT Central Anda. Anda juga dapat menggunakan perwakilan layanan.

Catatan

Token IoT Central API kedaluwarsa setelah satu tahun.

Selesaikan langkah-langkah berikut untuk aplikasi IoT Central pengembangan dan produksi Anda.

1. Di aplikasi IoT Central Anda, pilih Izin lalu token API.

2. Pilih baru.

3. Beri nama token, tentukan organisasi tingkat atas di aplikasi Anda, dan atur peran ke Administrator Aplikasi.

4. Catat token API dari aplikasi IoT Central pengembangan Anda. Anda menggunakannya nanti saat menjalankan skrip IoTC-Config.ps1 .

5. Simpan token yang dihasilkan dari aplikasi IoT Central produksi sebagai rahasia yang dipanggil API-Token ke brankas kunci produksi:

   az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'
   

Membuat file konfigurasi

Langkah-langkah ini menghasilkan file konfigurasi JSON untuk lingkungan pengembangan Anda berdasarkan aplikasi IoT Central yang ada. Anda juga mengunduh semua templat perangkat yang ada dari aplikasi.

1. Jalankan skrip PowerShell 7 berikut ini di salinan lokal repositori IoT Central CI/CD:

   cd .\iot-central-CICD-sample\PowerShell\
   .\IoTC-Config.ps1
   

2. Ikuti instruksi untuk masuk ke akun Azure Anda.

3. Setelah Anda masuk, skrip menampilkan menu opsi Konfigurasi IoTC. Skrip dapat menghasilkan file konfigurasi dari aplikasi IoT Central yang ada dan menerapkan konfigurasi ke aplikasi IoT Central lain.

4. Pilih opsi 1 untuk menghasilkan file konfigurasi.

5. Masukkan parameter yang diperlukan dan tekan Enter:

   • Token API yang Anda buat untuk aplikasi IoT Central pengembangan Anda.
   • Subdomain aplikasi IoT Central pengembangan Anda.
   • Masukkan .. \Config\Dev sebagai folder untuk menyimpan file konfigurasi dan templat perangkat.
   • Nama brankas kunci pengembangan Anda.

6. Skrip membuat folder yang disebut Konfigurasi IoTC di folder Config\Dev di salinan lokal repositori Anda. Folder ini berisi file konfigurasi dan folder yang disebut Model Perangkat untuk semua templat perangkat di aplikasi Anda.

Mengubah file konfigurasi

Sekarang setelah Anda memiliki file konfigurasi yang mewakili pengaturan untuk instans aplikasi IoT Central pengembangan Anda, buat perubahan yang diperlukan sebelum Anda menerapkan konfigurasi ini ke instans aplikasi IoT Central produksi Anda.

1. Buat salinan folder Dev yang dibuat sebelumnya dan sebut saja Produksi.

2. Buka IoTC-Config.json di folder Produksi menggunakan editor teks.

3. File memiliki beberapa bagian. Namun, jika aplikasi Anda tidak menggunakan pengaturan tertentu, bagian tersebut dihilangkan dari file:

   {
     "APITokens": {
       "value": [
         {
           "id": "dev-admin",
           "roles": [
             {
               "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
             }
           ],
           "expiry": "2023-05-31T10:47:08.53Z"
         }
       ]
     },
     "data exports": {
       "value": [
         {
           "id": "5ad278d6-e22b-4749-803d-db1a8a2b8529",
           "displayName": "All telemetry to blob storage",
           "enabled": false,
           "source": "telemetry",
           "destinations": [
             {
               "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63"
             }
           ],
           "status": "notStarted"
         }
       ]
     },
     "device groups": {
       "value": [
         {
           "id": "66f41d29-832d-4a12-9e9d-18932bee3141",
           "displayName": "MXCHIP Getting Started Guide - All devices"
         },
         {
           "id": "494dc749-0963-4ec1-89ff-e1de2228e750",
           "displayName": "RS40 Occupancy Sensor - All devices"
         },
         {
           "id": "dd87877d-9465-410b-947e-64167a7a1c39",
           "displayName": "Cascade 500 - All devices"
         },
         {
           "id": "91ceac5b-f98d-4df0-9ed6-5465854e7d9e",
           "displayName": "Simulated devices"
         }
       ]
     },
     "organizations": {
       "value": []
     },
     "roles": {
       "value": [
         {
           "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
           "displayName": "Builder"
         },
         {
           "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
           "displayName": "Administrator"
         },
         {
           "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
           "displayName": "Operator"
         }
       ]
     },
     "destinations": {
       "value": [
         {
           "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
           "displayName": "Blob destination",
           "type": "blobstorage@v1",
           "authorization": {
             "type": "connectionString",
             "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourexportaccount;AccountKey=*****;EndpointSuffix=core.windows.net",
             "containerName": "dataexport"
           },
           "status": "waiting"
         }
       ]
     },
     "file uploads": {
       "connectionString": "FileUpload",
       "container": "fileupload",
       "sasTtl": "PT1H"
     },
     "jobs": {
       "value": []
     }
   }
   

4. Jika aplikasi Anda menggunakan unggahan file, skrip akan membuat rahasia di brankas kunci pengembangan Anda dengan nilai yang ditampilkan di connectionString properti . Buat rahasia dengan nama yang sama di brankas kunci produksi Anda yang berisi string koneksi untuk akun penyimpanan produksi Anda. Contohnya:

   az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'
   

5. Jika aplikasi Anda menggunakan ekspor data, tambahkan rahasia untuk tujuan ke brankas kunci produksi. File konfigurasi tidak berisi rahasia aktual untuk tujuan Anda, rahasia disimpan di brankas kunci Anda.

6. Perbarui rahasia dalam file konfigurasi dengan nama rahasia di brankas kunci Anda.

   Tipe tujuan	Properti yang akan diubah
   Antrean Microsoft Azure Service Bus	connectionString
   Topik Service Bus	connectionString
   Azure Data Explorer	clientSecret
   Azure Blob Storage	connectionString
   Event Hubs	connectionString
   Webhook Tanpa Autentikasi	T/A

   Contohnya:

   "destinations": {
     "value": [
       {
         "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
         "displayName": "Blob destination",
         "type": "blobstorage@v1",
         "authorization": {
           "type": "connectionString",
           "connectionString": "Storage-CS",
           "containerName": "dataexport"
         },
         "status": "waiting"
       }
     ]
   }
   

7. Untuk mengunggah folder Konfigurasi ke repositori GitHub Anda, jalankan perintah berikut dari folder IoTC-CICD-howto .

    git add Config
    git commit -m "Adding config directories and files"
    git push
   

Buat alur

1. Buka organisasi Azure DevOps Anda di browser web dengan masuk ke https://dev.azure.com/{your DevOps organization}
2. Pilih Proyek baru untuk membuat proyek baru.
3. Beri nama proyek Anda dan deskripsi opsional lalu pilih Buat.
4. Pada halaman Selamat Datang di proyek , pilih Alur lalu Buat Alur.
5. Pilih GitHub sebagai lokasi kode Anda.
6. Pilih Otorisasi AzurePipelines untuk mengotorisasi Azure Pipelines untuk mengakses akun GitHub Anda.
7. Pada halaman Pilih repositori , pilih fork Anda dari repositori GitHub IoT Central CI/CD.
8. Ketika diminta untuk masuk ke GitHub dan memberikan izin bagi Azure Pipelines untuk mengakses repositori, pilih Setujui & instal.
9. Pada halaman Konfigurasikan alur Anda, pilih Alur pemula untuk memulai. azure-pipelines.yml ditampilkan untuk Anda edit.

Membuat grup variabel

Cara mudah untuk mengintegrasikan rahasia brankas kunci ke dalam alur adalah melalui grup variabel. Gunakan grup variabel untuk memastikan rahasia yang tepat tersedia untuk skrip penyebaran Anda. Untuk membuat grup variabel:

1. Pilih Pustaka di bagian Alur menu di sebelah kiri.

2. Pilih + Grup variabel.

3. Masukkan keyvault sebagai nama untuk grup variabel Anda.

4. Aktifkan tombol untuk menautkan rahasia dari brankas kunci Azure.

5. Pilih langganan Azure Anda dan otorisasi. Kemudian pilih nama brankas kunci produksi Anda.

6. Pilih Tambahkan untuk mulai menambahkan variabel ke grup.

7. Tambahkan rahasia berikut:

   • Kunci API IoT Central untuk aplikasi produksi Anda. Kau menyebut rahasia API-Token ini saat kau membuatnya.
   • Kata sandi untuk perwakilan layanan yang Anda buat sebelumnya. Kau menyebut rahasia SP-Password ini saat kau membuatnya.

8. Pilih OK.

9. Pilih Simpan untuk menyimpan grup variabel.

Konfigurasikan alur Anda

Sekarang konfigurasikan alur untuk mendorong perubahan konfigurasi ke aplikasi IoT Central Anda:

1. Pilih Alur di bagian Alur menu di sebelah kiri.

2. Ganti konten YAML alur Anda dengan YAML berikut. Konfigurasi mengasumsikan brankas kunci produksi Anda berisi:

   • Token API untuk aplikasi IoT Central produksi Anda dalam rahasia yang disebut API-Token.
   • Kata sandi perwakilan layanan Anda dalam rahasia yang disebut SP-Password.

   Ganti nilai untuk -AppName dan -KeyVault dengan nilai yang sesuai untuk instans produksi Anda.

   Anda membuat catatan dan -AppId-TenantId ketika Anda membuat perwakilan layanan Anda.

   trigger:
   - master
   variables:
   - group: keyvault
   - name: buildConfiguration
     value: 'Release'
   steps:
   - task: PowerShell@2
     displayName: 'IoT Central'
     inputs:
       filePath: 'PowerShell/IoTC-Task.ps1'
       arguments: '-ApiToken "$(API-Token)" -ConfigPath "Config/Production/IoTC Configuration" -AppName "{your production IoT Central app name}" -ServicePrincipalPassword (ConvertTo-SecureString "$(SP-Password)" -AsPlainText -Force) -AppId "{your service principal app id}" -KeyVault "{your production key vault name}" -TenantId "{your tenant id}"'
       pwsh: true
       failOnStderr:  true
   

3. Pilih Simpan dan jalankan.

4. File YAML disimpan ke repositori GitHub Anda, jadi Anda perlu memberikan pesan penerapan lalu pilih Simpan dan jalankan lagi.

Alur Anda diantrekan. Mungkin perlu waktu beberapa menit sebelum berjalan.

Saat pertama kali menjalankan alur, Anda diminta untuk memberikan izin bagi alur untuk mengakses langganan Anda dan mengakses brankas kunci Anda. Pilih Izinkan lalu Izinkan lagi untuk setiap sumber daya.

Ketika pekerjaan alur Anda berhasil diselesaikan, masuk ke aplikasi IoT Central produksi Anda dan verifikasi konfigurasi diterapkan seperti yang diharapkan.

Mempromosikan perubahan dari pengembangan ke produksi

Sekarang setelah Anda memiliki alur yang berfungsi, Anda dapat mengelola instans IoT Central Anda secara langsung dengan menggunakan perubahan konfigurasi. Anda dapat mengunggah templat perangkat baru ke folder Model Perangkat dan membuat perubahan langsung ke file konfigurasi. Pendekatan ini memungkinkan Anda memperlakukan konfigurasi aplikasi IoT Central Anda sama dengan kode lainnya.

Langkah selanjutnya

Sekarang setelah Anda tahu cara mengintegrasikan konfigurasi IoT Central ke dalam alur CI/CD Anda, langkah selanjutnya yang disarankan adalah mempelajari cara Mengelola dan memantau aplikasi IoT Central.