Файлы сборки
Эта страница объясняет одну идею — какой файл сборки что определяет — и не является запускаемым рабочим пространством. Веб-приложение с PostgreSQL, построенное шаг за шагом показывает её в рабочем пространстве, которое вы собираете; запишите его в собственную папку командой:
aggrega scaffold --example quickstart-webЗатем она выводит команды, которые нужно выполнить дальше:
cd quickstart-webcd 1aggrega build --release release.yaml --auto-pullexport QUICKSTART_DB_PASSWORD=choose-a-passworddocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait# then open http://127.0.0.1:8080/ in your browserПять видов файлов, у каждого свой автор
Сборка читает пять видов файлов. Каждый определяет что-то одно, и в типичной команде у каждого свой автор:
- сущность Component определяет, что представляет собой некоторый вид компонента: значения, которые может задать разработчик, настройки инфраструктуры, которые может задать оператор, что она публикует для компонентов, подключающихся к ней, и сокеты, через которые она подключается. Каталог стандартной библиотеки содержит сущности Components, нужные большинству приложений, например
core/datastore/postgresиcore/compute/server, поэтому рабочее пространство обычно не пишет ни одной; - сущность Aggregate принадлежит разработчику: какие компоненты есть у приложения и к чему подключается каждый из них;
- сущность Recipe превращает один вид компонента в файлы для одного инструмента — сервис Compose, чарт Helm, модуль Terraform;
- сущность Manifest выбирает, какая сущность Recipe реализует каждый вид компонента для одной цели;
- сущность Release называет сущности Aggregate и Manifest и задаёт настройки одного окружения. Именно её вы собираете:
aggrega build --release release.yaml.
Это разделение — ориентир: один человек может написать все пять, и сборка примет любой из них, если каждый корректен.
Сущность Aggregate: компоненты и их связи
Первый шаг примера — веб-приложение и его база данных. Его сущность Aggregate из 1/aggregate.yaml без комментариев:
spec: components: web: type: core/compute/server features: db_password: type: core/secret-value values: key: PGPASSWORD origin: "${QUICKSTART_DB_PASSWORD}" uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: database
db: type: core/datastore/postgres features: password: type: core/secret-value values: key: POSTGRES_PASSWORD origin: "${QUICKSTART_DB_PASSWORD}"Здесь ничто не называет порт, хост, пространство имён или инструмент. web подключается к db через свой сокет database, а список inject определяет, какая переменная приложения получает каждую запись, которую публикует база данных: from: называет запись, in: — переменную.
Соединение — это строка, переданная по конвейеру
Сущность Recipe базы данных публикует host, port, user и database, чтобы соединение их прочитало. Какой адрес содержит host, зависит от сущности Recipe, выбранной сущностью Manifest: имя сервиса, когда база данных работает рядом с приложением, строка-указатель, которую инструмент выделения ресурсов разрешает для управляемой базы данных, или адрес уже существующего сервера. Сборка копирует каждую опубликованную строку в переменную, названную сущностью Aggregate, и не интерпретирует её: она никогда не разрешает адрес и не проверяет его доступность.
Сущности Manifest и Release
Сущность Manifest из 1/manifest.yaml привязывает каждый вид компонента, а также вложения паролей, к сущности Recipe, которая реализует его в Docker Compose:
spec: mappings: components: type: core/compute/server:1.1.0: compose/server:2.0.0 core/datastore/postgres:1.0.0: compose/postgres:1.0.0 features: type: core/secret-value:1.0.0: compose/dotenv-secret:1.0.0Сущность Release из 1/release.yaml называет сущности Aggregate и Manifest и задаёт то, что знает только окружение, — здесь образ, который запускает приложение, порт, который оно слушает, и порт, на котором Docker Compose публикует его на loopback-адресе вашей машины (дайджест образа сокращён):
spec: aggregate: quickstart-web manifest: quickstart-web-compose components: web: infra: image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:… port: 8080 published_port: 8080 db: {}Последующие шаги примера расширяют его: кеш Redis рядом с базой данных, затем те же компоненты в AWS через Terraform, затем резервные копии базы данных.
Параметры: одна сущность Aggregate, много окружений
Значение, которое различается между окружениями, объявляется в сущности Aggregate как типизированный параметр, на него ссылаются там, где оно используется, а задаёт его каждая сущность Release. В примере Задача, запускаемая по требованию сущность Aggregate объявляет расписание своего отчёта:
spec: parameters: report_schedule: type: string default: "" components: report: type: core/compute/task values: schedule: "{{ .parameters.report_schedule }}"а сущность Release заполняет его:
spec: parameters: report_schedule: "30 2 * * 1-5"Сборка проверяет каждое значение, которое задаёт сущность Release, на соответствие типу параметра, прежде чем заполнить шаблон. Сущность Release никогда сама не пишет values компонента: она заполняет параметры, которые предоставляет сущность Aggregate, поэтому сущность Aggregate остаётся единственным местом, определяющим, какие значения меняются в зависимости от окружения. Сущность Release также может читать свои параметры из отдельного файла, parameters: { $import: ./env/prod-values.yaml }.