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

Credential-Modell

Eine einzige Attachment-Familie

Ein Credential ist in Aggrega ein Feature. Es wird auf derselben Oberfläche, unter demselben Schlüsselwort und in derselben Form angehängt wie jedes andere Feature. Hier hängt der Entwickler das Credential der Datenbank im Aggregate an und schreibt seinen Locator in values:

# the Aggregate — its parameters and the components' own values left out
spec:
components:
api:
type: core/compute/server
db:
type: core/datastore/mariadb
features:
root_password: # a credential Feature
type: core/secret-value:1.0.0
values:
key: MARIADB_ROOT_PASSWORD
origin: "{{ .parameters.db_root_pass }}"

und der Operator hängt dem Server im Release ein Metrik-Scrape-Ziel an, weil jede Eingabe, die core/prometheus-exporter entgegennimmt — Port, Pfad und Intervall des Scrapes — operativ ist und daher in infra geschrieben wird:

# the Release — the api's own infra and the db's entry left out
spec:
components:
api:
features:
metrics: # an operational Feature
type: core/prometheus-exporter:1.0.0
infra:
port: http # the named port of the api's Service

Es gibt ein Attachment-Schlüsselwort (features:), eine Form des Render-Kontexts (.features.<name>, und dieselbe Form unter einer Verbindung, .context.uses.<alias>.features.<slot>, für ein dort geschriebenes Attachment), eine Ausführungsreihenfolge und einen Satz von Ausgabekoordinaten — für ein Attachment an einer Komponente die Komponente, an die es angehängt ist, und dann der Name, unter dem es angehängt ist, unabhängig davon, ob das Layout des Ziels diese beiden als Verzeichnis <component>--<instance>/ neben dem der Komponente oder als Dateinamenpräfix <component>--<instance>-- führt. Was zwischen Attachments variiert, ist was sie erzeugen — ein injizierter Wert, eine referenzierbare Ressource, ein Sidecar, eine Cloud-Identität —, nicht die Oberfläche, auf der sie deklariert werden.

Ein Credential-Feature trägt auf seiner Katalogentität das Label feature.aggrega.ai/kind: secret. Dieses Label ist beschreibende Metadaten: Es teilt einem Leser, einer Katalog-Website und einem Label-Selektor mit, wofür das Feature gedacht ist. Kein Compiler-Zweig liest es, und kein Verhalten hängt davon ab. Das Verhalten ergibt sich aus dem FeatureRecipe, dem ein Operator den Feature-Typ zuordnet.

Das Denkmodell in einem Satz: Es gibt eine Art von Attachment; was variiert, ist, was es erzeugt.

Slots und freie Attachments

Eine Component oder ein Feature kann in featuresSchema Slots deklarieren:

spec:
featuresSchema:
root_password:
required: true
inject: [] # blackbox — the Recipe delivers it
selector: "feature.aggrega.ai/kind=secret"
user_password:
inject: [env, file] # transparent — the developer may dictate delivery

Ein Attachment, dessen Instanzname einem deklarierten Slot entspricht, füllt diesen Slot. Ein Attachment unter einem anderen Namen ist ein freies Attachment: Die Entität hat es nicht angefordert, und es wird neben allem gerendert, was die Entität angefordert hat. Das generierte Schema für einen deklarierten Slot bleibt offen, sodass die Deklaration eines Slots den Block nie für freie Attachments schließt. Eine Form hält an, statt zu rendern: ein an der Komponente selbst geschriebenes Attachment, dessen Feature den selector eines Slots erfüllt, den dort nichts bindet — das ist eine unter dem falschen Namen geschriebene Füllung und kein freies Attachment.

Zwei Dinge, die ein Slot einschränken kann:

  • inject — die Zustellmechanismen, die eine Workload für das wählen kann, was den Slot füllt. Eine leere Liste ist ein Blackbox-Slot: Die eigene Mechanik des Recipe stellt ihn zu (etwa die Option existingSecret eines Charts), und eine Workload darf ihn nicht aus einem Container referenzieren.
  • selector — eine Label-Selector-Zeichenkette, die die Labels des füllenden Feature erfüllen müssen. Hier macht sich das Label kind=secret bezahlt: Ein Entitätsautor, der einen Slot ausschließlich durch ein Credential füllen lassen möchte, drückt dies mit einem Selector aus, und die Prüfung ist eine Auswertung der Label-Menge, die der Compiler während der statischen Analyse durchführt.

Ein Slot kann außerdem verlangen, am Ende gebunden zu sein. required: true macht den Namen des Slots verpflichtend: Der Compiler hält während der statischen Analyse an, wenn nichts ihn bindet, mit einer Diagnose, die den Slot und den Komponententyp nennt, der ihn deklariert hat. Die Anforderung wird gegen die Attachment-Menge geprüft, die die Komponente hat, nachdem jeder Scope kaskadiert ist, sodass ein oberhalb der Komponente beigesteuertes Attachment den Slot genauso bindet wie eine an der Komponente geschriebene Füllung.

Eine zweite Oberfläche drückt eine andere Anforderung aus. Die wiederholbare Component-Annotation features.aggrega.ai/requiredType.<label> deklariert eine Präsenzpflicht: Mindestens ein Attachment muss den Feature-Typ tragen, den die Annotation nennt, unter beliebigem Namen und in beliebigem Scope, und eine Pflicht, die nichts erfüllt, hält während derselben statischen Analyse mit einer eigenen Diagnose an. Die beiden stehen nie füreinander ein — ein Slot fragt, ob ein benannter Bindungspunkt gebunden ist, eine Pflicht, ob irgendein Attachment einen benannten Typ trägt —, sodass eine Entität, deren Recipe lesen muss, was angehängt wurde, einen Slot deklariert, während eine, deren Vertrag lediglich das Vorhandensein einer Fähigkeit verlangt, eine Pflicht deklariert.

Was der Compiler garantiert und was nicht

Dieser Abschnitt ist der tragende. Aggrega ist ein Ahead-of-time-Compiler, und seine Garantien sind enger, als das Wort „Secret“ einen Leser vermuten lässt.

