Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Stack APISIX — un API gateway dinamico composto come modulo

Questo esempio compila uno stack piccolo e reale — un API gateway dinamico — in manifest Kubernetes sintetizzati a partire da un unico Aggregate scritto dallo sviluppatore.

Il gateway non è un singolo componente. È un modulo: un sotto-aggregato riutilizzabile che compone due componenti a carico di lavoro singolo —

  • un gateway che termina il traffico dei client sulla sua porta proxy e non mantiene alcuno stato locale, e
  • uno store, etcd, che contiene la configurazione del gateway e la rende persistente su un volume.

Il modulo cabla il proprio arco interno dal gateway allo store ed esporta il gateway come suo endpoint pubblico proxy. L’Aggregate di primo livello importa il modulo per nome e renderizza lo stack composto; l’operatore dimensiona i componenti interni del modulo nella Release.

File

FileRuolo
aggregate.yamlIntento dello sviluppatore: importa il modulo di API gateway (core/apisix) e gli passa la chiave della Admin API del gateway da un proprio parametro.
manifest-helm-synth.yamlMappa i tipi gateway e store alle rispettive Recipes helm synth, e la Feature di credenziale che il modulo associa alla realizzazione che legge un Secret già presente nel namespace.
release-helm-synth.yamlDocumento dell’operatore per il target Kubernetes. Nomina il Secret che contiene la chiave della Admin API e dimensiona i componenti interni del modulo tramite i loro ID con ambito di modulo; tutto il resto è lasciato ai valori predefiniti dello schema.

Che cosa dimostra

  • Composizione come modulo. Una capacità a più carichi di lavoro — un API gateway che in realtà è un proxy più uno store di configurazione — è confezionata come un sotto-aggregato che compone due componenti a carico di lavoro singolo, non come un unico componente monolitico. Il modulo viene importato per nome e riutilizzato ovunque serva un gateway.
  • Un arco interno al modulo. Il gateway dichiara un uso dello store; host e porta dei provides della Recipe dello store vengono convogliati nel gateway e composti nella sua connessione a etcd. Il compilatore instrada le stringhe senza interpretarle.
  • Un endpoint pubblico. Il modulo esporta il suo gateway come proxy, il nome pubblico stabile a cui si connette un consumatore — disaccoppiato dai nomi dei componenti interni del modulo.
  • Dimensionamento dei componenti interni da parte dell’operatore. La Release indirizza i componenti interni del modulo tramite i loro ID con ambito di modulo (gateway.store, gateway.gateway) per impostarne le risorse di calcolo, senza che l’Aggregate dello sviluppatore ripeta il dimensionamento fisico.
  • Un file di configurazione montato accanto a file scritti a runtime. Il gateway legge la propria configurazione da un file in una directory in cui scrive anche all’avvio. La Recipe emette quella configurazione come ConfigMap e la monta come singolo file, così configura il gateway senza nascondere i file che il gateway vi scrive.
  • Una chiave della Admin API letta da un Secret. Il gateway amministra le sue route tramite una Admin API, e la sua chiave arriva attraverso uno slot di credenziale del gateway, che il gateway richiede finché nulla è cablato al suo socket dei modelli, come qui, quindi non esiste alcuna chiave predefinita. Il modulo riceve la chiave come parametro, admin_key, e con essa associa allo slot la Feature di credenziale core/referenced-secret; questo Aggregate dichiara un proprio parametro e glielo passa, e la Release lo soddisfa. Il Manifest mappa la Feature su k8s-existing-secret, quindi il valore è il nome di un Secret che esiste già nel namespace: il build non legge alcuna chiave e non ne renderizza alcuna, e il gateway legge la chiave da quel Secret all’avvio. Una Release che non fornisce alcun valore arresta il build, nominando il parametro.
  • Immagini riproducibili. Sia il gateway sia lo store fissano tag di immagine espliciti, quindi i manifest renderizzati fanno riferimento a immagini stabili.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example apisix-stack

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd apisix-stack

Build

Questo workspace non contiene alcun .aggrega-config.yaml, quindi le entità della libreria standard vengono risolte dal registry dell’hub, hub.aggrega.ai, e non serve alcun flag di catalogo; --auto-pull scrive durante il build il lockfile che manca a un clone appena creato:

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

Gli artefatti renderizzati finiscono sotto dist/. Il target Kubernetes renderizza manifest semplici offline — non è richiesto alcun pull di chart.

Prima di applicarli, crea nel namespace di destinazione il Secret che la Release nomina, apisix-admin-key, contenente una tua chiave sotto la chiave dati admin-key. La chiave non deve essere vuota, cosa che arresta il gateway all’avvio, e non deve essere un valore che APISIX legge come un numero o come vero o falso, come una chiave composta solo da cifre, perché in tal caso APISIX non la confronta mai con la chiave che una richiesta presenta.

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `apisix-stack`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `apisix-stack` e senza `dir`: scrive l’esempio in una nuova cartella `apisix-stack`. Poi chiama lo strumento `build` con `workspace_root` impostato su `apisix-stack`, `release` impostato su `release-helm-synth.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `apisix-stack/dist/`.

Come appare lo stack composto

Il gateway viene renderizzato come un Deployment stateless più un Service ClusterIP sulla porta proxy. La sua configurazione viene fornita come una ConfigMap montata come singolo file nella directory conf del container; la configurazione contiene il nome del Service interno al cluster dello store e, dove va la chiave della Admin API, il nome della variabile d’ambiente da cui APISIX legge la chiave quando carica il file:

apisix:
node_listen: 9080
deployment:
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: 30

Il Deployment fornisce quella variabile dal Secret, quindi la chiave non compare in alcun file renderizzato:

env:
- name: APISIX_ADMIN_KEY
valueFrom:
secretKeyRef:
name: apisix-admin-key
key: admin-key

Lo store viene renderizzato come uno StatefulSet con un volume persistente montato in /etcd-data, più un Service ClusterIP e un Service headless.