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

Zugangsdaten-Features

Diese Seite erklärt eine einzige Idee, die Zugangsdaten-Features der Standardbibliothek und wie ein Manifest auswählt, was jedes davon realisiert, und ist kein lauffähiger Workspace. Eine Entwicklerabsicht, zwei Formen der Zugangsdaten-Bereitstellung baut ein Aggregate gegen zwei Realisierungen derselben Zugangsdaten; schreiben Sie es wie folgt in einen eigenen Ordner:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus:

Terminal window
cd credential-shape-per-target
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

Zugangsdaten füllen einen Slot, den eine Component in ihrem featuresSchema deklariert (siehe entities/component.md); der Slot, das Feature, das ihn füllt, und das FeatureRecipe, das das Manifest bindet, bilden den gesamten Pfad von der Anbindung eines Autors bis zu einer laufenden Arbeitslast.

Die Zugangsdaten-Feature-Familie

Ein Zugangsdaten-Feature trägt das Label feature.aggrega.ai/kind: secret. Das Label ist ein Katalog-Metadatum, das beschreibt, was die Anbindung erzeugt; kein Compiler-Zweig liest es, und ein Zugangsdaten-Feature wird wie jedes andere Feature unter features: angebunden, vom Entwickler im Aggregate oder vom Operator im Release.

Die Standardbibliothek teilt Zugangsdaten-Features danach auf, was die Realisierung mit dem Secret macht:

  • core/secret-value liefert einen Wert in die Inject-Pipe der Komponente, wo deren Recipe ihn liest — einen Chart-Wert, eine Umgebungsvariable.
  • core/secret-provided liefert ebenfalls einen Wert, veröffentlicht ihn aber stattdessen als Schlüssel provides, sodass der eigene Block inject: der Anbindung auf einem transparenten Slot angibt, wohin er geht.
  • core/referenced-secret benennt eine Secret-Ressource — ein Kubernetes-Secret, ein Secret in AWS Secrets Manager, einen Vault-Eintrag —, die seine Realisierung erzeugt oder die bereits existiert, und veröffentlicht name und key dieser Ressource, die ein Konsument als .features.<slot>.provides.name und .features.<slot>.provides.key liest.
  • core/referenced-secret-set materialisiert eine solche Ressource, die einen vom Autor gelieferten Satz von Datenschlüsseln enthält, und veröffentlicht nur ihren Locator, für einen Konsumenten, dessen Ziel die Schlüsselnamen, die er liest, bereits festlegt. Docker Compose hat keine solche Ressource, daher liefert die Realisierung dort die Schlüssel stattdessen als Werte, wie unten beschrieben. MariaDB (Bitnami-Chart) — ein Zugangsdaten-Secret mit mehreren Schlüsseln verwendet es.
  • core/generated-secret erzeugt nichts: Die Ziel-Engine erzeugt und verwaltet die Zugangsdaten selbst, wie es eine verwaltete Datenbank mit ihrem Administratorpasswort tut. Der Operator bindet es im Release an, weil sich aus dem Recipe, das das Manifest auswählt, ergibt, ob die Engine die Zugangsdaten besitzt; Terraform RDS (Inline-HCL-Artefakt) bindet auf diese Weise einen Pflicht-Slot.
  • core/random-password rendert eine Anfrage an das Ziel, ein Passwort in eine Secret-Ressource zu erzeugen, und veröffentlicht den Locator dieser Ressource so, wie es core/referenced-secret tut. Niemand schreibt die Zugangsdaten, und die gerenderte Ausgabe enthält keine.

Sie sind gleichrangig — dasselbe Label, dieselbe Anbindungsfläche, derselbe Slot —, sodass ein Slot immer gefüllt ist und sich zwischen Releases ändert, was ihn füllt. Ein Zugangsdaten-Feature, das einen Vertrag provides deklariert, verpflichtet jedes FeatureRecipe, das es implementiert, diese Schlüssel zu veröffentlichen, und der Build bricht ab, wenn eines das nicht tut; das macht das Lesen durch den Konsumenten sicher.

core/random-password braucht etwas auf dem Ziel, das den Wert erzeugt, da der Build das nie tut: auf Kubernetes einen Controller (den External Secrets Operator oder kubernetes-secret-generator), dessen Vorhandensein das Release mit infra.control_plane_present: true bestätigt; auf Terraform eine Ressource random_password; auf CloudFormation ein Secrets-Manager-Secret, das seine eigene Zeichenkette erzeugt. Für Docker Compose wird keine Realisierung ausgeliefert, daher bricht ein Build, der es dort bindet, ab. Jede Anfrage erzeugt ihren eigenen Wert, daher teilen sich zwei Komponenten ein generiertes Passwort, indem es einmal angebunden wird, mit festgelegtem name, und an anderer Stelle über core/referenced-secret gelesen wird, gebunden an helm/k8s-existing-secret.

Wer die Zugangsdaten benennt: values oder infra, genau eines

core/secret-value, core/secret-provided, core/referenced-secret und core/referenced-secret-set nehmen den Locator der Zugangsdaten von beiden Autoren an: Der Entwickler schreibt ihn in die values der Anbindung im Aggregate, der Operator in die infra der Anbindung im Release. Das Blatt ist in beiden dasselbe — origin, oder entries für den Satz —, und jede Realisierung liest diejenige Säule, die es trägt.

Die Form des Operators macht Zugangsdaten dort nutzbar, wo der Entwickler keine schreiben kann: an einer Verbindung, die das Release verdrahtet, und an einer Anbindung, die allein das Release vornimmt, da ein Release nirgends values schreibt.