Der Compiler löst nie ein Credential auf. Er authentifiziert sich bei keiner Cloud-API, liest keinen Vault und ruft während aggrega build kein Material ab. Die values und infra eines Credential-Attachments durchlaufen den Graphen und gelangen als opake Skalare in den Render-Kontext, und ein FeatureRecipe rendert sie in das Artefakt, das die Zielplattform erwartet. Die Auflösung geschieht später, im Cluster oder im IaC-Zustandsmanager, gegen das, worauf das gerenderte Artefakt verweist.

Der Compiler kann einen Zeiger nicht von einem Materialwert unterscheiden. Er ist agnostisch gegenüber der Bedeutung eines Skalars (siehe 05-invariants.md). Ein Credential-Attachment, dessen Locator eine Store-Koordinate trägt (path, key, ein ARN), rendert eine Referenz auf diese Koordinate; ein Credential-Attachment, dessen Locator das Material selbst trägt, rendert das Material wörtlich in die Ausgabedatei. Beides ist zulässig, und der Compiler behandelt beides identisch, weil er keine Möglichkeit hat, sie zu unterscheiden.

Die ehrliche Formulierung der Garantie lautet also:

Aggrega garantiert, dass der Compiler keine Auflösung durchführt. Es garantiert nicht, dass die gerenderte Ausgabe kein Material enthält — das hängt vollständig davon ab, welches Credential-Feature angehängt ist und was sein Autor hineingeschrieben hat, der Entwickler in values oder der Operator in infra.

Zwei Konsequenzen, die man verinnerlichen sollte:

  • Ein gerenderter Artefaktbaum ist so sensibel wie sein Attachment, das am meisten Material trägt. Behandeln Sie dist/ entsprechend: Trägt irgendein Attachment Material inline, enthält der Baum Material.
  • Die katalogeigenen Familien core/secret-value und core/referenced-secret enthalten Formen, die einen Wert direkt annehmen. Sie existieren, weil reale Deployments einen Weg für die lokale Entwicklung brauchen, und sie sind darin ehrlich: Die mitgelieferten Beispiele verwenden offensichtliche Platzhalter (dev-root-pw-change-me), gerade damit das Material in einem gerenderten Beispiel sichtbar kein echtes Credential ist. Für ein Deployment, das kein Material tragen darf, hängen Sie ein store-gestütztes Credential-Feature an, dessen FeatureRecipe eine Abrufressource ausgibt (ein ExternalSecret, eine Vault-Abruf-Custom-Resource, eine provider-native Secret-Referenz) statt einer, die Daten ausgibt.

Die Konvention der Standardbibliothek ist, dass ein Credential als Attachment angefordert und nicht in einen values-Block geschrieben wird, sodass der Austausch einer Füllung für die lokale Entwicklung gegen eine store-gestützte eine Manifest-Änderung ist und keine Bearbeitung der Entwicklerabsicht. Das ist eine Konvention, der der Katalog folgt, keine Regel, die der Compiler durchsetzt.

Deklarierte Sensibilität

Der Compiler kann einen Zeiger nicht von einem Materialwert unterscheiden, wie der vorige Abschnitt sagt — ein Autor aber schon, und er kann es angeben. Sensibilität ist in Aggrega eine Annotation an einer Deklaration: Der Autor einer Katalogentität gibt an, was geheimes Material trägt, und der Compiler leitet den Rest aus dieser Angabe und der bereits aufgebauten Verdrahtung ab. Nichts wird aus einem Wert gefolgert, und nichts wird aus dem Namen eines Feldes erraten.

Sie wird an genau zwei Stellen geschrieben, und diese tragen wirklich unterschiedliche Aussagen.

An einem Schema-Blatt — dieses Datum ist geheimes Material. Ein Blatt in values, infra oder provides deklariert sensitive: true:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true # the material
key:
type: string
default: value # a data key — a locator, not material

An einem Attachment-Slot — was auch immer diesen Punkt bindet, verarbeitet geheimes Material. Ein Slot in featuresSchema deklariert sensitive: true:

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

Die beiden Ebenen sind kein bequemes Duplikat voneinander, und die Form des referenzierbaren Credentials ist der durchgearbeitete Fall, der zeigt, warum. Ein referenzierbares Credential veröffentlicht provides.name und provides.key — den Locator der Ressource und den Datenschlüssel darin — und keines von beiden ist sensibel: Der Name eines Kubernetes-Secrets ist öffentlich, ebenso der Schlüssel darin. Beide werden im Klartext als secretKeyRef in das eigene Manifest des Konsumenten gerendert. Dennoch verarbeitet der Slot, den dieses Credential füllt, zweifellos geheimes Material. Eine Ebene allein kann nicht beide Tatsachen ausdrücken: Die veröffentlichten Locators zu markieren, damit der Slot als sensibel gilt, würde etwas Falsches über sie aussagen und diesen Fehler überallhin tragen, wo die Deklaration gelesen wird.

Aus diesen beiden Deklarationen leitet der Compiler pro Attachment ab, ob das Attachment als sensibel deklariertes Material verarbeitet — wahr, wenn das angehängte Feature ein sensibles Blatt deklariert oder wenn der Slot, den es bindet, eines deklariert, wobei jedes allein genügt. Er leitet dies aus dem Attachment ab, wie es vorliegt, nachdem jeder Authoring-Scope zusammengeführt wurde, sodass eine Deklaration eines breiteren Scopes, die eine engere Füllung verdrängt hat, nicht nachwirkt, und die Anforderung eines Slots für die Füllung gilt, die sich tatsächlich durchgesetzt hat. Ein Credential-Feature, das gar kein sensibles Blatt deklariert — weil die Ziel-Engine das Material besitzt und der Autor nichts schreibt —, ergibt dennoch ein sensibles Attachment, wenn es einen sensiblen Slot bindet.

Die Obergrenze, klar gesagt

