Mengotomatiskan konfigurasi API Management dengan menggunakan APIOps CLI

Azure API Management

Azure DevOps

Azure Pipelines

GitHub

APIOps adalah metodologi yang menerapkan konsep GitOps dan DevOps ke penyebaran API. Arsitektur ini menunjukkan cara menggunakan APIOps CLI untuk mengekstrak, meninjau, dan mempromosikan konfigurasi Azure API Management melalui alur kerja berbasis Git. Gunakan pendekatan ini untuk mengelola siklus hidup API, meningkatkan kualitas API, dan mempertahankan catatan perubahan yang dapat diaudit yang disetujui.

Arsitektur

Diagram berikut mengilustrasikan alur kerja promosi konfigurasi APIOps CLI tingkat tinggi. Tim meninjau artefak Manajemen API di Git, lalu pipeline integrasi berkelanjutan dan pengiriman berkelanjutan (CI/CD) menerapkan konfigurasi yang disetujui ke lingkungan Manajemen API target.

Unduh file Visio arsitektur ini.

Alur kerja

Konfigurasi API Management dimulai dengan mengekstrak konfigurasi API Management yang ada atau dengan menulis artefak API Management yang kompatibel dengan CLI. Alur kerja operasional dimulai dengan salah satu input artefak ini. Kedua jalur mengarah ke permintaan pull, validasi, persetujuan, dan proses penyebaran yang sama:

(A) Ekstrak terlebih dahulu: Operator API menjalankan apiops extract pada instans API Management yang sudah ada untuk membuat file artefak API Management di cabang checkout Git lokal mereka. Operator menggunakan artefak ini untuk mengusulkan garis besar atau mengambil perubahan konfigurasi yang disetujui.
(B) Code-first: Pengembang API menulis atau memperbarui spesifikasi API yang kompatibel dengan APIOps CLI, file informasi, kebijakan, dan artefak API Management terkait di cabang checkout Git lokal mereka.

Gunakan siklus hidup berikut untuk salah satu input:

Buat perubahan konfigurasi. Setelah ekstraksi awal atau pemeriksaan pembuatan artefak pertama kode, repositori konfigurasi API menjadi sumber kebenaran otoritatif untuk artefak konfigurasi API Management. Repositori mempertahankan riwayat versi dan catatan audit untuk setiap penyebaran. Untuk membuat perubahan, operator API atau pengembang membuat cabang dari cabang yang dilindungi di repositori konfigurasi API dan membuat satu perubahan logis yang terkait dengan API.
Tinjau dan validasi perubahan. Operator atau pengembang membuka pull request untuk menggabungkan cabang mereka ke dalam cabang yang dilindungi. Pemilik dan peninjau yang diperlukan dari kontrak API, kebijakan, dan konfigurasi API Management meninjau permintaan pull. Sistem CI/CD menjalankan pemeriksaan dan pengujian berikut:
- linting spesifikasi API
- Deteksi perubahan yang merusak kompatibilitas terhadap kontrak yang disetujui
- Pemindaian keamanan spesifikasi dan konten repositori
- Pengujian API yang memverifikasi perilaku yang diharapkan, autentikasi, efek kebijakan, dan dependensi back-end
Pemeriksaan ini tidak memerlukan alat Microsoft. Tim menggunakan alat apa pun yang sesuai untuk memenuhi persyaratan dukungan, keamanan, dan lisensi organisasinya.
Menyetujui input penyebaran yang tidak dapat diubah. Pemilik atau peninjau yang diwajibkan menyetujui pull request, dan pemelihara repositori yang berwenang menggabungkan perubahan yang telah ditinjau setelah semua pemeriksaan dan tinjauan yang diwajibkan berhasil. Commit yang telah digabungkan, bersifat immutable, beserta artefak cabang terlindungnya menjadi sumber kebenaran utama repositori yang dapat diaudit.

