Zugangsdaten teilen — pro Konsument, gemeinsam und beides zugleich
Zwei CrewAI-Agenten hinter einem OpenAI-kompatiblen Gateway. Der Socket model jedes Agenten deklariert einen Slot credential, daher wird der Schlüssel, den ein Agent dem Modell vorlegt, das er erreicht, an dieser Verbindung angebunden. Dieser Workspace füllt den Slot auf drei Arten, ohne eine einzige Katalogentität zu ändern: ein Schlüssel pro Verbindung, ein Secret, auf das jede Verbindung verweist, und ein gemeinsamer Standardwert, den eine Verbindung überschreibt.
Zwei Konsumenten sind der Kern der Sache. Mit einem einzigen Konsumenten sind die drei Formen nicht zu unterscheiden — der Unterschied ist, auf welches Secret jeder Konsument am Ende zeigt, und diese Frage hat keinen Inhalt, solange es nicht mehr als einen Konsumenten gibt.
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:
aggrega scaffold --example model-api-key-sharingDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd model-api-key-sharingBuild
Drei Releases, eines pro Form. Bauen Sie pro Lauf eines:
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/aggrega build --release release-shared.yaml --auto-pull # → dist/shared/aggrega build --release release-composed.yaml --auto-pull # → dist/composed/Jedes Release schreibt in sein eigenes Verzeichnis, sodass alle drei gerenderten Bäume nebeneinander bestehen und per Diff miteinander verglichen werden können.
Ein Release braucht sein Lockfile, bevor es gebaut wird. Lösen Sie auf einem frischen Checkout zuerst eines auf — entweder als eigenen Schritt oder indem Sie es vom Build füllen lassen:
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildDie Releases lösen ihre Katalogentitäten aus dem konfigurierten Katalog auf, daher ist kein Flag --catalog nötig.
Alle drei werden bewusst auf dem helm-Ziel gebaut. Das Beobachtbare, das die drei Formen unterscheidet, ist der Name des Secrets, das der Container jedes Agenten referenziert, und helm ist der Ort, an dem Zugangsdaten ein benanntes Kubernetes-Secret sind, das ein Container über seinen Namen referenziert. Zwei Manifests binden die Zugangsdaten: manifest.yaml an k8s-secret-from-parameter, das ein Secret aus dem Wert rendert, den die Anbindung trägt, für das Release pro Konsument; und manifest-existing-secret.yaml an k8s-existing-secret, das nichts rendert und jeden Konsumenten auf ein Secret verweist, das bereits im Namespace liegt, für das gemeinsame und das zusammengesetzte Release.
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 Workspace-Ordner noch keinen Ordner `model-api-key-sharing` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `model-api-key-sharing` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `model-api-key-sharing`. Rufen Sie anschließend das Tool `build` einmal für jedes Release auf, in dieser Reihenfolge — `release-per-consumer.yaml`, `release-shared.yaml` und `release-composed.yaml` —, jedes Mal mit `workspace_root` auf `model-api-key-sharing`, `release` auf diese Datei, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir, welche Dateien jeder Build geschrieben hat; sie liegen unter `model-api-key-sharing/dist/`.Pro Konsument — jede Verbindung hält ihren eigenen Schlüssel
aggregate-per-consumer.yaml füllt den Slot an der Verbindung jedes Agenten, mit einem anderen origin pro Agent:
researcher: type: core/ai-agent/crewai uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-key-change-meEine Anbindung an einer Verbindung wird zu einer der eigenen Anbindungen des Agenten, benannt nach der Verbindung und dem Slot — hier gateway.credential —, daher werden zwei Secrets ausgegeben, eines pro Agent, jedes mit dem eigenen Material dieses Agenten:
[… omitted: the apiVersion and the Secret kind]metadata: name: researcher-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml[… omitted: the apiVersion and the Secret kind]metadata: name: writer-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "writer-key-change-me"und jedes Deployment referenziert sein eigenes:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-gateway.credential key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: writer-gateway.credential key: OPENAI_API_KEYWird der Schlüssel eines Agenten widerrufen, läuft der andere weiter.
Gemeinsam — ein Secret, von jeder Verbindung aus referenziert
Zugangsdaten an einer Verbindung werden an dieser Verbindung geschrieben: Nichts, was anderswo angebunden ist, füllt sie. Daher teilen sich mehrere Konsumenten Zugangsdaten durch Authoring: Die Zugangsdaten jeder Verbindung lesen denselben Wert, und dieser Wert nennt ein Secret.
aggregate-shared.yaml deklariert einen Parameter und liest ihn an beiden Verbindungen:
parameters: team_model_key: type: string default: team-model-keycomponents: researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" writer: { ... } # the same credential, reading the same parameterDas Release bindet die Zugangsdaten an k8s-existing-secret, das origin als den Namen eines Secrets liest, das bereits im Namespace existiert. Es rendert überhaupt kein Secret — nur der Service des Gateways und die beiden Deployments werden geschrieben —, und beide Deployments referenzieren das eine Secret, das der Parameter nennt:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEYDas ist genau ein physisches Secret, außerhalb des Release von demjenigen erstellt, der es bereitstellt, und von jedem Konsumenten gelesen. Das Material des Schlüssels durchläuft nie eine verfasste Datei oder ein gerendertes Artefakt.
Was der Parameter trägt, folgt der Realisierung, die das Manifest bindet. Unter k8s-existing-secret ist er der Name eines Secrets. Wären die Zugangsdaten stattdessen an k8s-secret-from-parameter gebunden, würden dieselben zwei Verbindungen, die einen Parameter lesen, den Schlüssel selbst tragen, und der Build würde ein Secret pro Konsument rendern, jedes mit demselben Material: Das Rendering läuft pro Komponente, und diese Realisierung benennt das Secret, das sie rendert, nach der konsumierenden Komponente und der Verbindung. Der eine Parameter ist das, was die Konsumenten davor bewahrt, auseinanderzulaufen; welche Realisierung ihn liest, entscheidet, ob sie sich eine Ressource teilen. Im Cluster erzeugte Zugangsdaten werden auf dieselbe Weise geteilt — eine Anforderung und viele Referenzen; siehe Zugangsdatenmodell.
Zusammengesetzt — gemeinsamer Standardwert, eine Verbindung überschreibt ihn
aggregate-composed.yaml behält den gemeinsamen Parameter als Standardwert bei und lässt eine Verbindung ein eigenes Secret nennen:
researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-model-key # this connection's own Secretwriter: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" # the shared defaultDie Überschreibung ist das, was diese eine Verbindung verfasst; nichts kaskadiert auf sie, und writer behält das gemeinsame Secret unverändert:
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-model-key key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEYDie Zugangsdaten einer Verbindung sind eine vollständige eigene Anbindung, daher wiederholt eine Überschreibung jedes Feld, das sie benötigt — hier den Feature-Typ, key und origin — und erbt keines vom Standardwert.
Was der Slot bringt
core/ai-agent/crewai deklariert den Slot einmal, an seinem Socket model, und die drei Formen sind alle Entscheidungen, die im Aggregate getroffen werden:
usesSchema: model: selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api" required: true inject: [env, file] featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]Der Slot ist optional, daher ist eine vierte Form, überhaupt nichts anzubinden: Entfernen Sie den Block features: aus beiden Verbindungen, und der gerenderte Baum verliert jeden env-Eintrag OPENAI_API_KEY, sodass die beiden Deployments und der Service des Gateways übrig bleiben. Nichts wird erfunden, um die Lücke zu füllen. Die Katalogentität ist in jedem Fall identisch; der Autor entscheidet.
Das baut, weil das Gateway hier, core/ai-model/openai-compatible, kein Label component.aggrega.ai/hosting trägt. Eine Verbindung, die ein Ziel erreicht, das der Katalog mit managed kennzeichnet — etwa core/ai-model/openai —, bricht ohne Zugangsdaten den Build an der eigenen Assertion des Agenten ab, es sei denn, die Verbindung gibt in ihren values an, dass das Ziel keine benötigt, unauthenticated: true.
Der Slot ist außerdem agnostisch gegenüber der Familie (feature.aggrega.ai/kind=secret lässt jede der beiden Zugangsdaten-Familien zu), und genau das erlaubt es demselben Agenten, auf helm ein referenzierbares Secret und auf compose Zugangsdaten mit injiziertem Wert anzunehmen. Zustellung von Zugangsdaten — secretKeyRef von Ende zu Ende arbeitet diese Aufteilung nach Provider durch, und sein negatives Release zeigt, was passiert, wenn nicht referenzierbare Zugangsdaten eine Referenz erfüllen sollen.
Determinismus
Alle drei Releases werden mit --verify-determinism gebaut, das jeden Knoten zweimal rendert und die ausgegebenen Bytes vergleicht:
aggrega build --release release-shared.yaml --auto-pull --verify-determinismEin Neubau eines der drei aus einem sauberen Baum reproduziert seine gerenderte Ausgabe Byte für Byte.