Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Стек 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 не задаёт значение, сборка останавливается с указанием параметра.
  • Воспроизводимые образы. И шлюз, и хранилище фиксируют явные теги образов, поэтому отрисованные манифесты ссылаются на стабильные образы.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example apisix-stack

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd apisix-stack

Сборка

В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:

Terminal window
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: 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

Deployment передаёт эту переменную из Secret, поэтому ключ не появляется ни в одном отрисованном файле:

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

Хранилище отрисовывается как StatefulSet с постоянным томом, смонтированным в /etcd-data, а также Service типа ClusterIP и headless Service.