Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Eine Entwicklerabsicht, zwei Formen der Zustellung von Zugangsdaten

Wie Zugangsdaten einen laufenden Container erreichen, ist eine Eigenschaft dessen, wo Sie bereitstellen, nicht der Anwendung. Ein Cluster hat keinen Secret-Store, daher liefert die Bereitstellung das Material selbst in einem Kubernetes-Secret mit. Ein anderer betreibt einen Secret-Store-Operator, daher liefert die Bereitstellung nur einen Zeiger mit, und der Cluster ruft das Material zum Zeitpunkt des Abgleichs ab.

Dieser Workspace enthält ein Aggregate und baut es für zwei Ziele. Das Aggregate ändert sich zwischen ihnen nicht. Ebenso wenig die Referenz der Datenbank auf ihr Passwort. Was sich ändert, ist eine Zeile in einem Manifest.

Was sich bewegt und was festgehalten wird

Dateilokales ZielStore-Ziel
aggregate.yamldieselbe Dateidieselbe Datei
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

Die beiden Manifests unterscheiden sich in ihrem eigenen Namen und in einem Zuordnungseintrag:

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

Die beiden Releases unterscheiden sich in ihrem eigenen Namen und darin, auf welches Manifest sie zeigen:

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

Beide Releases deklarieren dasselbe environment. Das ist Absicht: Der Name der Umgebung wird jedem gerenderten Dokument als Label aufgeprägt, sodass genau eine Sache frei beweglich bleibt, wenn er festgehalten wird — das FeatureRecipe, das das Manifest bindet. Ein echtes Paar von Releases würde natürlich eigene Umgebungen nennen, und die Formen der Zugangsdaten würden sich genau auf dieselbe Weise unterscheiden.

Die Seite des Entwicklers, einmal

aggregate.yaml füllt beide Zugangsdaten-Slots der PostgreSQL-Component mit demselben referenzierbaren Zugangsdaten-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 nennt eine Secret-Ressource, eine, die die Ausgabe seines FeatureRecipe erstellt, oder eine, die bereits existiert, und veröffentlicht den Lokator dieser Ressource — ihren name und den key der Daten darin — über seinen Vertrag provides. Das konsumierende Recipe liest diesen Lokator. Es leitet nie einen eigenen Ressourcennamen ab, und es fragt nie, welches FeatureRecipe sie erzeugt hat.

Was jedes Ziel ausgibt

Jeder Build schreibt sechs Dateien. Vier davon — das StatefulSet, beide Services und die Initialisierungs-ConfigMap — kommen aus beiden Zielen byteidentisch heraus. Die anderen beiden sind die Zugangsdaten-Ressourcen, eine pro gefülltem Slot, und in ihnen unterscheiden sich die Ziele.

Lokales Ziel, aus k8s-secret-from-parameter, unter 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"

Store-Ziel, aus k8s-external-secret, unter 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"

Andere API-Gruppe, anderer Kind, anderer Inhalt. Auf dem lokalen Ziel steht das Material der Zugangsdaten im gerenderten Dokument, für jeden lesbar, der die bereitgestellten Ressourcen lesen kann — weshalb diese Form zu lokalen und Entwicklungsclustern passt statt zu einem Produktionscluster. Auf dem Store-Ziel trägt das gerenderte Dokument nur den Namen des Eintrags; das Material bleibt im Store, und der Operator gleicht es zu einem Secret namens db-password ab.

Ein Vergleich der beiden Ausgabebäume zeigt den Unterschied und zeigt, wo er endet (der Abschnitt Build weiter unten enthält die Befehle, die local/ und store/ erzeugen):

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

Vier Zeilen, alle in einem Verzeichnis, weil die Dateien einer Anbindung auf diesem Ziel neben den eigenen der Komponente liegen statt in einem Unterverzeichnis. Der Dateiname ist es, der die beiden Koordinaten trägt: db--password-- ist die Anbindung password an db, und db--app-zuuser-zupassword-- ist die Anbindung app_user_password — der Unterstrich als -zu kodiert, weil die Koordinate und der eigene Name der Datei sich hier einen String teilen.

Vier Zeilen und sonst nichts: zwei Zugangsdaten-Ressourcen, die nur im Baum des lokalen Ziels vorhanden sind, zwei nur in dem des Store-Ziels. diff -r meldet in keiner Datei, die beide Bäume gemeinsam haben, einen inhaltlichen Unterschied, daher sind die vier gemeinsamen Dokumente identisch und nicht bloß ähnlich.

Die Referenz, die sich nicht bewegt

Der Container der Datenbank liest beide Zugangsdaten als Umgebungsvariablen, die von einem secretKeyRef gestützt werden. Dieser Block ist auf beiden Zielen byteidentisch:

- 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

Er ist identisch, weil das konsumierende Recipe nicht verzweigt. Es fragt den Slot nach seinem veröffentlichten name und key und schreibt sie aus. Beide FeatureRecipes veröffentlichen dieselben zwei Schlüssel, weil das Feature sie deklariert, sodass jedes von beiden den Konsumenten zufriedenstellt — und auf dem Store-Ziel wird die Referenz aufgelöst, sobald der Operator das ExternalSecret zu einem Secret unter diesem Namen abgeglichen hat.