Tim melindungi cabang repositori yang dilindungi dari pendorongan langsung, memerlukan persetujuan lingkungan atau koneksi layanan untuk target sensitif, dan menggunakan identitas hak istimewa terendah terpisah untuk ekstraksi dan penerbitan. Mereka mencatat commit yang disetujui beserta pull request, ulasan, dan hasil validasinya untuk keperluan audit.
Pratinjaukan penerapan. Pipeline CI/CD menjalankan apiops publish --dry-run untuk commit yang disetujui menggunakan target yang sama dan file override tanpa memublikasikan. Pemberi persetujuan rilis meninjau sumber daya yang dibuat, diperbarui, dihapus, atau dilewati oleh dry run. Tim memperlakukan dry run yang berhasil sebagai gerbang penyebaran, bukan pengganti pengujian API otomatis.
Terbitkan dan promosikan. Setelah dry run lolos validasi, pipeline CI/CD menggunakan apiops publish untuk memublikasikan commit yang sama yang telah ditinjau. Untuk beberapa lingkungan, tim platform menjaga artefak bersama tetap stabil dan menggunakan file konfigurasi penggantian yang ditinjau untuk nilai seperti URL back-end, ID sumber daya, dan referensi rahasia. Tim mendorong komit melalui lingkungan nonproduksi sebelum produksi, dan mencegah lebih dari satu pipeline menulis ke target yang sama pada saat yang bersamaan.

Note

Konfigurasi mendukung override turunan workspace, namun tidak menerapkannya saat Anda memublikasikan. Publikasi hanya menerapkan penggantian pada kontainer ruang kerja itu sendiri. Jangan mengandalkan override turunan workspace untuk menerapkan API workspace yang spesifik untuk lingkungan, backend, nilai bernama, atau sumber daya turunan lainnya. Verifikasi pendekatan promosi alternatif untuk sumber daya tersebut, atau tunda promosi sampai masalah umum properti override dengan cakupan ruang kerja tidak diterapkan teratasi.
Validasikan dan lakukan rekonsiliasi setelah penerapan. Setelah publikasi, tim operasi menjalankan smoke test dan uji regresi otomatis, memantau manajemen API dan kesehatan sistem back-end, serta membandingkan hasil deployment dengan commit yang disetujui. Tim menyelidiki dan menyelesaikan perubahan tak terduga melalui permintaan pull daripada mengedit produksi secara langsung.

Jika operator API membuat perubahan darurat yang disetujui langsung di API Management, operator harus menjalankan ekstraksi di checkout Git, meninjau dan meng-commit perubahan artefak pada branch mereka, melakukan push branch, dan membuka pull request. Pemilik atau peninjau yang diperlukan harus meninjau dan menyetujui permintaan pull, dan penjaga repositori resmi harus menggabungkannya sehingga repositori tetap otoritatif.

Komponen

API Management adalah layanan terkelola yang membuat gateway API yang konsisten untuk layanan back-end. Dalam arsitektur ini, tersedia konfigurasi sumber yang diekstrak oleh APIOps CLI serta lingkungan target tempat CLI menerbitkan definisi API, kebijakan, produk, diagnostik, nilai bernama, dan konfigurasi didukung lainnya yang telah disetujui.
APIOps CLI adalah proyek sumber terbuka yang menyediakan perangkat untuk pendekatan APIOps yang telah ditentukan. Dalam arsitektur ini, ia mengekstrak konfigurasi API Management ke file artefak, menerbitkan artefak ke API Management, dan dapat mengacak alur kerja CI/CD.
Repositori Git menyimpan artefak API Management dan, jika berlaku, kontrak API. Ini memberikan riwayat tinjauan dan sumber kebenaran yang disetujui untuk penyebaran alur.
Sistem CI/CD menjalankan validasi, ekstraksi, dan penerbitan dengan menggunakan identitas beban kerja atau kredensial noninteraktif lain yang didukung. Dalam arsitektur ini, GitHub Actions atau Azure Pipelines menentukan alur kerja CI/CD.

