Один контракт, три реализации
База данных 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, который его рендерит. Всё, что относится к базе данных, берётся из стандартной библиотеки без изменений.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example postgres-three-realizationsЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd postgres-three-realizationsСборка
aggrega build --release release-selfhosted.yaml --auto-pullaggrega build --release release-managed.yaml --auto-pullaggrega build --release release-managed-dns.yaml --auto-pullaggrega build --release release-external.yaml --auto-pull--auto-pull записывает lock-файл каждой сущности Release при её первой сборке; последующим сборкам флаг не нужен. Каждая сборка пишет в dist/, и сборка добавляет свои файлы, а не очищает то, что оставила предыдущая. Удаляйте dist/ между запусками, чтобы видеть вывод одной реализации отдельно:
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 внутри кластера.
- 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: две стороны этого развёртывания встречаются на опубликованном контракте базы данных, а не на общей целевой платформе.
- 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.netRecipe публикует это имя как host вместо ссылки Terraform,
и приложение получает его:
- name: DB_HOST value: db.internal.example.net| переменная | release-managed.yaml | release-managed-dns.yaml |
|---|---|---|
DB_HOST | ${module.db.address} | db.internal.example.net |
DB_PORT | 5432 | 5432 |
Это единственная строка вывода, которая меняется. Recipe не создаёт ни DNS-записи, ни псевдонима для имени, и сборка его не ищет: компилятор передаёт его ровно так же, как передавал ссылку. Направить db.internal.example.net на экземпляр, когда тот появится, — записью в собственной DNS-зоне оператора, указывающей на адрес экземпляра, — задача оператора, за пределами Release. Этот ключ — тот же, из которого вариант со ссылкой на внешний сервер ниже читает тот же адрес; этот Recipe принимает его как простое имя или IP-литерал, а значение со схемой, путём, пользователем или портом останавливает сборку, поскольку порт — это infra.port из Release, а потребитель составляет подключение из этих двух значений.
Потребитель, сгенерированный в ту же конфигурацию Terraform, что и база данных,
тоже получает имя и вместе с этим теряет порядок, который давала ссылка:
Terraform обрабатывает модуль после модуля, на который тот ссылается, а имя ни на что
не ссылается. Порядок восстанавливается, если поместить такого потребителя в отдельную границу,
которая использует тот же directory:, что и база данных, и имеет более поздний syncWave:.
Внешний вариант — сервер не запускает никто в этом развёртывании
helm/postgres-external вообще ничего не создаёт. Весь его вывод — один
Service, который сопоставляет имя внутри кластера с адресом, заданным в Release:
[… 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- 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 ofPostgreSQL, which addresses a server it does not provision, but no address wassupplied: set infra.overrides.host on this component in the Release to the DNSname or IP literal the existing server answers onСравнение, ради которого всё затевалось
Отрендеренное окружение приложения, все три варианта рядом:
| переменная | собственный хостинг | управляемая | внешняя |
|---|---|---|---|
POOL_SIZE | 10 | 10 | 10 |
DB_HOST | db-default | ${module.db.address} | postgres.data.example.net |
DB_NAME | appdb | appdb | appdb |
DB_PORT | 5432 | 5432 | 5432 |
DB_PROTOCOL | postgres | postgres | postgres |
DB_USER | appuser | appuser | appuser |
Те же переменные, в том же порядке, каждый раз. Меняется только строка за одной из них. 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 в этом каталоге не
меняется.