Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Один намір розробника, дві форми доставки облікових даних

Те, як облікові дані потрапляють до запущеного контейнера, — це властивість місця розгортання, а не застосунку. В одному кластері немає сховища секретів, тому розгортання саме постачає матеріал у Kubernetes Secret. В іншому працює оператор сховища секретів, тому розгортання постачає лише вказівник, а кластер отримує матеріал під час узгодження.

Цей робочий простір містить одну сутність Aggregate і збирає її для двох цілей. Aggregate між ними не змінюється. Не змінюється й посилання бази даних на її пароль. Змінюється один рядок у Manifest.

Що змінюється, а що залишається незмінним

файллокальна цільціль зі сховищем
aggregate.yamlтой самий файлтой самий файл
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

Два Manifests відрізняються власною назвою та одним записом зіставлення:

Terminal window
$ diff manifest-local.yaml manifest-store.yaml
7c7
< name: credential-shape-local-manifest
---
> name: credential-shape-store-manifest
16c16
< core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
---
> core/referenced-secret:1.0.0: helm/k8s-external-secret:1.0.0

Два Releases відрізняються власною назвою та тим, на який Manifest вони вказують:

Terminal window
$ diff release-local.yaml release-store.yaml
7c7
< name: credential-shape-local
---
> name: credential-shape-store
12c12
< manifest: credential-shape-local-manifest
---
> manifest: credential-shape-store-manifest

Обидва Releases оголошують однакове environment. Це зроблено навмисно: назва середовища проставляється на кожному відрендереному документі як мітка, тож якщо зафіксувати її, вільною для змін залишається рівно одна річ — FeatureRecipe, який прив’язує Manifest. Справжня пара Releases, звісно, мала б власні назви середовищ, а форми облікових даних відрізнялися б так само.

Сторона розробника, один раз

aggregate.yaml заповнює обидва слоти облікових даних сутності Component для PostgreSQL тією самою сутністю Feature облікових даних, на яку можна посилатися:

features:
password:
type: core/referenced-secret
values:
key: POSTGRES_PASSWORD
origin: postgres-superuser-password
app_user_password:
type: core/referenced-secret
values:
key: APP_USER_PASSWORD
origin: postgres-app-password

core/referenced-secret називає ресурс секрету — той, що створює вивід його FeatureRecipe, або той, що вже існує, — і публікує локатор цього ресурсу — його name і key даних у ньому — через свій контракт provides. Recipe-споживач читає цей локатор. Він ніколи не виводить власну назву ресурсу й ніколи не з’ясовує, який FeatureRecipe його створив.

Що генерує кожна ціль

Кожна збірка записує шість файлів. Чотири з них — StatefulSet, обидва Services та ConfigMap ініціалізації — виходять побайтово ідентичними для обох цілей. Інші два — це ресурси облікових даних, по одному на кожен заповнений слот, і саме в них цілі відрізняються.

Локальна ціль, з k8s-secret-from-parameter, у dist/helm/helm/db--password--db-secret-db-password.yaml:

apiVersion: v1
kind: Secret
metadata:
name: db-password
[… omitted: the labels and annotations naming the aggregate, component, environment, compiler and provider versions, boundary and Recipe — the same set every rendered document carries]
stringData:
POSTGRES_PASSWORD: "postgres-superuser-password"

Ціль зі сховищем, з k8s-external-secret, у dist/helm/helm/db--password--db-externalsecret-db-password.yaml:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: db-password
[… omitted: the same label and annotation set as above]
spec:
refreshInterval: "1h"
secretStoreRef:
name: platform-secret-store
kind: ClusterSecretStore
target:
name: db-password
creationPolicy: Owner
data:
- secretKey: POSTGRES_PASSWORD
remoteRef:
key: "postgres-superuser-password"

Інша група API, інший kind, інше тіло. На локальній цілі матеріал облікових даних міститься у відрендереному документі й доступний кожному, хто може прочитати розгортання, — саме тому ця форма пасує локальним кластерам і кластерам для розробки, а не продакшн-кластеру. На цілі зі сховищем відрендерений документ містить лише назву запису; матеріал залишається у сховищі, а оператор узгоджує його в Secret з назвою db-password.

Порівняння двох дерев виводу показує різницю й показує, де вона закінчується (команди, що створюють local/ і store/, наведено в розділі «Збірка» нижче):

Terminal window
$ diff -r local store
Only in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yaml
Only in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yaml
Only in store/helm/helm: db--password--db-externalsecret-db-password.yaml
Only in local/helm/helm: db--password--db-secret-db-password.yaml

Чотири рядки, усі в одному каталозі, бо на цій цілі файли вкладення лежать поруч із власними файлами компонента, а не в підкаталозі. Дві координати передає назва файлу: db--password-- — це вкладення password на db, а db--app-zuuser-zupassword-- — вкладення app_user_password; підкреслення закодовано як -zu, бо координата й власна назва файлу тут поділяють один рядок.

Чотири рядки, і нічого більше: два ресурси облікових даних є лише в дереві локальної цілі, два — лише в дереві цілі зі сховищем. diff -r не повідомляє про жодну різницю вмісту в спільних для обох дерев файлах, тож чотири спільні документи ідентичні, а не просто схожі.

Посилання, яке не змінюється

Контейнер бази даних читає обидва облікові дані як змінні середовища на основі secretKeyRef. Цей блок побайтово ідентичний в обох цілях:

