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

Файлы сборки

Эта страница объясняет одну идею — какой файл сборки что определяет — и не является запускаемым рабочим пространством. Веб-приложение с PostgreSQL, построенное шаг за шагом показывает её в рабочем пространстве, которое вы собираете; запишите его в собственную папку командой:

Terminal window
aggrega scaffold --example quickstart-web

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

Terminal window
cd quickstart-web
cd 1
aggrega build --release release.yaml --auto-pull
export QUICKSTART_DB_PASSWORD=choose-a-password
docker 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 }.