Alternatif

Anda dapat mengganti atau menambah arsitektur ini dengan layanan atau pendekatan Azure lainnya, tergantung pada persyaratan fungsional dan nonfungsi beban kerja Anda. Pertimbangkan alternatif dan trade-off berikut.

Bicep atau Terraform dan APIOps dapat melayani berbagai bagian dari solusi yang sama. Tim yang memiliki konfigurasi dan infrastruktur API Management dapat menggunakan infrastruktur sebagai kode (IaC) untuk menyediakan layanan API Management dan infrastruktur pendukungnya, dan menggunakan alur IaC yang sama untuk mengelola konfigurasi API Management. Pilih pendekatan ini ketika infrastruktur dan konfigurasi berubah dan disebarkan bersama-sama, dan kapan parameter dapat mengekspresikan perbedaan antara lingkungan.

Gunakan pola APIOps saat definisi API, kebijakan, dan konfigurasi terkait memiliki pemilik terpisah atau siklus hidup rilis yang independen dari infrastruktur layanan. APIOps juga sesuai ketika Anda perlu mengekstrak konfigurasi yang ada, meninjau artefak yang berfokus pada API, atau mempromosikan konfigurasi yang disetujui yang sama di beberapa lingkungan atau instans API Management. API dan perubahan kebijakan yang lebih sering atau lebih banyak lingkungan meningkatkan nilai alur kerja khusus ini.

Faktor-faktor ini tidak memiliki ambang batas tetap. Mendasarkan keputusan terutama tentang kepemilikan, persyaratan ulasan, dan batas penyebaran. Untuk properti API yang lebih kecil dengan tingkat perubahan yang rendah, mulailah dengan alur kerja permintaan pull manual dan tambahkan jadwal ekstraksi atau otomatisasi penyebaran hanya setelah garis besar repositori dan proses persetujuan dibuat.

Detail skenario

APIOps menggunakan kontrol versi untuk mengelola API dan membuat jejak audit perubahan pada definisi API, kebijakan, produk, diagnostik, dan konfigurasi API Management lainnya. Meninjau perubahan sebelumnya dan lebih sering membantu tim mengidentifikasi penyimpangan dari standar API sebelum penyebaran. Karena lebih banyak API menggunakan proses yang sama, tim dapat meningkatkan konsistensi di seluruh properti API mereka.

Alur kerja ini menyebarkan konfigurasi API Management ke instans API Management. Ini tidak menerapkan backend API, sumber daya komputasi aplikasi atau data, jaringan, atau infrastruktur layanan API Management. Gunakan alur IaC dan aplikasi terpisah yang diatur untuk menyebarkan lapisan tersebut.

Solusi ini membantu tim:

Pertahankan gambaran umum lingkungan dan instans API Management.
Lacak perubahan penting pada API dan kebijakan.
Buat jejak audit untuk penerapan yang disetujui.
Rekonsiliasi perubahan yang disetujui yang berasal dari luar repositori.

Pilih sumber artefak dan kepemilikan

Pilih dari cara berikut agar artefak memasuki repositori dan siapa yang memilikinya sebelum Anda mengotomatiskan penyebaran:

Extract-first: Ekstrak instans API Management yang telah tervalidasi untuk menetapkan baseline awal artefak. Tinjau artefak yang sudah di-check-in sebelum menganggap repositori sebagai rujukan utama.
Kode-pertama: Simpan kontrak API, seperti deskripsi OpenAPI, dengan sumber aplikasi atau repositori APIOps. Tentukan siapa yang mengubah kontrak tersebut menjadi artefak API Management yang diterbitkan oleh pipeline. Validasikan alur kerja impor dan artefak yang dimaksud dengan instans API Management non-produksi. Jangan berasumsi bahwa tata letak sumber arbitrer dapat dikonsumsi secara langsung oleh CLI.
Tanggung jawab bersama: Tetapkan apakah pengembang API, operator platform, atau keduanya memiliki perubahan pada kebijakan, produk, diagnostik, nilai bernama, dan definisi API. Setelah garis besar diterima, rutekan setiap perubahan melalui repositori yang sama dan tinjau proses.