Das Wort „sensibel“ lässt einen Leser einen Vertraulichkeitsmechanismus erwarten. Es ist keiner, und die Garantie ist in fünf bestimmten Punkten enger, als der Name nahelegt:

  • Es verschlüsselt nicht. Nichts wird verpackt, versiegelt oder transformiert.
  • Sie ändert das Urteil des Builds nicht, mit einer Ausnahme. Kein Build bricht ab, weil eine Deklaration fehlt, und ein Katalog, dessen Credential-Entitäten keine Deklaration tragen, wird erfolgreich gebaut. Kein Wert wird angenommen oder abgelehnt, weil eine Deklaration existiert, außer dort, wo bei einem CloudFormation-Recipe oder einem FeatureRecipe das valuesMapping einen als sensitiv deklarierten Wert liest, um die Parameter eines eingebundenen Templates zu füllen: Dort wird jedes Literal abgelehnt, das das Mapping bindet, sodass das Hinzufügen einer Deklaration einen Build, der erfolgreich war, in einen abbrechenden verwandeln kann — siehe A secret bound to a CloudFormation parameter would be written into the template (Ein an einen CloudFormation-Parameter gebundenes Secret würde in das Template geschrieben). Überall sonst bleibt jeder erfolgreiche Build nach dem Hinzufügen von Deklarationen zu einem bestehenden Katalog erfolgreich.
  • Es garantiert nicht, dass die gerenderte Ausgabe frei von Material ist. Die oben formulierte Garantie bleibt unverändert: Ob ein Artefakt Material trägt, hängt davon ab, welche Füllung angehängt wurde und was ihr Autor hineingeschrieben hat. Ein inline angegebener, als sensibel deklarierter Wert wird genau wie ein nicht deklarierter gerendert, wo immer der Build ihn überhaupt rendert — die oben beschriebene CloudFormation-Ablehnung stoppt ein Literal, statt es zu rendern, und eine intrinsische Funktion wird wie angegeben geschrieben, einschließlich ihres Textes —, und dist/ bleibt so sensibel wie sein Attachment, das am meisten Material trägt.
  • Es erzwingt keinen Zustellmechanismus. Eine Deklaration kann einen Inline-Wert nicht in eine Store-Referenz umwandeln, und sie schränkt nicht ein, was die inject-Allowlist eines Slots erlaubt. Die Zustellung zu erzwingen hieße, eine Ressource auszugeben, die der Autor nie deklariert hat, und genau das verbietet die Invariante gegen Geisterinfrastruktur — siehe 05-invariants.md.
  • Sie ändert auf den meisten Zielen kein gerendertes Byte, und auf diesen wird sie es nie tun. Zwei mitgelieferte Render-Pfade reagieren in dem, was sie erzeugen, auf die Deklaration (die Provider für Helm, Helm-Chart und Compose lesen sie ebenfalls, nur um einen markierten Wert aus dem Text eines Fehlers herauszuhalten): Der Terraform-Provider markiert die Eingabe eines eingebundenen Moduls, die als sensitiv deklariertes Material trägt, mit Terraforms eigenem Sensitivitätsattribut — siehe language-reference/providers/terraform.md „Als sensitiv deklarierte Moduleingaben“; wo das valuesMapping eines Recipe oder das des FeatureRecipe eines an eine Komponente angehängten Feature die Eingabenamen erfindet, kann keine Eingabe das Attribut tragen, und der Build gibt einen entsprechenden Hinweis aus, siehe A declared-sensitive value reaches the target through a values mapping (Ein als sensitiv deklarierter Wert erreicht das Ziel über ein Values-Mapping) — und der CloudFormation-Provider lehnt die oben beschriebenen Literal-Bindungen ab, was einen Build abbricht, statt seine Bytes zu ändern. Überall sonst lässt das Hinzufügen von Deklarationen in einem bestehenden Katalog jedes gerenderte Artefakt identisch. Die Obergrenze darüber hinaus ist struktureller Natur und keine Frage dessen, was bisher gebaut wurde: Eine Deklaration kann ein gerendertes Artefakt immer nur auf einer Zielplattform erreichen, deren eigene Sprache einen Begriff von Sensitivität kennt — eine Deklaration, die diese Plattform versteht und die bestimmt, wie sie einen Wert anzeigt, nicht wie sie ihn speichert. Auf einem Ziel ohne einen solchen Begriff gibt es nichts, wozu eine Deklaration werden könnte, sodass identische Eingaben mit oder ohne sie identisch gerendert werden, dauerhaft.

Eines ändert eine Deklaration jedoch: was die CLI für einen Menschen zum Lesen ausgibt. Ein als sensibel deklarierter Wert wird im Trace pro Durchlauf und in den inspect-Layouts durch einen festen Platzhalter ersetzt, wobei der Schlüssel erhalten bleibt und nur der Wert zurückgehalten wird. Das ist eine Anzeigeentscheidung auf Oberflächen, die niemand deployt, und gerenderte Artefakte werden wörtlich ausgegeben, weil sie das Deploybare sind.

Wo der Compiler den Wert über einen Schlüssel identifizieren kann — ein deklariertes Blatt oder ein Zustellschlüssel, der Material aus einem deklarierten provides-Schlüssel trägt —, ist die Ersetzung exakt. Ein Wert, den ein Template bereits in ein anderes Dokument geschrieben hat, trägt keinen Schlüssel, an dem ersetzt werden könnte, weil ein gerendertes Dokument nichts darüber festhält, aus welcher Deklaration jedes Zeichen stammt, und dies zu rekonstruieren hieße, Inhalte zu inspizieren. Daher zeigt der Trace ein solches Dokument, indem er dasselbe Template ein zweites Mal gegen einen Kontext auswertet, dessen als sensibel deklarierte Daten bereits als Platzhalter gelesen werden, und kennzeichnet das Ergebnis als erneutes Rendering und nicht als das, was gerendert wurde: Ein Template, das nach dem Inhalt eines Wertes verzweigt, rendert gegen einen Platzhalter anders, und ein Datum, das keine Deklaration nennt, wird unverändert durchgereicht. Die Oberflächen, diese Kennzeichnung und ihre Grenzen stehen unter language-reference/vocabulary/compact-form-authoring.md „Ein Blatt als sensibel deklarieren“.

Die ehrliche Formulierung dessen, was diese Achse bringt, lautet also:

