Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Stack de APISIX — un gateway de API dinámico compuesto como módulo

Este ejemplo compila un stack pequeño y real — un gateway de API dinámico — a manifiestos de Kubernetes sintetizados a partir de un único Aggregate escrito por el desarrollador.

El gateway no es un componente único. Es un módulo: un subagregado reutilizable que compone dos componentes de una sola carga de trabajo —

  • un gateway que termina el tráfico de los clientes en su puerto de proxy y no guarda estado local, y
  • un almacén, etcd, que guarda la configuración del gateway y la persiste en un volumen.

El módulo conecta su propia arista interna del gateway al almacén y exporta el gateway como su endpoint público proxy. El Aggregate de nivel superior importa el módulo por nombre y renderiza el stack compuesto; el operador dimensiona los componentes internos del módulo en la Release.

Archivos

ArchivoRol
aggregate.yamlIntención del desarrollador: importa el módulo de gateway de API (core/apisix) y le pasa la clave de la Admin API del gateway desde un parámetro propio.
manifest-helm-synth.yamlAsigna los tipos gateway y almacén a sus Recipes helm synth, y la Feature de credencial que vincula el módulo, a la realización que lee un Secret ya presente en el namespace.
release-helm-synth.yamlDocumento del operador para el destino Kubernetes. Nombra el Secret que contiene la clave de la Admin API y dimensiona los componentes internos del módulo por sus ID con ámbito de módulo; todo lo demás queda en los valores predeterminados del esquema.

Lo que demuestra

  • Composición como módulo. Una capacidad de varias cargas de trabajo — un gateway de API que en realidad es un proxy más un almacén de configuración — se empaqueta como un subagregado que compone dos componentes de una sola carga de trabajo, no como un único componente monolítico. El módulo se importa por nombre y se reutiliza dondequiera que se necesite un gateway.
  • Una arista interna dentro del módulo. El gateway declara un uso del almacén; el host y el puerto de los provides de la Recipe del almacén se canalizan al gateway y se componen en su conexión a etcd. El compilador enruta las cadenas sin interpretarlas.
  • Un endpoint público. El módulo exporta su gateway como proxy, el nombre público estable al que se conecta un consumidor — desacoplado de los nombres de los componentes internos del módulo.
  • Dimensionamiento de los componentes internos por parte del operador. La Release se dirige a los componentes internos del módulo por sus ID con ámbito de módulo (gateway.store, gateway.gateway) para establecer el cómputo, sin que el Aggregate del desarrollador repita el dimensionamiento físico.
  • Un archivo de configuración montado junto a archivos escritos en tiempo de ejecución. El gateway lee su configuración de un archivo en un directorio en el que también escribe al arrancar. La Recipe emite esa configuración como un ConfigMap y la monta como un solo archivo, de modo que configura el gateway sin ocultar los archivos que el gateway escribe ahí.
  • Una clave de la Admin API leída de un Secret. El gateway administra sus rutas a través de una Admin API, y su clave llega por un slot de credencial del gateway, que el gateway exige mientras no haya nada conectado a su socket de modelos, como aquí, así que no existe ninguna clave predeterminada. El módulo toma la clave como parámetro, admin_key, y vincula con ella la Feature de credencial core/referenced-secret al slot; este Aggregate declara un parámetro propio y lo transmite hacia abajo, y la Release lo satisface. El Manifest asigna la Feature a k8s-existing-secret, así que el valor es el nombre de un Secret que ya existe en el namespace: la compilación no lee ninguna clave ni renderiza ninguna, y el gateway lee la clave de ese Secret al arrancar. Una Release que no proporciona ningún valor detiene la compilación, nombrando el parámetro.
  • Imágenes reproducibles. Tanto el gateway como el almacén fijan tags de imagen explícitos, así que los manifiestos renderizados hacen referencia a imágenes estables.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example apisix-stack

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd apisix-stack

Compilación

Este workspace no lleva ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no se necesita ningún flag de catálogo; --auto-pull escribe durante la compilación el lockfile que le falta a un clon recién creado:

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

Los artefactos renderizados quedan en dist/. El destino Kubernetes renderiza manifiestos simples sin conexión — no se requiere ningún pull de chart.

Antes de aplicarlos, crea en el namespace de destino el Secret que nombra la Release, apisix-admin-key, con una clave propia bajo la clave de datos admin-key. La clave no debe estar vacía, lo que detiene el gateway al arrancar, ni ser un valor que APISIX lea como un número o como verdadero o falso, como una clave formada solo por dígitos, porque entonces APISIX nunca la compara con la clave que presenta una solicitud.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `apisix-stack`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `apisix-stack` y sin `dir`: escribe el ejemplo en una nueva carpeta `apisix-stack`. Después llama a la herramienta `build` con `workspace_root` establecido en `apisix-stack`, `release` establecido en `release-helm-synth.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `apisix-stack/dist/`.

Cómo es el stack compuesto

El gateway se renderiza como un Deployment sin estado más un Service ClusterIP en el puerto de proxy. Su configuración se entrega como un ConfigMap montado como un solo archivo en el directorio conf del contenedor; la configuración lleva el nombre del Service interno del clúster del almacén y, donde va la clave de la Admin API, el nombre de la variable de entorno de la que APISIX lee la clave cuando carga el archivo:

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

El Deployment entrega esa variable desde el Secret, así que la clave no aparece en ningún archivo renderizado:

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

El almacén se renderiza como un StatefulSet con un volumen persistente montado en /etcd-data, más un Service ClusterIP y un Service headless.