Diese Invarianz macht die beiden Formen austauschbar. Hätte die konsumierende Seite den Namen des Secrets selbst abgeleitet, hätte der Austausch der Bindung sie auf eine Ressource zeigen lassen, die unter diesem Namen nicht mehr existierte.

origin bedeutet das, was das FeatureRecipe darunter versteht

core/referenced-secret deklariert origin als die Herkunft des Materials und überlässt seine Interpretation dem FeatureRecipe:

  • k8s-secret-from-parameter schreibt es als Material in das Secret.
  • k8s-external-secret liest es als den Schlüssel, der aus dem Store abzurufen ist.

Der Compiler leitet den String unverändert weiter; er ist agnostisch gegenüber der Frage, welches von beidem ein gegebener String ist. Das erlaubt es einer einzigen Anbindung, beide Formen ohne Änderung auf der Seite des Entwicklers zu bedienen — und genau das ist vor dem Austausch einer Bindung zu prüfen, weil derselbe verfasste String für jedes FeatureRecipe, das ihn liest, sinnvoll sein muss.

Der veröffentlichte Name und der Unterstrich in einem Slot-Namen

Die Component nennt ihren zweiten Zugangsdaten-Slot app_user_password. Ein Kubernetes-Objektname darf keinen Unterstrich enthalten, daher normalisiert der veröffentlichte provides.name Unterstriche zu Bindestrichen, und die Ressource landet als db-app-user-password:

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

Beide FeatureRecipes normalisieren identisch, weshalb der Austausch der Bindung die Referenz des Konsumenten nicht verschiebt. Der Name wird einmal veröffentlicht, auf der erzeugenden Seite, und die ausgegebene Ressource und die Referenz des Konsumenten werden beide aus diesem einen veröffentlichten Wert aufgelöst.

Was das Store-Ziel vom Cluster erwartet

ExternalSecret ist eine benutzerdefinierte Ressource. Die Ausgabe des Store-Ziels auf einen Cluster anzuwenden, setzt voraus, dass dort ein Secret-Store-Operator läuft und ein ClusterSecretStore namens platform-secret-store existiert. Nichts in diesem Workspace installiert eines von beiden: Das Beispiel rendert, was ein solcher Cluster konsumiert, und lehrt, wie die Form gewählt wird.

Welchen Store ein Cluster betreibt und unter welchem Namen, ist eine Eigenschaft des Ziels statt der Anwendung, daher trägt k8s-external-secret dafür keinen Authoring-Schlüssel. Ein Cluster, dessen Store anders benannt ist, wird von einem FeatureRecipe bedient, das diesen Store nennt.

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd credential-shape-per-target

Build

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

--auto-pull löst den Katalog beim ersten Build in ein Lockfile neben dem Release auf; spätere Builds desselben Release brauchen kein Flag.

Beide Ziele schreiben nach dist/, und aggrega build leert es nicht, legen Sie also die Ausgabe jedes Laufs beiseite, um die beiden zu vergleichen:

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 )

Um zu bestätigen, dass jedes Ziel deterministisch rendert, fügen Sie --verify-determinism hinzu: Jeder Knoten wird zweimal gerendert, und der Build bricht ab, wenn sich die beiden Renderings eines Knotens unterscheiden.

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

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Arbeitsbereichsordner noch keinen Ordner `credential-shape-per-target` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `credential-shape-per-target` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `credential-shape-per-target`. Rufen Sie dann das Tool `build` einmal für jedes Release auf, in dieser Reihenfolge — `release-local.yaml`, `release-store.yaml` — jedes Mal mit `workspace_root` auf `credential-shape-per-target`, `release` auf diese Datei, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die jeder Build geschrieben hat; sie liegen unter `credential-shape-per-target/dist/`.

Dateien

  • aggregate.yaml — Entwicklerabsicht: eine Komponente db vom Typ core/datastore/postgres, deren beide Zugangsdaten-Slots mit core/referenced-secret gefüllt sind. Von beiden Releases unverändert verwendet.
  • manifest-local.yaml — bindet core/referenced-secret an k8s-secret-from-parameter, das aus dem verfassten Material ein Kubernetes-Secret rendert.
  • manifest-store.yaml — bindet dasselbe Feature an k8s-external-secret, das ein ExternalSecret rendert, das den Eintrag im Store nennt. Identisch mit manifest-local.yaml bis auf seinen eigenen Namen und diese eine Zeile.
  • release-local.yaml, release-store.yaml — die beiden Releases. Identisch bis auf ihre eigenen Namen und darauf, auf welches Manifest jedes zeigt.
  • .aggrega-config.yaml — nennt die Hub-Registry, aus der die Katalogentitäten aufgelöst werden.

Die Werte von origin hier sind Platzhalter. Sie sind keine Zugangsdaten für einen echten Dienst, und auf dem lokalen Ziel werden beide im Klartext in die Ausgabe gerendert.