Один намір розробника, дві форми доставки облікових даних
Те, як облікові дані потрапляють до запущеного контейнера, — це властивість місця розгортання, а не застосунку. В одному кластері немає сховища секретів, тому розгортання саме постачає матеріал у Kubernetes Secret. В іншому працює оператор сховища секретів, тому розгортання постачає лише вказівник, а кластер отримує матеріал під час узгодження.
Цей робочий простір містить одну сутність Aggregate і збирає її для двох цілей. Aggregate між ними не змінюється. Не змінюється й посилання бази даних на її пароль. Змінюється один рядок у Manifest.
Що змінюється, а що залишається незмінним
| файл | локальна ціль | ціль зі сховищем |
|---|---|---|
aggregate.yaml | той самий файл | той самий файл |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
Два Manifests відрізняються власною назвою та одним записом зіставлення:
$ diff manifest-local.yaml manifest-store.yaml7c7< name: credential-shape-local-manifest---> name: credential-shape-store-manifest16c16< 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 вони вказують:
$ diff release-local.yaml release-store.yaml7c7< name: credential-shape-local---> name: credential-shape-store12c12< 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-passwordcore/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: v1kind: Secretmetadata: 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/v1kind: ExternalSecretmetadata: 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/, наведено в розділі «Збірка» нижче):
$ diff -r local storeOnly in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yamlOnly in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yamlOnly in store/helm/helm: db--password--db-externalsecret-db-password.yamlOnly 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, що називає це сховище.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example credential-shape-per-targetПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd credential-shape-per-targetЗбирання
aggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pull--auto-pull під час першої збірки розв’язує каталог у lock-файл поруч із Release; подальшим збіркам того самого Release прапорець не потрібен.
Обидві цілі записують у dist/, а aggrega build його не очищує, тож зберігайте вивід кожного запуску окремо, щоб порівняти їх:
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: кожен вузол рендериться двічі, і збірка зупиняється, якщо два рендери будь-якого вузла відрізняються.
aggrega build --release release-local.yaml --verify-determinismaggrega 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 тут — заповнювачі. Вони не є обліковими даними жодного реального сервісу, а на локальній цілі обидва рендеряться у вивід відкритим текстом.