Один контракт, три реалізації
База даних 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, ClusterIP Service і 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 у цьому каталозі не змінюється.