Kemungkinan kasus penggunaan

Organisasi yang mengembangkan dan mengelola API, termasuk organisasi dengan satu API yang diekspos melalui API Management.
Sektor yang sangat teregulasi seperti asuransi, perbankan, keuangan, dan pemerintah yang membutuhkan catatan tinjauan dan penyebaran yang dapat dilacak.

Pertimbangan

Pertimbangan ini mengimplementasikan pilar Azure Well-Architected Framework, yang merupakan serangkaian tenet panduan yang dapat Anda gunakan untuk meningkatkan kualitas beban kerja. Untuk informasi selengkapnya, lihat Well-Architected Framework.

Reliability

Keandalan membantu memastikan bahwa aplikasi Anda dapat memenuhi komitmen yang Anda buat kepada pelanggan Anda. Untuk informasi selengkapnya, lihat Daftar Periksa Ulasan Desain untuk Keandalan.

Untuk perubahan API yang tidak merusak kompatibilitas, gunakan fitur revisi di API Management untuk menerapkan dan menguji revisi yang belum menjadi revisi saat ini sebelum Anda menjadikannya sebagai revisi saat ini. Jika validasi gagal setelah rilis, pulihkan revisi sebelumnya sebagai saat ini. Gunakan versi API untuk melanggar perubahan kontrak sehingga konsumen yang ada dapat terus menggunakan versi yang lebih lama.

Koordinasikan perubahan konfigurasi API Management dengan strategi penyebaran untuk setiap back end API. Mengembalikan penerapan APIOps hanya memulihkan konfigurasi yang diwakili oleh penerapan tersebut. Ini tidak memulihkan backend yang tidak kompatibel atau tidak tersedia. Catat commit APIOps, revisi API Management, dan rilis back-end yang menyusun setiap deployment yang dipastikan baik. Uji prosedur rollback secara menyeluruh di lingkungan nonproduksi, termasuk kebijakan, nilai bernama, referensi rahasia, dependensi, dan kompatibilitas backend.

Keamanan

Keamanan memberikan perlindungan dari serangan yang disengaja dan penyalahgunaan data dan sistem yang bernilai. Untuk informasi selengkapnya, lihat Daftar periksa tinjauan desain untuk Keamanan.

Gunakan repositori dan alur sebagai jalur normal untuk menerapkan perubahan API Management. Pengembang dan operator tidak memerlukan akses tulis persisten ke instans API Management produksi. Berikan akses yang ditingkatkan hanya jika perlu, dan hanya untuk waktu yang terbatas. Rekonsiliasikan setiap perubahan yang dihasilkan dengan repositori.

Gunakan mekanisme berikut untuk melindungi repositori Git yang menyimpan artefak API Management:

Peninjauan permintaan pull: Lindungi cabang yang menyebarkan konfigurasi dan perlu ditinjau oleh peninjau yang sesuai.
Isolasi kredensial: Utamakan identitas beban kerja terfederasi jika tersedia. Simpan rahasia khusus lingkungan di penyimpanan rahasia atau lingkungan repositori yang disetujui, bukan dalam artefak atau file alur.
Integritas commit: Wajibkan commit yang ditandatangani untuk memverifikasi asal commit. Konfigurasikan perlindungan cabang untuk mencegah dorongan paksa dan penghapusan cabang, memerlukan autentikasi multifaktor bagi pengguna untuk menyetujui atau menggabungkan perubahan, dan mempertahankan riwayat permintaan penerapan dan penarikan untuk penyebaran.
Tinjauan artefak: Periksa output ekstraksi dan input publikasi untuk memastikan tidak ada rahasia, penanda yang disunting, dan nilai spesifik lingkungan yang tidak diinginkan. Validasi bahwa perubahan tidak memperluas akses API atau melemahkan kebijakan.