# Release: the operator wires the connection and names the secret.
spec:
components:
router:
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a

Genau eine der beiden. Jede Säule wird für sich validiert, daher kann keines der beiden Schemas den Locator verlangen; stattdessen enthalten die eigenen assertions jedes Feature die Regel, und eine Anbindung, die den Locator in beiden Säulen oder in keiner trägt, bricht den Build ab (E0033) und nennt das Feature, die Anbindung und die Komponente. Das ist der Vertrag der Katalogentitäten: Der Compiler wertet ihre Assertion so aus, wie er die jedes Feature auswertet.

Alles andere behält seine Säule. key bleibt ein Blatt in values, daher liest eine Anbindung, die nur das Release vornimmt, den Standard-Datenschlüssel value. Das Deklarieren von origin in beiden Säulen ist genau das, wonach der Hinweis auf Säulenüberschneidung sucht, daher meldet das Laden dieser Features ihn — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Hier ist die Überschneidung der Vertrag; der Hinweis ändert kein Urteil und kein gerendertes Byte.

Das Manifest wählt die Realisierung

Mehrere FeatureRecipes können ein Feature für dasselbe Ziel implementieren, und das Manifest wählt. core/referenced-secret hat drei auf Kubernetes, und wo die Zugangsdaten liegen, entscheidet zwischen ihnen:

  • helm/k8s-secret-from-parameter schreibt den von einem Autor gelieferten Wert in ein Secret, das es ausgibt, sodass das Material in der gerenderten Ausgabe liegt: für Evaluierung und lokale Arbeit.
  • helm/k8s-external-secret rendert ein ExternalSecret, das einen Eintrag in einem Secret-Store nennt, den der External Secrets Operator im Cluster zu einem Secret abgleicht.
  • helm/k8s-existing-secret gibt nichts aus: Es liest origin als Namen eines Secrets, das bereits existiert, und veröffentlicht ihn wie geschrieben.

Die ersten beiden leiten den Namen des Secrets auf dieselbe Weise ab, aus dem gerenderten Namen des Hosts und dem des Slots, sodass ein Konsument von beiden denselben Locator liest und seine gerenderte Referenz unverändert bleibt; genau das zeigt das Beispiel. Das dritte veröffentlicht den eigenen Namen des bestehenden Secrets, sodass seine Bindung die Referenz des Konsumenten absichtlich ändert.

core/secret-value wird auf Docker Compose durch compose/dotenv-secret realisiert, das den Wert genau wie verfasst in die Umgebung des Dienstes schreibt: Ein als ${DB_PASSWORD} geschriebener origin landet als diese Referenz, die Docker Compose beim Start des Stacks aus Ihrer Shell oder einer Datei .env füllt. Auf Kubernetes liefert helm/env-secret den Wert in die Inject-Pipe, und helm/k8s-secret-from-value schreibt ihn außerdem in ein Secret und veröffentlicht dessen Locator, für einen Konsumenten, der die Zugangsdaten per Referenz liest. Keine der beiden Kubernetes-Realisierungen akzeptiert eine Compose-Variablenreferenz, die dort nichts füllen würde.

core/referenced-secret wird auf Docker Compose durch compose/dotenv-referenced-secret realisiert. Compose hat keine Secret-Ressource, auf die verwiesen werden könnte, daher ist origin die Zugangsdaten selbst statt des Namens eines Secrets: Der Wert wird unter dem key der Anbindung in die Inject-Pipe geliefert, und ein Compose-Recipe, das den Slot liest, schreibt ihn genau wie verfasst in die ausgegebene Datei, sodass ein als ${DB_PASSWORD} geschriebener origin als diese Referenz ankommt. Es erzeugt keine Ressource, daher ist der veröffentlichte Name leer und der veröffentlichte Schlüssel ist values.key.

core/referenced-secret-set wird auf Docker Compose durch compose/dotenv-secret-set realisiert, das jeden Eintrag als nach seinem Schlüssel benannte Variable in die Inject-Pipe liefert, genau wie verfasst in die Umgebung des Dienstes geschrieben, sodass ein Eintrag mit dem Wert ${GITHUB_TOKEN} als diese Referenz ankommt. Es erzeugt keine Ressource, daher ist der veröffentlichte Locator leer: Ein Konsument auf Compose liest die Einträge aus seiner Inject-Pipe, statt per Name auf ein Secret zu verweisen, wie es compose/mcp und compose/mcp-stdio-bridge ab 1.1.0 für die server_env eines Model-Context-Protocol-Servers tun.

Ein FeatureRecipe-Name, der für mehr als ein Ziel ausgeliefert wird, wie provided-secret, wird im Manifest mit seinem Ziel angegeben, compose/provided-secret:1.0.0, da der bloße Name auf beide passt.

Ein Name, einmal veröffentlicht

Das Recipe eines Konsumenten leitet den Namen des Secrets, das Zugangsdaten erzeugen, nie selbst ab: Es liest den Locator, den die Zugangsdaten veröffentlichen, existingSecret: "{{ .features.root_password.provides.name }}". Der Name wird einmal verfasst, im provides des FeatureRecipe, daher ist eine Änderung seiner Zusammensetzung eine Bearbeitung allein an dieser Stelle. Zugangsdaten-Bereitstellung — secretKeyRef durchgängig baut den referenzierbaren Pfad auf Kubernetes und den injizierten auf Docker Compose, und Zugangsdaten teilen — pro Konsument, gemeinsam und beides zugleich zeigt mehrere Konsumenten, die jeweils einen eigenen Schlüssel halten oder sich einen teilen.