Eine Sensibilitätsdeklaration ist eine Aussage über die Absicht des Autors, die mit der Entität reist, sodass Werkzeuge und Richtlinien darüber urteilen können, was ein Deployment verarbeitet. Sie ist kein Mechanismus, der es schützt.

Material zu schützen bleibt Aufgabe des Secret-Stores, des Clusters und der Pipeline, die den gerenderten Baum verarbeitet — wie der Rest dieses Kapitels sagt.

Wie ein Credential einen Container erreicht

Zwei Zustellformen, gewählt vom FeatureRecipe des Attachments statt vom Entwickler:

Injizierter Wert. Das FeatureRecipe deklariert ein injectMapping und keine Ressourcen. Seine Ausgabe wird tief in die Zustell-Pipe der konsumierenden Komponente gemergt, bevor das Basis-Recipe rendert, sodass ein Recipe, das .context.inject.env.<KEY> liest, den Wert erhält. Nichts Eigenständiges wird ausgegeben.

Zwei unter einem Schlüssel zugestellte Credentials halten den Build an und nennen beide Attachments: Ein Mapping, das einen Schlüssel schreibt, den ein anderes angehängtes Feature bereits zugestellt hat — über das eigene Mapping dieses Features oder seinen eigenen inject:-Block —, wird abgelehnt statt gemergt, sodass nie ein Credential anstelle eines anderen präsentiert wird. Die Regel ist für jedes Attachment dieselbe, wo immer es angehängt wurde und ob es einen Slot an der Komponente oder an einer Verbindung füllt. Ein Mapping, das einen Schlüssel ersetzt, den der eigene inject:-Block der Komponente oder eine ihrer Verbindungen zugestellt hat, ist die Interception, auf die die Routing-Features angewiesen sind, und bleibt zulässig.

Referenzierbare Ressource. Das FeatureRecipe deklariert source, workload, artifacts und/oder valuesMapping, sodass es eine Ressource ausgibt — typischerweise ein plattformnatives Secret. Es veröffentlicht die Identität dieser Ressource über seine provides, und ein Konsument liest sie als .features.<name>.provides.name / .provides.key zurück. Der eigene Name der Ressource wird aus denselben veröffentlichten provides abgeleitet, sodass der Name, den der Konsument liest, und der Name, den die Ressource trägt, eine einzige ausgewertete Zeichenkette sind statt zweier Ableitungen, die auseinanderlaufen könnten.

Die Workload eines Recipe konsumiert eine referenzierbare Füllung über die Map attachments: eines Containers:

workload: |
containers:
main:
attachments:
DB_PASSWORD:
from: root_password # a slot the Component declares
as: env

Der Synthesizer löst die Referenz aus den veröffentlichten provides des Slots auf — ein Kubernetes-secretKeyRef für as: env, ein secret-gestütztes Volume für as: file. Der Recipe-Autor schreibt nur den Slot-Namen und den Mechanismus.

Ein FeatureRecipe kann beides: die Zustell-Pipe umschreiben und eine Ressource ausgeben. Es kann außerdem eine pipeline aus Wasm-Schritten deklarieren, die für jede Attachment-Familie gleichermaßen laufen — ein Credential-Attachment kann die gerenderten Dokumente der Host-Komponente auf Einladung genauso transformieren wie ein operatives Attachment.

Wer das Credential benennt

Der Locator eines Credentials — der Name des Secrets, der abzurufende Store-Eintrag, der zuzustellende Wert — wird von demjenigen geschrieben, der ihn kennt, und das ist nicht immer der Entwickler. Eine Verbindung, die das Release verdrahtet, hat keinen Eintrag im Aggregate, und das Release schreibt nirgends values, sodass ein Credential, das seinen Locator nur aus values bezöge, auf einer solchen Verbindung nie benannt werden könnte, ebenso wenig auf einem Attachment, das das Release anlegt.

Daher nimmt jedes Credential-Feature der Standardbibliothek, das den Locator eines Aufrufers trägt — core/referenced-secret, core/referenced-secret-set, core/secret-value und core/secret-provided —, ihn von beiden Autoren an: vom Entwickler in den values des Attachments im Aggregate oder vom Operator in dessen infra im Release. Das Blatt hat in beiden Säulen einen Namen, eine Form und eine sensitive: true-Deklaration, und jede Realisierung liest die Säule, die es trägt. Das values:-Verbot des Release bleibt unberührt: Der Locator des Operators ist infra. Die Features, die keinen Locator annehmen — core/random-password, core/generated-secret —, sind nicht betroffen.

Genau einer, durch das Feature sichergestellt. Ein Attachment trägt den Locator in einer Säule, nie in beiden und nie in keiner. Das Schema keiner Säule kann das ausdrücken, weil jede Säule für sich validiert wird; der eigene assertions-Block jedes Features tut es, und ein Attachment, das ihn verletzt, hält den Build an und nennt das Feature, das Attachment und die Komponente. Das ist der Vertrag der Katalogentität, eingehalten wie jede Feature-Assertion: Der Compiler wertet das Template aus, das der Autor des Features geschrieben hat, und hat keine eigene Regel über Credentials, Säulen oder Locators.

Was bleibt, wo es war. Jedes andere Feld behält seine Säule — der Datenschlüssel eines referenzierbaren Credentials wird weiterhin in values geschrieben, sodass ein Attachment, das allein das Release anlegt, seinen Standardwert liest —, und core/secret-provided stellt weiterhin nur über den eigenen inject:-Block des Attachments zu, den nur das Aggregate schreibt und den das Attachment einer Verbindung nie trägt.

Ein Credential für mehrere Konsumenten gemeinsam nutzen

