Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Stack APISIX — une passerelle d’API dynamique composée comme un module

Cet exemple compile une petite stack réelle — une passerelle d’API dynamique — en manifestes Kubernetes synthétisés à partir d’un seul Aggregate écrit par le développeur.

La passerelle n’est pas un composant unique. C’est un module : un sous-agrégat réutilisable qui compose deux composants à charge de travail unique —

  • une passerelle qui termine le trafic client sur son port proxy et ne conserve aucun état local, et
  • un magasin, etcd, qui contient la configuration de la passerelle et la persiste sur un volume.

Le module câble sa propre arête interne de la passerelle vers le magasin et exporte la passerelle comme son endpoint public proxy. L’Aggregate de plus haut niveau importe le module par son nom et rend la stack composée ; l’opérateur dimensionne les composants internes du module dans la Release.

Fichiers

FichierRôle
aggregate.yamlIntention du développeur : importe le module de passerelle d’API (core/apisix) et lui transmet la clé de l’Admin API de la passerelle depuis un paramètre qui lui est propre.
manifest-helm-synth.yamlAssocie les types passerelle et magasin à leurs Recipes helm synth, et la Feature d’informations d’identification que le module rattache à la réalisation qui lit un Secret déjà présent dans le namespace.
release-helm-synth.yamlEnregistrement de l’opérateur pour la cible Kubernetes. Nomme le Secret contenant la clé de l’Admin API et dimensionne les composants internes du module par leurs ID à portée de module ; tout le reste est laissé aux valeurs par défaut du schéma.

Ce qu’il démontre

  • Composition en module. Une capacité à plusieurs charges de travail — une passerelle d’API qui est en réalité un proxy plus un magasin de configuration — est empaquetée comme un sous-agrégat composant deux composants à charge de travail unique, et non comme un composant monolithique. Le module est importé par son nom et réutilisé partout où une passerelle est nécessaire.
  • Une arête interne au module. La passerelle déclare une utilisation du magasin ; l’hôte et le port des provides de la Recipe du magasin sont acheminés dans la passerelle et composés en sa connexion etcd. Le compilateur achemine les chaînes sans les interpréter.
  • Un endpoint public. Le module exporte sa passerelle sous le nom proxy, le nom public stable auquel un consommateur se connecte — découplé des noms des composants internes du module.
  • Dimensionnement des composants internes par l’opérateur. La Release adresse les composants internes du module par leurs ID à portée de module (gateway.store, gateway.gateway) pour définir les ressources de calcul, sans que l’Aggregate du développeur ne reprenne le dimensionnement physique.
  • Un fichier de configuration monté à côté de fichiers écrits à l’exécution. La passerelle lit sa configuration depuis un fichier situé dans un répertoire où elle écrit aussi au démarrage. La Recipe émet cette configuration sous forme de ConfigMap et la monte comme un fichier unique, si bien qu’elle configure la passerelle sans masquer les fichiers que la passerelle y écrit.
  • Une clé d’Admin API lue depuis un Secret. La passerelle administre ses routes via une Admin API, et sa clé arrive par un emplacement d’informations d’identification sur la passerelle, que la passerelle exige tant que rien n’est câblé à son socket de modèles, comme ici, si bien qu’aucune clé par défaut n’existe. Le module reçoit la clé comme paramètre, admin_key, et rattache avec elle la Feature d’informations d’identification core/referenced-secret à l’emplacement ; cet Aggregate déclare un paramètre qui lui est propre et le transmet vers le bas, et la Release le satisfait. Le Manifest associe la Feature à k8s-existing-secret, si bien que la valeur est le nom d’un Secret qui existe déjà dans le namespace : le build ne lit aucune clé et n’en rend aucune, et la passerelle lit la clé depuis ce Secret à son démarrage. Une Release qui ne fournit aucune valeur arrête le build, en nommant le paramètre.
  • Images reproductibles. La passerelle comme le magasin épinglent des tags d’image explicites, si bien que les manifestes rendus référencent des images stables.

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example apisix-stack

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd apisix-stack

Build

Ce workspace ne contient aucun .aggrega-config.yaml, si bien que les entités de la bibliothèque standard sont résolues depuis le registre du hub, hub.aggrega.ai, et aucune option de catalogue n’est nécessaire ; --auto-pull écrit pendant le build le lockfile qui manque à un clone récent :

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

Les artefacts rendus atterrissent sous dist/. La cible Kubernetes rend des manifestes simples hors ligne — aucun pull de chart n’est requis.

Avant de les appliquer, créez dans le namespace cible le Secret que nomme la Release, apisix-admin-key, contenant une clé de votre choix sous la clé de données admin-key. La clé ne doit pas être vide, ce qui arrête la passerelle au démarrage, et ne doit pas être une valeur qu’APISIX lit comme un nombre ou comme vrai ou faux, par exemple une clé composée uniquement de chiffres, car APISIX ne la compare alors jamais à la clé que présente une requête.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `apisix-stack`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `apisix-stack` et sans `dir` : il écrit l’exemple dans un nouveau dossier `apisix-stack`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `apisix-stack`, `release` défini sur `release-helm-synth.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `apisix-stack/dist/`.

À quoi ressemble la stack composée

La passerelle est rendue sous forme d’un Deployment sans état plus un Service ClusterIP sur le port proxy. Sa configuration est livrée sous forme d’une ConfigMap montée comme un fichier unique dans le répertoire conf du conteneur ; la configuration porte le nom du Service interne au cluster du magasin et, là où va la clé de l’Admin API, le nom de la variable d’environnement depuis laquelle APISIX lit la clé lorsqu’il charge le fichier :

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

Le Deployment fournit cette variable depuis le Secret, si bien que la clé n’apparaît dans aucun fichier rendu :

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

Le magasin est rendu sous forme d’un StatefulSet avec un volume persistant monté sur /etcd-data, plus un Service ClusterIP et un Service headless.