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

Значения origin здесь — заполнители. Это не учётные данные какого-либо реального сервиса, и на локальной цели оба отрисовываются в вывод в открытом виде.