Одно намерение разработчика, две формы доставки учётных данных
То, как учётные данные попадают в работающий контейнер, — свойство того, куда вы развёртываете, а не приложения. В одном кластере нет хранилища секретов, поэтому развёртывание само доставляет материал в 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, оба Service и 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, другое тело. На локальной цели
материал учётных данных находится в отрисованном документе и доступен любому, кто может читать
развёртывание, — поэтому такая форма подходит для локальных кластеров и кластеров разработки,
а не для production. На цели с хранилищем отрисованный документ содержит
только имя записи; материал остаётся в хранилище, и оператор согласует
его в 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— указывает реестр хаба, из которого разрешаются сущности каталога.
Значения origin здесь — заполнители. Это не учётные данные какого-либо реального
сервиса, и на локальной цели оба отрисовываются в вывод в открытом виде.