Der Konsument kann das Credential halten. Ein Slot gehört derjenigen Entität, die das Credential benötigt, und das ist oft der Aufrufer und nicht das Aufgerufene: Eine Komponente, die beim Verbindungsaufbau einen Schlüssel vorlegt, deklariert den Slot für diesen Schlüssel auf ihrer eigenen Katalogentität, an dem Socket, über den sie die Verbindung aufbaut, sodass der Schlüssel auf der Verbindung gehalten wird, auf der er vorgelegt wird — und nichts an einer uses-Kante verpflichtet das Ziel, einen bereitzustellen. core/ai-agent/crewai ist die mitgelieferte Form — sein Socket model deklariert einen optionalen Slot credential mit dem Selector feature.aggrega.ai/kind=secret, inject: [env] und sensitive: true, und ein Aggregate füllt ihn unter der Verbindung, unter uses.model.<alias>.features.credential. Was die Modellkomponenten der Standardbibliothek für einen Konsumenten zum Lesen veröffentlichen, ist ein Bereitstellungsort und ein Modellname, kein Credential, sodass der Schlüssel, den der Agent beim Aufruf dieses Endpunkts vorlegt, vom Agenten deklariert und auf seiner Verbindung gehalten wird. Der Slot ist optional, aber eine Verbindung zu einem Modell, das sein Katalog mit component.aggrega.ai/hosting: managed kennzeichnet, die kein Credential trägt, bricht den Build ab, es sei denn, ihre eigenen values sagen, dass das Modell keines benötigt, unauthenticated: true — eine Assertion, die die Katalogentität des Agenten trägt und die der Compiler wie jede Assertion auswertet, wobei er das Label als Zeichenkette liest. Die Modellkomponente, mit der er sich verbindet, kann einen eigenen Schlüssel für ihre eigenen Aufrufer halten — core/ai-model/vllm deklariert genau dafür einen Slot api_key —, und die beiden sind getrennte Bindungspunkte: Ein Attachment bindet einen Slot über den Namen dort, wo er deklariert ist, auf der Komponente oder auf der Verbindung, sodass das Füllen des einen nichts über den anderen aussagt.

Diese Platzierung macht die beiden folgenden Formen überhaupt erst zu Deployment-Entscheidungen: Mit dem Slot beim Konsumenten kann ein Build jedem Konsumenten seinen eigenen Schlüssel geben und ein anderer allen denselben, ohne dass sich zwischen ihnen eine Katalogentität ändert.

Dieselbe Katalogentität bedient beide Formen, und der Autor wählt, welche:

  • Pro Konsument. Jeder Konsument füllt seinen eigenen Slot mit seinem eigenen Credential-Attachment — auf der Komponente oder, wo der Slot zu einem Socket gehört, auf seiner Verbindung. Jeder erhält seine eigene gerenderte Ressource.
  • Gemeinsam. Für einen Slot, den eine Komponente deklariert, wird ein Credential einmal in einem gemeinsamen Geltungsbereich angehängt — einem Subsystem im Aggregate, einer Boundary im Release — und kaskadiert zu jeder Komponente in diesem Geltungsbereich. Ein Slot, den ein Socket deklariert, wird pro Verbindung gefüllt, und nichts kaskadiert in eine Verbindung hinein, daher wird die gemeinsame Form dort auf jeder Verbindung geschrieben: Das Credential jeder Verbindung liest einen einzigen Parameter. Wo die Konsumenten auf eine einzige physische Ressource verweisen müssen, benennt dieser Parameter sie — core/referenced-secret, gebunden an die Existing-Secret-Realisierung, richtet jede Verbindung über den Namen auf ein einziges Secret aus, und ein generiertes Credential ist eine Anforderung und viele Referenzen, wie weiter unten beschrieben.

Das Rendering der gemeinsamen Form sei genau festgehalten, weil man leicht etwas anderes annimmt: Ein gemeinsames Attachment rendert eine Ressource pro Konsument, jede mit demselben Material aus der einen Deklaration. Das Rendern läuft pro Komponente, und ein aus {{ .context.instance_id }}-{{ .attachment_name }} abgeleiteter Ressourcenname unterscheidet sich daher pro Konsument. Geteilt wird die einzelne Deklaration; die emittierten Ressourcen werden nicht zu einer einzigen dedupliziert. Ein auf jeder Verbindung gelesener Parameter rendert unter einer Realisierung, die eine Ressource rendert, auf dieselbe Weise — eine pro Verbindung, wobei der Name des Attachments der Alias der Verbindung, ein Punkt und der Slot ist.

Benötigt ein Deployment genau ein physisches Secret, das mehrere Konsumenten lesen, drücken Sie das mit einem Credential-Feature aus, dessen FeatureRecipe im Boundary-Geltungsbereich läuft (executionScope: boundary) und das einmal für die Boundary statt einmal pro Komponente rendert.

Ein Schlüssel, den beide Enden einer Verbindung halten

Ein Server, der einen Schlüssel prüft, und die Komponente, die ihn aufruft, halten diesen Schlüssel jeweils auf ihrer eigenen Seite. Der Server hält den Schlüssel, den er verifiziert, in einem Slot seiner eigenen Component — core/ai-model/vllm, core/ai-model/tei und core/ai-model/tgi deklarieren jeweils api_key, ebenso wie das LiteLLM-Modell und das LiteLLM-Gateway für den Schlüssel, den LiteLLM seinen Master-Key nennt —, und sein Recipe liefert das, was den Slot füllt, als die Variable aus, die der Server liest. Der Aufrufer hält den Schlüssel, den er vorlegt, auf seiner eigenen Seite: auf der Verbindung, auf der er ihn vorlegt, in einem Slot, den sein Socket deklariert — so wie der Socket model von core/ai-agent/crewai credential deklariert — oder, wo seine Component den Schlüssel an sich selbst deklariert, in diesem Slot, für jede Verbindung, die er aufbaut. Keines der beiden Enden sieht die Attachments des anderen: Ein Attachment auf einer Verbindung landet allein beim Aufrufer, und die gerenderte Ausgabe eines Servers ist dieselbe, was auch immer die Verbindungen tragen, die ihn erreichen. Der Server erfährt nie, welchen Schlüssel ein Aufrufer hält, und der Aufrufer liest nur, was der Server veröffentlicht — eine Adresse und einen Modellnamen. Die beiden Enden stimmen überein, weil das Aggregate beide aus einem einzigen Parameter speist:

spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
router:
type: local/gateway/model-router # its `models` socket declares a `credential` slot
uses:
models:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Ob das ein Secret oder zwei sind, ergibt sich daraus, wo die beiden Enden Secrets auflösen. Ein Provider löst ein Secret per Referenz innerhalb eines Secret-Geltungsbereichs auf: ein Kubernetes-Namespace bei helm, ein Compose-Projekt bei compose, die Root-Konfiguration einer Boundary bei terraform und bei cloudformation ein Stack, in dem AWS-Konto und der Region, in die er deployt. Wo beide Enden in einem Geltungsbereich liegen, verweisen sie auf eine einzige Secret-Ressource. Wo sie in verschiedenen Geltungsbereichen liegen, hält jedes Ende eine eigene Secret-Ressource, realisiert aus demselben Store-Eintrag. Das Manifest wählt die Realisierung jedes Endes — nach Feature-Typ oder, für ein einzelnes Attachment, nach dessen Namen, der für das Attachment einer Verbindung <alias>.<slot> ist (local.credential oben). Da ein Parameter beide speist, lesen die beiden Realisierungen origin als dieselbe Art von Locator: beide den Namen eines Secret, beide den Schlüssel eines Store-Eintrags oder beide den Wert selbst.

Bei helm mit beiden Enden in einem Namespace führt das Binden von core/referenced-secret an helm/k8s-existing-secret und das Erfüllen des Parameters mit dem Namen eines Secret, das dieser Namespace enthält, model-keys, dazu, dass beide Enden es über den Namen referenzieren, und es wird kein Secret gerendert. Der Container des Servers trägt:

- name: VLLM_API_KEY
valueFrom:
secretKeyRef:
name: model-keys
key: api-key

und das Recipe des Routers liest denselben Namen und Schlüssel aus seiner Verbindung, unter .context.uses.local.features.credential.provides. Liegen die beiden Enden in verschiedenen Namespaces, erhält jedes Ende durch das Binden an helm/k8s-external-secret und das Erfüllen des Parameters mit dem Schlüssel eines Store-Eintrags ein eigenes ExternalSecret in seinem eigenen Namespace, die beide diesen einen Eintrag abrufen. Bei compose tragen beide Enden dieselbe Referenz ${VAR}, die Docker Compose aus der Umgebung ersetzt, mit der das eine Projekt gestartet wird. Diese Platzierung ist eine Konvention, der der Katalog der Standardbibliothek folgt; der Compiler vergleicht nichts zwischen den beiden Enden.

Ein Schlüssel bedient jeden Aufrufer. vLLM, TEI und TGI prüfen jeweils einen einzigen Schlüssel, daher legt jeder Aufrufer denselben Schlüssel vor, und der Server kann einen Aufrufer nicht vom anderen unterscheiden, wie viele Verbindungen ihn auch erreichen. Das ist eine eigene Grenze des Servers. TGI vergleicht seinen Schlüssel ohne Rücksicht auf Groß- und Kleinschreibung, sodass zwei Schlüssel, die sich nur darin unterscheiden, für ihn ein Schlüssel sind. Das LiteLLM-Modell und das LiteLLM-Gateway akzeptieren außerdem die Schlüssel, die sie selbst ausstellen, solange ihre Buchhaltungsdatenbank angehängt ist.

Ein Credential, das das Ziel generiert

Wo ein Release kein Credential liefert, greift eine Katalogentität oft auf einen Entwicklungs-Standardwert zurück — einen Inline-Wert in einem Recipe, einen Standardwert für den Parameter eines Moduls. Dieser Wert ist für jeden Leser des Katalogs derselbe, was für eine Evaluierung akzeptabel ist und für nichts anderes. core/random-password beseitigt die Notwendigkeit dafür: Niemand schreibt das Credential, weil das Ziel es generiert.

Der Build kann nicht der Ort sein, an dem das Passwort entsteht. Seine Ausgabe ist eine reine Funktion seiner Eingabe und trägt nie den Wert eines Secret, sodass ein zur Build-Zeit gezogenes Passwort sich bei jedem Build ändern und in den gerenderten Dateien stehen würde. Das FeatureRecipe rendert stattdessen eine Anforderung — eine Generator-Ressource, die die Secret-Ressource benennt, die sie füllt —, und das Ziel zieht den Wert zur Deploy-Zeit:

  • bei helm ein Controller im Cluster: der Passwortgenerator des External Secrets Operator, abgeglichen über ein ExternalSecret, oder der Controller kubernetes-secret-generator, der ein StringSecret abgleicht;
  • bei terraform das random_password des random-Providers, gezogen, wenn die Konfiguration angewendet wird;
  • bei cloudformation ein Secrets-Manager-Secret, das seinen eigenen String generiert, wenn der Stack es erstellt.

In jedem Fall benennt die gerenderte Ausgabe den Generator und die Secret-Ressource und trägt keinen Wert. Das ist eine Eigenschaft dessen, was der Build hat, kein Schutz, den er hinzufügt: Der Wert existiert nie, bevor das Ziel ihn erzeugt. Wo das Ziel ihn danach aufbewahrt, ist Sache des Ziels — Terraform bewahrt ihn im Plan und im State auf, ein Cluster in einem Secret.

Was auf dem Ziel laufen muss. Eine Anforderung wird nur dort erfüllt, wo etwas sie erfüllt. Bei helm ist das der Controller, und der Compiler kann den Cluster nicht untersuchen, um zu wissen, ob einer läuft, daher brechen die helm-FeatureRecipes den Build ab, es sei denn, das Release bestätigt die Voraussetzung mit infra.control_plane_present: true auf dem Attachment. Bei terraform und cloudformation generiert das Apply bzw. der Stack den Wert selbst, und vorher muss nichts laufen.

Wo es nicht verwendet werden kann. Compose führt keinen Controller aus und hat keine Ressource, die einen Wert generiert, daher realisiert dort kein FeatureRecipe core/random-password, und ein Build, der es auf compose bindet, bricht mangels eines solchen ab. Ein Release, das auf compose zielt, liefert sein Credential über core/secret-value, typischerweise als Variablenreferenz, die Docker Compose beim Start des Stacks ersetzt.

Wie ein Konsument es liest. core/random-password veröffentlicht dieselben provides.name und provides.key wie core/referenced-secret und trägt dasselbe Label feature.aggrega.ai/kind: secret, sodass ein Slot, der die Credential-Familie auswählt, es zulässt und ein Konsument ein generiertes Credential genau so liest wie eines, das bereits existiert.