Kelola APIOps CLI sebagai dependensi repositori. Sematkan @azure-tools/apiops-clipackage.json ke versi yang diuji, terapkan file kunci, dan gunakan npm ci. Tinjau pengaturan identitas, variabel, pemicu, dan aturan perlindungan yang dihasilkan sebelum mengaktifkan alur produksi.

Pengoptimalan Biaya

Pengoptimalan Biaya berfokus pada cara untuk mengurangi pengeluaran yang tidak perlu dan meningkatkan efisiensi operasional. Untuk informasi selengkapnya, lihat Daftar periksa tinjauan desain untuk Pengoptimalan Biaya.

APIOps CLI adalah perangkat lunak sumber terbuka, tetapi skenario ini dikenakan biaya untuk instans API Management dan kontrol sumber dan platform CI/CD yang dipilih. Perkiraan tetap tunggal tidak disediakan karena harga API Management bervariasi menurut wilayah, tingkat, jumlah unit, model kapasitas, konfigurasi zona ketersediaan atau multiregion, dan penggunaan. Biaya CI/CD juga bergantung pada jenis runner, menit yang disertakan, konkurensi, penyimpanan, dan retensi.

Buat perkiraan khusus skenario dalam kalkulator harga Azure dan catat asumsi berikut dengan keputusan arsitektur:

Perkirakan input	Asumsi untuk merekam
Wilayah API Management	Wilayah penyebaran untuk setiap instans pengembangan, pengujian, penahapan, dan produksi.
Tingkat dan kapasitas	Tier atau tier v2, jumlah unit atau gateway, dan jam operasional untuk setiap lingkungan.
Resiliency	Setiap penyebaran zona ketersediaan atau wilayah tambahan, termasuk unit di setiap lokasi.
Biaya berbasis penggunaan	Permintaan atau operasi yang diharapkan dan ruang kerja yang berlaku, gateway yang dihost sendiri, jaringan, pemantauan, atau biaya transfer data.
Platform CI/CD	agen yang dihosting di GitHub, yang dihosting sendiri, atau agen Azure Pipelines. Alur yang diharapkan berjalan, durasi, konkurensi, penyimpanan, dan retensi log atau artefak.
Kontrol dan lisensi sumber	Jumlah pengguna dan fitur paket GitHub atau Azure DevOps berbayar.

Gunakan detail harga API Management saat ini untuk memilih model penagihan yang berlaku. Untuk CI/CD dan asumsi kontrol sumber, lihat harga Azure DevOps dan harga GitHub. Ekspor atau ambil perkiraan kalkulator, mata uangnya, tanggal harga, dan semua asumsi sehingga peninjau dapat mereproduksi dan memperbaruinya. Hitung kembali sebelum penerapan dan ketika wilayah, tingkat, jumlah unit, lingkungan, atau penggunaan pipeline berubah.

Keunggulan Operasi

Keunggulan Operasional mencakup proses operasi yang menyebarkan aplikasi dan membuatnya tetap berjalan dalam produksi. Untuk informasi selengkapnya, lihat Daftar periksa tinjauan desain untuk Keunggulan Operasional.

APIOps membuat penyebaran dapat diulang dan membuat riwayat penerapan untuk analisis pasca-perubahan. Tandai atau catat commit yang diterima oleh setiap lingkungan, simpan log pipeline, dan pantau instans API Management serta API yang bergantung padanya setelah penerapan.