- name: POSTGRES_PASSWORD
valueFrom:
secretKeyRef:
name: db-password
key: POSTGRES_PASSWORD
- name: APP_USER_PASSWORD
valueFrom:
secretKeyRef:
name: db-app-user-password
key: APP_USER_PASSWORD

Він ідентичний, бо Recipe-споживач не розгалужується. Він запитує в слота опубліковані name і key та записує їх. Обидва FeatureRecipes публікують ті самі два ключі, бо їх оголошує Feature, тож будь-який із них задовольняє споживача — а на цілі зі сховищем посилання розв’язується, щойно оператор узгодить ExternalSecret у Secret з цією назвою.

Саме ця незмінність робить дві форми взаємозамінними. Якби сторона-споживач сама виводила назву Secret, заміна прив’язки залишила б її з посиланням на ресурс, якого під цією назвою вже не існує.

origin означає те, що каже FeatureRecipe

core/referenced-secret оголошує origin як джерело матеріалу й залишає його тлумачення FeatureRecipe:

  • k8s-secret-from-parameter записує його в Secret як матеріал.
  • k8s-external-secret читає його як ключ, який слід отримати зі сховища.

Компілятор передає рядок без змін; він агностичний щодо того, яким із цих варіантів є певний рядок. Саме це дає змогу одному вкладенню обслуговувати обидві форми без жодних змін на боці розробника — і саме це слід перевірити перед заміною прив’язки, бо той самий написаний рядок має бути змістовним для того FeatureRecipe, який його читає.

Опублікована назва й підкреслення в назві слота

Component називає свій другий слот облікових даних app_user_password. Назва об’єкта Kubernetes не може містити підкреслення, тому опублікований provides.name нормалізує підкреслення в дефіси, і ресурс отримує назву db-app-user-password:

- name: APP_USER_PASSWORD
valueFrom:
secretKeyRef:
name: db-app-user-password

Обидва FeatureRecipes нормалізують однаково, тому заміна прив’язки не зсуває посилання споживача. Назву публікують один раз, на боці виробника, і згенерований ресурс, і посилання споживача розв’язуються з цього одного опублікованого значення.

Чого ціль зі сховищем очікує від кластера

ExternalSecret — це кастомний ресурс. Щоб застосувати вивід цілі зі сховищем до кластера, у ньому має працювати оператор сховища секретів і має існувати ClusterSecretStore з назвою platform-secret-store. Ніщо в цьому робочому просторі не встановлює ні того, ні іншого: приклад рендерить те, що споживає такий кластер, і показує, як обирається форма.

Яке сховище працює в кластері й під якою назвою — це властивість цілі, а не застосунку, тому k8s-external-secret не має для цього ключа авторингу. Кластер, сховище якого має іншу назву, обслуговує FeatureRecipe, що називає це сховище.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

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

Terminal window
aggrega scaffold --example credential-shape-per-target

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd credential-shape-per-target

Збирання

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

--auto-pull під час першої збірки розв’язує каталог у lock-файл поруч із Release; подальшим збіркам того самого Release прапорець не потрібен.

Обидві цілі записують у dist/, а aggrega build його не очищує, тож зберігайте вивід кожного запуску окремо, щоб порівняти їх:

Terminal window
out=$(mktemp -d)
rm -rf dist && aggrega build --release release-local.yaml --auto-pull && cp -r dist "$out/local"
rm -rf dist && aggrega build --release release-store.yaml --auto-pull && cp -r dist "$out/store"
( cd "$out" && diff -r local store )

Щоб переконатися, що кожна ціль рендерить детерміновано, додайте --verify-determinism: кожен вузол рендериться двічі, і збірка зупиняється, якщо два рендери будь-якого вузла відрізняються.

Terminal window
aggrega build --release release-local.yaml --verify-determinism
aggrega build --release release-store.yaml --verify-determinism

З ШІ-асистентом

ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.

Використовуйте лише інструменти Aggrega і не створюйте жодної папки самостійно. Якщо в папці робочої області ще немає папки `credential-shape-per-target`, один раз викличте інструмент `scaffold` зі значенням `example`, встановленим у `credential-shape-per-target`, і без `dir`: він записує приклад у нову папку `credential-shape-per-target`. Потім викличте інструмент `build` один раз для кожної сутності Release у такому порядку — `release-local.yaml`, `release-store.yaml` — щоразу з `workspace_root`, встановленим у `credential-shape-per-target`, `release`, встановленим у цей файл, `auto_pull`, встановленим у true, і `write`, встановленим у true. Скажіть мені, які файли записала кожна збірка; вони розташовані в `credential-shape-per-target/dist/`.

Файли

  • aggregate.yaml — намір розробника: один компонент db типу core/datastore/postgres, обидва слоти облікових даних якого заповнено core/referenced-secret. Використовується без змін обома Releases.
  • manifest-local.yaml — прив’язує core/referenced-secret до k8s-secret-from-parameter, який рендерить Kubernetes Secret з написаного матеріалу.
  • manifest-store.yaml — прив’язує ту саму Feature до k8s-external-secret, який рендерить ExternalSecret, що називає запис сховища. Ідентичний manifest-local.yaml, окрім власної назви та цього одного рядка.
  • release-local.yaml, release-store.yaml — два Releases. Ідентичні, окрім власних назв і того, на який Manifest вказує кожен.
  • .aggrega-config.yaml — називає реєстр hub, з якого розв’язуються сутності каталогу.

Значення origin тут — заповнювачі. Вони не є обліковими даними жодного реального сервісу, а на локальній цілі обидва рендеряться у вивід відкритим текстом.