Wie mehrere Konsumenten eines teilen. Ein Generator zieht für jede Anforderung einen neuen Wert, daher gilt die Regel zur gemeinsamen Nutzung aus dem vorherigen Abschnitt in verschärfter Form: Ein generiertes Credential, das in einem gemeinsamen Geltungsbereich — oder an jedem Konsumenten — angehängt ist, rendert eine Anforderung pro Konsument, und jede Anforderung zieht ein anderes Passwort, das eine Datenbank und ihre Clients nicht verwenden können. Ein generiertes Credential, das mehrere Konsumenten teilen, wird als eine Anforderung und viele Referenzen ausgedrückt: core/random-password auf einer Komponente, deren Wert name das Secret festlegt, das es füllt, und core/referenced-secret auf den anderen, gebunden an die Existing-Secret-Realisierung und auf denselben Namen gerichtet. Aus einem Parameter geschrieben, können die beiden nicht voneinander abweichen, und das Rendering trägt genau eine Anforderung, die jeder Konsument referenziert.

core/random-password ist nicht core/generated-secret. Jenes Feature übergibt ein Credential an eine Engine, die bereits seinen gesamten Lebenszyklus besitzt — eine verwaltete Datenbank, einen Datenbank-Controller — und rendert nichts. core/random-password rendert die Anforderung selbst, für eine Workload, deren Recipe erwartet, ein Credential übergeben zu bekommen.

Vorrang von Attachments

Ein Attachment kann in mehreren Geltungsbereichen gleichzeitig deklariert werden. Die Zuständigkeit für ein umstrittenes Feld wird durch drei Regeln aufgelöst, die in dieser Reihenfolge angewendet werden:

  1. Herkunft. Ein explizit geschriebenes Feld schlägt eines, das durch annotationsgesteuerte Expansion beigesteuert wurde, unabhängig davon, aus welchem Geltungsbereich beide stammen.
  2. Kompositionsautorität. Eine Deklaration in dem Aggregate, das Sie deployen, schlägt eine innerhalb eines Aggregate, das es komponiert, selbst wenn das komponierte Dokument sie im engeren Geltungsbereich deklariert hat.
  3. Spezifität. Innerhalb einer Autorenebene verfeinert der engere Geltungsbereich den breiteren Feld für Feld: Eine Füllung auf Komponentenebene überschreibt ein subsystemweites oder boundaryweites Attachment mit demselben Instanznamen nur für die Felder, die sie erwähnt, und die Felder, die sie weglässt, behalten die Werte des breiteren Geltungsbereichs.

Die Entwicklerseite liefert values und die Betreiberseite liefert infra, daher streiten die beiden nie um dasselbe Feld. Ein Credential-Feature, das seinen Locator von einer der beiden Seiten nimmt, deklariert ihn als zwei Felder, eines pro Säule, und seine eigene Assertion lehnt ein Attachment ab, das beide trägt, sodass der Vorrang auch dort keinen Gleichstand aufzulösen hat. Der Vorrang regelt nur Feldwerte; er ordnet die Auswertung nicht neu, die der Kaskadenfolge in 10-compilation-pipeline.md folgt.

Legacy-Charts, die eine formatierte Zeichenkette verlangen

Ein Chart verlangt manchmal eine einzelne Verbindungszeichenkette, in die Material eingebettet ist — oracle://admin:PASSWORD@HOST:1521/DB. Ein Ahead-of-Time-Compiler kann diese Zeichenkette nicht aus einer Store-Koordinate bauen, weil er das Material nie hält. Zwei unterstützte Wege:

Clusterseitiges Templating. Das Credential-FeatureRecipe emittiert eine Ressource, die die Zeichenkette im Cluster formatiert, mithilfe des eigenen Templatings des Vault-Operators. Die Anwendung referenziert dann das resultierende Plattform-Secret über den Namen, und der Compiler hat die Beziehung verdrahtet, ohne jemals das Material zu halten:

{
"apiVersion": "external-secrets.io/v1beta1",
"kind": "ExternalSecret",
"metadata": { "name": "oracle-dsn-secret" },
"spec": {
"target": {
"name": "oracle-formatted-dsn",
"template": {
"engineVersion": "v2",
"data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" }
}
},
"data": [
{ "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } }
]
}
}

Parameter-Hoisting. Das Aggregate deklariert einen typisierten Parameter, und die umgebende CI-Pipeline liefert den Wert zur Build-Zeit über die parameters: des Release — etwa eine Datei, die die Pipeline schreibt und das Release mit parameters: { $import: ./ci-parameters.yaml } importiert. Dies ist der explizite Ausweg, und er macht den Kompromiss sichtbar: Das Material fließt nun durch den Build, sodass die gerenderte Ausgabe es trägt und entsprechend behandelt werden muss.

Lokale Entwicklung

Der bewährte Weg für die lokale Entwicklung lässt die Entwicklerabsicht unverändert und tauscht die Bindung aus. Das Aggregate hängt weiterhin denselben Credential-Feature-Typ an; das lokale Manifest bildet diesen Typ auf ein lokales FeatureRecipe statt auf das store-gestützte ab. Der Compiler ruft weiterhin nichts ab — das lokale FeatureRecipe liefert einfach Provider-native Syntax, die die lokale Laufzeitumgebung auflöst: für Compose eine Variablenreferenz wie ${SECRET_NAME}, die in die Umgebung des Dienstes geschrieben wird und die Docker Compose beim Start des Stacks aus der Shell-Umgebung oder einer .env-Datei ersetzt. Ein Wechsel der Umgebung ist eine Änderung am Manifest.

Datengovernance rund um Credentials