Untuk beberapa lingkungan, promosikan penerapan artefak yang ditinjau yang sama melalui pengembangan, penahapan, dan produksi. Gunakan override lingkungan hanya untuk nilai yang memang harus berbeda antarlingkungan, dan tinjau file tersebut dengan kehati-hatian yang sama seperti artefak. Penimpaan anak ruang kerja tidak diterapkan pada waktu penerbitan, jadi jangan gunakan untuk promosi lingkungan. Ujilah prosedur pemulihan sebelum insiden terjadi. Revert Git tetap memerlukan validasi dan publikasi terkontrol untuk memulihkan API Management.

CLI menyediakan perintah init, extract, dan publish, serta dapat membuat kerangka pipeline GitHub Actions atau Azure DevOps. Tinjau detail perintah dalam dokumentasi APIOps CLI.

Lakukan migrasi dengan aman dari Toolkit APIOps lama

Jika proses APIOps Anda menggunakan Toolkit APIOps warisan, rencanakan untuk meningkatkan. Pendekatan tersebut menggunakan file biner Extractor dan Publisher yang terpisah serta templat pipeline. APIOps CLI menggunakan satu Node.js CLI, tetapi format artefaknya dirancang agar kompatibel dengan artefak toolkit yang ada. Perlakukan migrasi sebagai proses peralihan yang terkontrol, bukan sebagai upgrade produksi langsung di sistem yang sama.

Tandai artefak dan alur toolkit yang dikenal baik, dan pertahankan penerbit yang ada sebagai opsi putar kembali. Jangan ubah penerbit lama dan perkenalkan penerbit baru dalam penerapan yang sama.
Di cabang migrasi, gunakan versi APIOps CLI terbaru dan jalankan apiops init tanpa menggunakan --force. Perintah mendeteksi file yang berkonflik lalu berhenti alih-alih menimpanya. Bandingkan dan integrasikan secara cermat pipeline yang dihasilkan, panduan identitas, filter, dan file override.
Gunakan artefak dengan apiops publish --dry-run dan penimpaan lingkungan target terhadap instans API Management nonproduksi. Tinjau sumber daya yang akan dibuat, diperbarui, atau dihapus oleh CLI. Uji satu proses publikasi terkontrol dan validasikan API, kebijakan, nilai bernama, serta dependensi yang diterapkan.
Jangan gunakan override turunan workspace, yang tidak diterapkan saat publikasi, sebagai bagian dari desain migrasi atau promosi. Verifikasi pendekatan promosi alternatif untuk sumber daya turunan yang terdampak, atau tunda migrasinya hingga masalah umum properti penggantian cakupan ruang kerja tidak diterapkan terselesaikan.
Saat peralihan, izinkan hanya satu publisher untuk melakukan penulisan ke instans API Management. Nonaktifkan pemicu penerbit lama sebelum mengaktifkan penerbit CLI. Sebarkan penerapan yang ditinjau, dan pantau hasilnya. Pertahankan alur Toolkit dan garis besar artefak yang ditandai hingga alur kerja baru menyelesaikan siklus rilis yang berhasil.

Untuk detail kompatibilitas dan contoh migrasi perintah demi perintah, lihat Migrasi dari Toolkit APIOps.

Menyebarkan skenario ini

Ikuti Dokumentasi APIOps CLI di repositori GitHub APIOps CLI. Mulailah dengan instans API Management nonproduksi dan gunakan panduan rilis APIOps CLI saat ini. Untuk mulai menggunakan lingkungan nonproduksi, lihat Cara mengelola konfigurasi API Management dengan APIOps CLI.

Kontributor

Microsoft mempertahankan artikel ini. Kontributor berikut menulis artikel ini.

Penulis utama:

Pat Altimore | Pengembang Konten Senior
Wael Kdouh | Arsitek Solusi Utama Senior
Rishabh Saha | Arsitek Solusi Utama Senior

Untuk melihat profil LinkedIn nonpublik, masuk ke LinkedIn.

Langkah berikutnya

Saran dan Komentar

Apakah halaman ini membantu?