Stack APISIX — gateway API dinamis yang disusun sebagai modul
Contoh ini mengompilasi sebuah stack kecil yang nyata — sebuah gateway API dinamis — menjadi
manifest Kubernetes hasil sintesis dari satu Aggregate yang ditulis oleh Developer.
Gateway ini bukan satu komponen tunggal. Ia adalah sebuah modul: sub-aggregate yang dapat digunakan ulang dan menyusun dua komponen dengan satu workload —
- sebuah gateway yang mengakhiri lalu lintas klien pada port proxy-nya dan tidak menyimpan state lokal, dan
- sebuah store, etcd, yang menyimpan konfigurasi gateway dan mempersistensikannya pada sebuah volume.
Modul ini menghubungkan edge internalnya sendiri dari gateway ke store dan mengekspor
gateway sebagai endpoint publiknya proxy. Aggregate tingkat atas mengimpor
modul tersebut berdasarkan nama dan merender stack yang tersusun; operator menentukan ukuran
komponen internal modul di dalam Release.
Berkas
| Berkas | Peran |
|---|---|
aggregate.yaml | Intent Developer: mengimpor modul gateway API (core/apisix) dan meneruskan kepadanya kunci Admin API gateway dari parameternya sendiri. |
manifest-helm-synth.yaml | Memetakan tipe gateway dan store ke Recipes synth helm-nya, serta Feature kredensial yang dilampirkan modul ke realisasi yang membaca Secret yang sudah ada di namespace. |
release-helm-synth.yaml | Catatan operator untuk target Kubernetes. Menyebutkan Secret yang menyimpan kunci Admin API, dan menentukan ukuran komponen internal modul berdasarkan ID yang berlingkup modul; selebihnya diserahkan pada nilai default schema. |
Apa yang didemonstrasikan
- Komposisi sebagai modul. Sebuah kapabilitas multi-workload — gateway API yang sebenarnya adalah proxy ditambah store konfigurasi — dikemas sebagai sub-aggregate yang menyusun dua komponen dengan satu workload, bukan sebagai satu komponen monolitik. Modul ini diimpor berdasarkan nama dan digunakan ulang di mana pun gateway dibutuhkan.
- Edge internal di dalam modul. Gateway mendeklarasikan penggunaan
store; host dan port
providesdari Recipe store dialirkan ke gateway dan disusun menjadi koneksi etcd-nya. Compiler merutekan string tersebut tanpa menafsirkannya. - Endpoint publik. Modul mengekspor gateway-nya sebagai
proxy, nama publik yang stabil tempat konsumen terhubung — terpisah dari nama komponen internal modul. - Penentuan ukuran komponen internal oleh operator. Release merujuk komponen
internal modul berdasarkan ID yang berlingkup modul (
gateway.store,gateway.gateway) untuk mengatur compute, tanpa Aggregate milik developer menyatakan ulang ukuran fisik. - Berkas konfigurasi yang di-mount berdampingan dengan berkas yang ditulis saat runtime. Gateway membaca konfigurasinya dari sebuah berkas di direktori yang juga ditulisinya saat startup. Recipe mengeluarkan konfigurasi tersebut sebagai ConfigMap dan me-mount-nya sebagai satu berkas, sehingga berkas itu mengonfigurasi gateway tanpa menutupi berkas yang ditulis gateway di sana.
- Kunci Admin API yang dibaca dari Secret. Gateway mengelola rutenya
melalui Admin API, dan kuncinya diterima melalui slot kredensial pada
gateway, yang diwajibkan gateway selama tidak ada yang terhubung ke socket models-nya,
seperti di sini, sehingga tidak ada kunci default. Modul menerima kunci tersebut sebagai
parameter,
admin_key, dan melampirkan Feature kredensialcore/referenced-secretke slot tersebut bersamanya; Aggregate ini mendeklarasikan parameternya sendiri dan meneruskannya ke bawah, dan Release memenuhinya. Manifest memetakan Feature tersebut kek8s-existing-secret, sehingga nilainya adalah nama Secret yang sudah ada di namespace: build tidak membaca kunci dan tidak merender kunci apa pun, dan gateway membaca kunci dari Secret tersebut saat mulai berjalan. Release yang tidak menyediakan nilai akan menghentikan build, dengan menyebutkan parameter tersebut. - Image yang dapat direproduksi. Gateway maupun store sama-sama menyematkan tag image yang eksplisit, sehingga manifest yang dirender merujuk image yang stabil.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example apisix-stackKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd apisix-stackBuild
Workspace ini tidak memuat .aggrega-config.yaml, sehingga entitas pustaka standar di-resolve dari registry hub, hub.aggrega.ai, dan flag katalog tidak diperlukan; --auto-pull menulis lockfile yang tidak dimiliki clone baru selama build:
aggrega build --release release-helm-synth.yaml --auto-pullArtefak yang dirender ditempatkan di bawah dist/. Target Kubernetes merender manifest
biasa secara offline — tidak diperlukan penarikan chart.
Sebelum menerapkannya, buat Secret yang disebutkan Release, apisix-admin-key,
di namespace target, yang menyimpan kunci milik Anda sendiri di bawah kunci data
admin-key. Kunci tersebut tidak boleh kosong, karena hal itu menghentikan gateway saat start-up,
dan tidak boleh berupa nilai yang dibaca APISIX sebagai angka atau sebagai true atau false, seperti
kunci yang seluruhnya digit, karena APISIX kemudian tidak pernah mencocokkannya dengan kunci yang
diajukan oleh permintaan.
Dengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `apisix-stack`, panggil tool `scaffold` sekali dengan `example` diatur ke `apisix-stack` dan tanpa `dir`: tool itu menulis contoh ke folder baru `apisix-stack`. Lalu panggil tool `build` dengan `workspace_root` diatur ke `apisix-stack`, `release` diatur ke `release-helm-synth.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu berada di bawah `apisix-stack/dist/`.Seperti apa stack yang tersusun
Gateway dirender sebagai Deployment stateless ditambah Service ClusterIP pada port proxy. Konfigurasinya dikirimkan sebagai ConfigMap yang di-mount sebagai satu berkas ke direktori conf container; konfigurasi tersebut memuat nama Service in-cluster milik store dan, di tempat kunci Admin API berada, nama variabel lingkungan yang dibaca APISIX untuk mendapatkan kunci saat memuat berkas:
apisix: node_listen: 9080deployment: role: traditional role_traditional: config_provider: etcd admin: [… omitted: the client range the Admin API accepts] admin_key: - name: admin key: ${{APISIX_ADMIN_KEY}} role: admin admin_listen: ip: 0.0.0.0 port: 9180 etcd: host: - "http://gateway-zdstore-default:2379" prefix: "/apisix" timeout: 30Deployment mengirimkan variabel tersebut dari Secret, sehingga kunci tidak muncul di berkas hasil render mana pun:
env: - name: APISIX_ADMIN_KEY valueFrom: secretKeyRef: name: apisix-admin-key key: admin-keyStore dirender sebagai StatefulSet dengan volume persisten yang di-mount di
/etcd-data, ditambah Service ClusterIP dan Service headless.