Aggrega modelliert keine Datenschemata — Zeilen, Spalten und Dateien sind Angelegenheiten der Anwendung. Es modelliert die Governance-Identität von Daten mit Labels, und die Konvention der Standardbibliothek lautet:

  • Daten liegen in Komponenten, deren Ontologie-Label sie als zustandsbehaftet oder ressourcenartig kennzeichnet (component.aggrega.ai/type: stateful-server, resource). Auch ein Message Broker, der Payloads in Warteschlangen hält, gehört dazu: Er trägt stateful-server, wenn er seine eigene Festplatte besitzt, und resource, wenn das Release einen gehosteten verdrahtet, und das Regal messaging, unter dem er geführt wird, ist die separate Achse component.aggrega.ai/category.
  • compliance.aggrega.ai/data-class (public, internal, restricted) gibt diesen Daten eine semantische Identität. Die Konvention legt den Schlüssel und seine Werte fest, nicht, welche Komponenten ihn tragen: Keine Component der Standardbibliothek tut es, weil die Klasse der Daten, die eine Komponente hält, eine Aussage darüber ist, wie eine Systemlandschaft die Komponente nutzt, und keine Eigenschaft des Produkts, daher gibt eine Systemlandschaft sie an ihren eigenen Components an. Es ist ein gewöhnliches Label: Label-Selectors werten es aus, und ein Governance-Plugin, das ein Betreiber anhängt, kann es lesen und einen Build ablehnen. Der Compiler selbst interpretiert es nicht und stellt keine Klasse über eine andere — welche Klassen es gibt und wie sie sich ordnen, sind die eigenen Einstellungen der angehängten Policy, wie in ../language-reference/examples/policy-data-class-route/.

data-class und sensitive sind zwei Achsen, und wer sie zusammenlegt, verliert Information. Sie stehen nebeneinander und lassen sich leicht für eine einzige Oberfläche halten, also halten Sie die Unterscheidung fest:

compliance.aggrega.ai/data-classsensitive
Formabgestuft — public / internal / restrictedboolesch
Granularitätein ganzer Knotenein Schemablatt oder ein Attachment-Slot
Sagt auswelche Governance-Identität die Daten haben, die eine Komponente hältdass dieses Datum geheimes Material ist oder dass dieser Bindungspunkt es behandelt
Geschrieben alsein Label in metadata.labelsein Schlüsselwort an einer Deklaration

Keines ersetzt das andere: Sensitivität in das abgestufte Label zu zwingen, würde einer Tatsache eine Ordnung auferlegen, die keine hat, und eine Datenklasse auf ein Blatt zu zwingen, würde eine Granularität auferlegen, die die Klassifizierung nicht hat. Eine Entität kann beides tragen, und eine Komponente, die restricted-Daten hält und deren Credential-Slot als sensitive deklariert ist, sagt zwei getrennte wahre Dinge aus. Die Schlüsselwörter für Blatt und Slot werden in ../language-reference/vocabulary/compact-form-authoring.md „Ein Blatt als sensitiv deklarieren“ und ../language-reference/entities/component.md „Einen Slot als sensitiv deklarieren“ erläutert.

Verschlüsselung im Ruhezustand liegt bewusst außerhalb der Entwicklerabsicht und außerhalb des Compilers. Sie gehört in das Ops-Recipe für die zustandsbehaftete Komponente und in das Rendering-Plugin, das die Labels des Knotens liest und die verschlüsselte Speicherkonfiguration emittiert. Diese Platzierung ist eine Gestaltungsempfehlung dazu, wohin das Anliegen gehört — der Compiler prüft nicht, ob irgendein Recipe sie einhält.

Was hier eigenständig ist und was nicht

Die öffentliche Positionierung sollte klar und eng gefasst formuliert werden, damit Leser sie richtig einordnen können.

Eigenständig: Der Socket-Vertrag wird veröffentlicht, nicht inline deklariert. Der Vertrag, den ein Credential erfüllen muss — der Slot, seine Zustellungs-Allowlist, sein Label-Selektor —, wird von demjenigen, der sie veröffentlicht hat, auf der Katalog-Entität verfasst und liegt in einem Katalog, den ein Dritter pflegt. Ein Konsument beschreibt den Vertrag nicht inline in seiner eigenen Konfiguration; er füllt einen Vertrag, den jemand anderes veröffentlicht hat, und der Compiler prüft die Füllung gegen diese veröffentlichte Deklaration. Konsument und Vertragsautor sind verschiedene Personen, die in verschiedenen Repositorys und in verschiedenen Veröffentlichungszyklen arbeiten.

Eigenständig: Das Füllen ist durch Label-Selektoren eingeschränkt. Ein Slot kann angeben, welche Art von Sache ihn füllen darf (selector: "feature.aggrega.ai/kind=secret"), statt eine bestimmte Implementierung zu benennen. Die Prüfung ist eine Auswertung von Label-Mengen, sodass eine Entität eine Familie von Füllungen akzeptieren kann, von denen sie nie gehört hat, und eine neue Füllung wird zulässig, indem sie die richtigen Labels trägt.

Nicht eigenständig: das Inject-Mapping. Die Zuordnung „dieser lokale Umgebungsvariablenname erhält jenen erzeugten Wert“ ist ein bekanntes Muster; mehrere Konfigurations- und Deployment-Werkzeuge drücken dieselbe Idee in ihrer eigenen Syntax aus. Die Version von Aggrega ist ein vorab ausgewertetes Mapping, das in eine Zustellungs-Pipe eingefügt wird, aber die Idee gehört dem Ökosystem, nicht uns.

Nicht eigenständig: statische Vorab-Generierung. Das statische Erzeugen von Deployment-Artefakten aus einer Beschreibung höherer Ebene, ohne Zugriff auf einen laufenden Cluster zum Zeitpunkt der Generierung, ist keine Erfindung von Aggrega. Andere Werkzeuge tun das und taten es, bevor es Aggrega gab. Was Aggrega hinzufügt, ist die Schicht veröffentlichter Verträge darüber, nicht die statische Generierung selbst.

Keine Sicherheitsgrenze. Nichts in diesem Kapitel ist ein Vertraulichkeitsmechanismus. Das Credential-Modell ist ein Modell der Verdrahtung: Es entscheidet, woher ein Zeiger oder ein Wert stammt, wer ihn einschränken darf und wie er einen Container erreicht. Das Material zu schützen ist Aufgabe des Secret Stores, des Clusters und der Pipeline, die den gerenderten Baum verarbeitet.

Querverweise