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

Один контракт, три реализации

База данных PostgreSQL и приложение, которое её читает, развёрнутые тремя разными способами из одной неизменной сущности Aggregate: PostgreSQL, работающий в кластере, PostgreSQL в виде управляемого облачного экземпляра и сервер PostgreSQL, который существовал ещё до развёртывания этой сущности Release.

Урок в том, что не меняется. Приложение один раз называет ключи, которые ему нужны от базы данных, и имена, под которыми их следует передать. Оно так и не узнаёт, какой из трёх вариантов ответил. Компилятор тоже этого не узнаёт: он читает ключи, опубликованные выбранной сущностью Recipe, и маршрутизирует строки.

Единственное, что меняется

.-- helm/postgres ---------- a StatefulSet in the cluster
/
core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform
one Component \
one contract '- helm/postgres-external -- a server that already exists

Три сущности Recipes реализуют одну и ту же сущность Component. Каждая публикует одни и те же ключи provides — host, port, user, database, protocol, а также ключи, указывающие, где сборщик метрик находит метрики базы данных; во всех трёх они пусты. Какая из них работает, определяет одна строка в Manifest.

Файлы

  • aggregate.yaml — намерение разработчика и один и тот же документ для всех трёх развёртываний: компонент db типа core/datastore/postgres, компонент app, который его использует (uses), и пять ключей, которые запрашивает приложение. Здесь не названы ни целевая платформа, ни облако, ни Recipe.
  • manifest-selfhosted.yaml, manifest-managed.yaml, manifest-external.yaml — сопоставления Ops. Каждое выбирает свою реализацию одной строкой: какой Recipe привязывает тип компонента PostgreSQL. Управляемое сопоставление также привязывает сущность Feature резервного копирования, которую подключают его сущности Releases.
  • release-selfhosted.yaml, release-managed.yaml, release-external.yaml — параметры, которые оператор задаёт в каждой сущности Release: хранилище и версия движка для развёртывания внутри кластера, хранилище, HA и подключение core/backup для управляемого и адрес существующего сервера для внешнего.
  • release-managed-dns.yaml — ещё раз управляемый Release, теперь с DNS-именем, которое оператор даёт экземпляру, чтобы приложение получило имя, которое оно может разрешить.
  • catalog/ — собственный Component приложения и единственный Recipe, который его рендерит. Всё, что относится к базе данных, берётся из стандартной библиотеки без изменений.

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

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

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

Terminal window
aggrega scaffold --example postgres-three-realizations

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

Terminal window
cd postgres-three-realizations

Сборка

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull записывает lock-файл каждой сущности Release при её первой сборке; последующим сборкам флаг не нужен. Каждая сборка пишет в dist/, и сборка добавляет свои файлы, а не очищает то, что оставила предыдущая. Удаляйте dist/ между запусками, чтобы видеть вывод одной реализации отдельно:

Terminal window
rm -rf dist && aggrega build --release release-managed.yaml

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке Workspace ещё нет папки `postgres-three-realizations`, вызовите один раз инструмент `scaffold`, задав для `example` значение `postgres-three-realizations` и не задавая `dir`: он запишет пример в новую папку `postgres-three-realizations`. Затем вызовите инструмент `build` по одному разу для каждой сущности Release в таком порядке — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` и `release-external.yaml` — каждый раз задавая для `workspace_root` значение `postgres-three-realizations`, для `release` — этот файл, для `auto_pull` — true и для `write` — true. Сообщите мне, какие файлы записала каждая сборка; они находятся в `postgres-three-realizations/dist/`.

Что генерирует каждый вариант

Самостоятельное размещение — сервер запускает само развёртывание

helm/postgres синтезирует базу данных в кластере: StatefulSet, Service типа ClusterIP и headless Service. provides.host — это просто имя этого Service, поэтому приложение обращается к нему через DNS внутри кластера.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

Управляемый вариант — сервер запускает облачный провайдер

terraform/postgres-rds выдаёт aws_db_instance в виде Terraform HCL, а заданные оператором параметр размера ha и подключение core/backup отображаются на собственные настройки экземпляра: retention_days: 14 из подключения становится backup_retention_period = 14 экземпляра. Приложение по-прежнему генерируется для Kubernetes: две стороны этого развёртывания встречаются на опубликованном контракте базы данных, а не на общей целевой платформе.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

Это значение — не имя хоста, и ничто в этой сборке не превращает его в имя хоста. Адрес экземпляра RDS не существует, пока экземпляр не создан, поэтому компилятору, работающему заранее, нечего искать. Recipe публикует ссылку Terraform на выход собственного модуля базы данных; компилятор передаёт её через ребро без изменений, Recipe приложения получает её дословно, и она попадает в манифест Kubernetes в виде тех самых символов, что показаны выше. Контейнер получает именно этот текст.

С DB_PORT всё иначе: он генерируется как "5432", потому что Recipe задаёт порт экземпляра из Release и публикует то же значение, известное ещё до того, как что-либо создано.

Нативное связывание двух компонентов целевая платформа выполняет внутри собственного вывода, поэтому здесь его выполнять негде. Два конца этого ребра генерируются через разные целевые платформы — база данных в Terraform HCL, приложение в манифест Kubernetes, — а ссылка Terraform имеет смысл только внутри конфигурации Terraform. При пересечении этой границы опубликованное значение доставляется как текст, как любая другая строка. Потребитель, сгенерированный в Terraform как Recipe source: в той же корневой конфигурации, что и база данных, получает ту же ссылку как один из аргументов своего модуля, и там Terraform её разрешает.

Это общее правило, а не особый случай для RDS: всё, что зависит от состояния работающей системы, выражается как детерминированный указатель, который разрешает среда выполнения, и никогда — как значение, которое получает компилятор. Задача компилятора — доставить указатель без изменений. Добиться того, чтобы он разрешался там, куда попадает, — задача автора Recipe: опубликуйте адрес, которым может воспользоваться принимающая сторона, или дайте обоим компонентам Recipes, генерирующие вывод для одной и той же целевой платформы.

Как дать экземпляру имя, которое приложение может разрешить

terraform/postgres-rds принимает первый из этих вариантов как параметр, задаваемый оператором. release-managed-dns.yaml — это управляемый Release с одним дополнением: DNS-именем, которое оператор даёт экземпляру:

db:
infra:
overrides:
host: db.internal.example.net

Recipe публикует это имя как host вместо ссылки Terraform, и приложение получает его:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
переменнаяrelease-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

Это единственная строка вывода, которая меняется. Recipe не создаёт ни DNS-записи, ни псевдонима для имени, и сборка его не ищет: компилятор передаёт его ровно так же, как передавал ссылку. Направить db.internal.example.net на экземпляр, когда тот появится, — записью в собственной DNS-зоне оператора, указывающей на адрес экземпляра, — задача оператора, за пределами Release. Этот ключ — тот же, из которого вариант со ссылкой на внешний сервер ниже читает тот же адрес; этот Recipe принимает его как простое имя или IP-литерал, а значение со схемой, путём, пользователем или портом останавливает сборку, поскольку порт — это infra.port из Release, а потребитель составляет подключение из этих двух значений.

Потребитель, сгенерированный в ту же конфигурацию Terraform, что и база данных, тоже получает имя и вместе с этим теряет порядок, который давала ссылка: Terraform обрабатывает модуль после модуля, на который тот ссылается, а имя ни на что не ссылается. Порядок восстанавливается, если поместить такого потребителя в отдельную границу, которая использует тот же directory:, что и база данных, и имеет более поздний syncWave:.

Внешний вариант — сервер не запускает никто в этом развёртывании

helm/postgres-external вообще ничего не создаёт. Весь его вывод — один Service, который сопоставляет имя внутри кластера с адресом, заданным в Release:

dist/stack/helm/db-service.yaml
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]
spec:
type: ExternalName
externalName: postgres.data.example.net
ports:
- port: 5432

Ни StatefulSet, ни тома, ни контейнера — жизненный цикл сервера целиком находится за пределами этого развёртывания. Адрес берётся из Release:

db:
infra:
overrides:
host: postgres.data.example.net
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

Сослаться на сервер — не то же самое, что взять его под управление. Этот Recipe обращается к серверу, который остаётся во внешнем владении; ничто здесь не передаёт его под управление развёртывания и ничто здесь его не изменит.

Если не указать адрес, сборка остановится и сообщит об этом. У внешнего сервера либо есть адрес, либо нет ничего, поэтому Recipe отказывается работать, а не создаёт Service, который служит псевдонимом для пустого имени:

[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]
assertion failed: the Manifest selects the referenced realization of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

Сравнение, ради которого всё затевалось

Отрендеренное окружение приложения, все три варианта рядом:

переменнаясобственный хостингуправляемаявнешняя
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

Те же переменные, в том же порядке, каждый раз. Меняется только строка за одной из них. Recipe приложения не называет ни одной из переменных DB_: он выдаёт то, во что разрешилось ребро uses, и поэтому один Recipe рендерится без изменений для всех трёх баз данных.

И компилятор не знает, чем являются эти строки. db-default — имя Service в Kubernetes, ${module.db.address} — ссылка Terraform, postgres.data.example.net — DNS-имя; для компилятора это три строки, которые Recipe опубликовал под ключом host, а ребро запросило доставить как DB_HOST. Он не проверяет, что какая-либо из них маршрутизируема, что порт является числом или что компонент с именем db является базой данных. Он сопоставил ребро по метке, которую несёт Component, прочитал ключ, объявленный контрактом, и перенёс текст.

Где проходит шов

Каждое из трёх развёртываний выбрано сопоставлением Ops, и документ разработчика этот выбор не затронул. Именно это разделение и призван наглядно показать весь пример:

  • разработчик говорит, что приложению нужно от базы данных;
  • Ops говорит, из чего состоит база данных, — по одному Recipe на каждую реализацию;
  • оператор говорит, какую из них получает это развёртывание, и задаёт её размер.

Добавьте завтра четвёртую реализацию — другое облако, другого оператора, сервис Compose для локальной работы, — и это будет ещё один Recipe, публикующий те же ключи, плюс одна строка в Manifest. Файл aggregate.yaml в этом каталоге не меняется.