Стек APISIX — динамический API-шлюз, собранный как модуль
Этот пример компилирует небольшой реальный стек — динамический API-шлюз — в
синтезированные манифесты Kubernetes из одного Aggregate, написанного разработчиком.
Шлюз — это не один компонент. Это модуль: повторно используемый вложенный агрегат, который объединяет два компонента с одной рабочей нагрузкой —
- шлюз, который принимает клиентский трафик на своём прокси-порту и не хранит локального состояния, и
- хранилище, etcd, которое хранит конфигурацию шлюза и сохраняет её на томе.
Модуль сам связывает своё внутреннее ребро от шлюза к хранилищу и экспортирует
шлюз как свою публичную конечную точку proxy. Aggregate верхнего уровня импортирует
модуль по имени и отрисовывает собранный стек; оператор задаёт размеры внутренних
компонентов модуля в Release.
Файлы
| Файл | Роль |
|---|---|
aggregate.yaml | Намерение разработчика: импортирует модуль API-шлюза (core/apisix) и передаёт ему ключ Admin API шлюза из собственного параметра. |
manifest-helm-synth.yaml | Сопоставляет типы шлюза и хранилища с их Recipes synth helm, а сущность Feature учётных данных, которую модуль подключает, — с реализацией, читающей Secret, уже существующий в пространстве имён. |
release-helm-synth.yaml | Запись оператора для целевой платформы Kubernetes. Называет Secret, содержащий ключ Admin API, и задаёт размеры внутренних компонентов модуля по их идентификаторам в области модуля; всё остальное определяется значениями по умолчанию из схемы. |
Что демонстрирует пример
- Композиция в виде модуля. Возможность из нескольких рабочих нагрузок — API-шлюз, который на деле состоит из прокси и хранилища конфигурации, — упакована как вложенный агрегат, объединяющий два компонента с одной рабочей нагрузкой, а не как один монолитный компонент. Модуль импортируется по имени и повторно используется везде, где нужен шлюз.
- Внутреннее ребро внутри модуля. Шлюз объявляет использование
хранилища; хост и порт из
providesсущности Recipe хранилища передаются в шлюз и собираются в его подключение к etcd. Компилятор передаёт строки, не интерпретируя их. - Публичная конечная точка. Модуль экспортирует свой шлюз как
proxy— стабильное публичное имя, к которому подключается потребитель, — независимо от внутренних имён компонентов модуля. - Задание размеров внутренних компонентов оператором. Release обращается к внутренним
компонентам модуля по их идентификаторам в области модуля (
gateway.store,gateway.gateway), чтобы задать вычислительные ресурсы, и Aggregate разработчика не повторяет физические размеры. - Файл конфигурации, смонтированный рядом с файлами, записываемыми во время работы. Шлюз читает конфигурацию из файла в каталоге, в который он также пишет при запуске. Recipe выводит эту конфигурацию как ConfigMap и монтирует её как отдельный файл, поэтому она настраивает шлюз, не скрывая файлы, которые шлюз туда записывает.
- Ключ Admin API, читаемый из Secret. Шлюз управляет своими маршрутами
через Admin API, а его ключ поступает через слот учётных данных шлюза,
который шлюз требует, пока к его сокету моделей ничего не подключено, как здесь,
поэтому ключа по умолчанию нет. Модуль принимает ключ как
параметр
admin_keyи подключает с ним к слоту сущность Feature учётных данныхcore/referenced-secret; этот Aggregate объявляет собственный параметр и передаёт его ниже, а Release задаёт его значение. Manifest сопоставляет Feature сk8s-existing-secret, поэтому значение — это имя Secret, который уже существует в пространстве имён: сборка не читает ключ и не отрисовывает его, а шлюз читает ключ из этого Secret при запуске. Если Release не задаёт значение, сборка останавливается с указанием параметра. - Воспроизводимые образы. И шлюз, и хранилище фиксируют явные теги образов, поэтому отрисованные манифесты ссылаются на стабильные образы.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example apisix-stackЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd apisix-stackСборка
В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:
aggrega build --release release-helm-synth.yaml --auto-pullОтрисованные артефакты помещаются в dist/. Целевая платформа Kubernetes отрисовывает обычные
манифесты офлайн — загрузка чарта не требуется.
Перед их применением создайте в целевом пространстве имён Secret, который называет Release, — apisix-admin-key,
со своим ключом под ключом данных
admin-key. Ключ не должен быть пустым — это останавливает шлюз при запуске —
и не должен быть значением, которое APISIX читает как число или как true или false, например
ключом из одних цифр, потому что тогда APISIX никогда не сопоставит его с ключом,
предъявленным в запросе.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки сами. Если в папке рабочего пространства ещё нет папки `apisix-stack`, вызовите один раз инструмент `scaffold`, задав для `example` значение `apisix-stack` и не задавая `dir`: он запишет пример в новую папку `apisix-stack`. Затем вызовите инструмент `build`, задав для `workspace_root` значение `apisix-stack`, для `release` — `release-helm-synth.yaml`, для `auto_pull` — true и для `write` — true. Сообщите мне, какие файлы записала сборка; они находятся в `apisix-stack/dist/`.Как выглядит собранный стек
Шлюз отрисовывается как Deployment без состояния и Service типа ClusterIP на прокси-порту. Его конфигурация доставляется как ConfigMap, смонтированный как отдельный файл в каталог conf контейнера; конфигурация содержит внутрикластерное имя Service хранилища и, на месте ключа Admin API, имя переменной окружения, из которой APISIX читает ключ при загрузке файла:
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 передаёт эту переменную из Secret, поэтому ключ не появляется ни в одном отрисованном файле:
env: - name: APISIX_ADMIN_KEY valueFrom: secretKeyRef: name: apisix-admin-key key: admin-keyХранилище отрисовывается как StatefulSet с постоянным томом, смонтированным в
/etcd-data, а также Service типа ClusterIP и headless Service.