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

Stack Kong — une passerelle d’API adossée à une base de données composée comme un module

Cet exemple compile une petite stack réelle — une passerelle d’API adossée à une base de données — 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 backend, PostgreSQL, 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 backend 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/kong).
manifest-helm-synth.yamlAssocie les types passerelle et backend à leurs Recipes helm synth.
release-helm-synth.yamlEnregistrement de l’opérateur pour la cible Kubernetes. Dimensionne les composants internes du module par leurs ID à portée de module ; tout ce qui est laissé aux valeurs par défaut du schéma est rendu de manière autonome.

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 une base de données 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 backend ; l’hôte, le port, l’utilisateur et la base de données des provides de la Recipe du backend sont acheminés dans la passerelle et composés en sa connexion PostgreSQL. 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.backend, gateway.gateway) pour définir les ressources de calcul, sans que l’Aggregate du développeur ne reprenne le dimensionnement physique.
  • Une étape de migration exécutée avant le service. La passerelle provisionne le schéma de sa base de données via un conteneur d’initialisation qui s’exécute jusqu’à son terme avant le démarrage du conteneur principal de la passerelle, si bien que la passerelle sert sur un schéma prêt. L’amorçage est idempotent, si bien qu’une nouvelle exécution sur une base de données déjà provisionnée n’a aucun effet.
  • Une information d’identification partagée. La passerelle s’authentifie auprès de son backend PostgreSQL, si bien que les deux partagent un seul mot de passe. Cet exemple utilise une valeur par défaut de développement partagée et écrite en ligne, si bien que la stack s’exécute de manière autonome sans aucun secret externe.
  • Images reproductibles. La passerelle comme le backend é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 kong-stack

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

Terminal window
cd kong-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.

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 `kong-stack`, appelez une fois l’outil `scaffold` avec `example` défini sur `kong-stack` et sans `dir` : il écrit l’exemple dans un nouveau dossier `kong-stack`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `kong-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 `kong-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 et une ConfigMap portant la liste d’autorisation des requêtes de sa Status API. Son Pod porte un conteneur d’initialisation de migration qui s’exécute avant le conteneur principal ; les deux portent la connexion composée à partir de l’arête vers le backend — le nom du Service interne au cluster du backend, l’utilisateur et la base de données :

env:
- name: KONG_DATABASE
value: postgres
- name: KONG_PG_HOST
value: gateway-zdbackend-default
- name: KONG_PG_PORT
value: "5432"
- name: KONG_PG_USER
value: kong
- name: KONG_PG_DATABASE
value: kong
[… omitted: the gateway's own proxy, admin and status listen addresses, and
the allowlist file its Status API includes]
- name: KONG_PG_PASSWORD
value: apppass

Les sondes de readiness et de liveness de la passerelle interrogent la Status API de Kong — GET /status/ready et GET /status — sur le port de conteneur status, si bien que cet écouteur est lié à l’adresse du Pod. Kong inclut la liste d’autorisation de la ConfigMap dans le bloc server propre à la Status API : depuis toute adresse autre que l’adresse de bouclage du Pod, il répond à un GET de /status, /status/ready ou /metrics, et refuse toute autre requête avec 403 — parmi elles POST /status/ready, qui sinon marquerait la passerelle comme en cours de drainage et la retirerait de son Service jusqu’à son redémarrage.

Le backend est rendu sous forme d’un StatefulSet avec un volume persistant monté sur /var/lib/postgresql/data, plus un Service ClusterIP et un Service headless.