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

Geheimnisse

Diese Seite erklärt eine einzige Idee, wie Zugangsdaten die Komponente erreichen, die sie benötigt, und ist kein ausführbarer Workspace. Erweiterte Plattform — eine Kubernetes-Plattform mit mehreren Grenzen zeigt beide Zustellungsmodelle in einem Workspace, den Sie selbst erstellen; schreiben Sie ihn in einen eigenen Ordner mit:

Terminal window
aggrega scaffold --example advanced-platform

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

Terminal window
cd advanced-platform
aggrega pull --release release.yaml
aggrega build --release release.yaml

Die Checkliste für die Secret-Zustellung

Zugangsdaten durchlaufen sechs Oberflächen, bevor sie einen laufenden Container erreichen. Dies sind die Berührungspunkte, die beim Verdrahten neuer Zugangsdaten zu prüfen sind:

SchrittOberflächeAktion
1featuresSchema: der ComponentDeklarieren des Zugangsdaten-Slots: sein Name, ob er required ist, und seine Allowlist inject: — die Zustellmechanismen, die eine Anbindung nennen darf, [env] oder [env, file] für einen transparenten Slot, [] für einen opaken.
2schema: des Zugangsdaten-FeaturesDefinieren, was ein Autor angibt: Die Zugangsdaten-Features der Standardbibliothek tragen das Label feature.aggrega.ai/kind: secret und nehmen den Locator der Zugangsdaten als origin und den Datenschlüssel als key entgegen.
3Aggregate features:Anfordern der Zugangsdaten, unter demselben Schlüsselwort features: wie jedes andere Feature: ihr type, ihre values und, nur bei einem transparenten Slot, ein Block inject:, der angibt, wie die Anwendung sie liest.
4FeatureRecipeRealisieren der Zugangsdaten für das Ziel: den Wert dort schreiben, wo die Komponente ihn liest, eine Ressource rendern, die ihn enthält, oder eine rendern, die ihn aus einem Secret-Store abruft.
5mappings.features.type des ManifestBinden des Zugangsdaten-Feature an sein FeatureRecipe, in derselben Stufe wie jedes andere Feature.
6RecipeLesen der Zugangsdaten bei einem opaken Slot: Das Recipe der Komponente liest den Locator, den die Zugangsdaten veröffentlichen, .features.<slot>.provides.name, und übergibt ihn dem eigenen Mechanismus des Produkts, etwa existingSecret eines Charts.

Ein transparenter Slot nutzt die ersten fünf; ein opaker Slot nutzt alle sechs, was der übliche Fall für paketierte Infrastruktur wie das Chart eines Anbieters ist.

Transparente und opake Slots

Ein transparenter Slot lässt den Entwickler festlegen, wie die Anwendung die Zugangsdaten liest. Ein opaker Slot überlässt die Zustellung dem Recipe, und eine Anbindung, die darauf einen Block inject: schreibt, hält den Build an. Im Beispiel deklariert core/datastore/mariadb je einen davon, und das Aggregate füllt beide, aus aggregate.yaml ohne seine Kommentare:

db:
type: core/datastore/mariadb
features:
root_password:
type: core/secret-value
values:
key: MARIADB_ROOT_PASSWORD
origin: dev-root-pw-change-me
user_password:
type: core/secret-provided
values:
origin: dev-app-pw-change-me
inject:
env:
- in: MARIADB_PASSWORD
from: value

root_password ist opak: core/secret-value stellt den Wert unter dem Schlüssel zu, den die Anbindung nennt, wo das Recipe der Datenbank ihn liest. user_password ist transparent: core/secret-provided veröffentlicht den Wert als value, und der eigene Block inject: der Anbindung stellt ihn in MARIADB_PASSWORD zu. Ein Block inject:, der einen Mechanismus nennt, den der Slot nicht aufführt, hält den Build an, ebenso einer, der einen Schlüssel nennt, den nichts veröffentlicht oder liest.

Bei einem opaken Slot, der mit referenzierbaren Zugangsdaten gefüllt ist, liest das Recipe der Komponente den veröffentlichten Locator, statt einen Namen abzuleiten, existingSecret: "{{ .features.root_password.provides.name }}", sodass das Secret, das ein FeatureRecipe ausgibt, und der Verweis darauf ein und derselbe String sind. MariaDB (Bitnami-Chart) — ein Zugangsdaten-Secret mit mehreren Schlüsseln baut diesen Fluss gegen das Chart eines Anbieters auf.

Zugangsdaten realisieren: eine Ressource oder eine zweistufige Pipeline

Die Kubernetes-Realisierungen der Standardbibliothek rendern die Ressource der Zugangsdaten aus einem kleinen Chart neben dem FeatureRecipe: helm/k8s-secret-from-parameter ein Secret, das den von einem Autor angegebenen Wert enthält, und helm/k8s-external-secret ein ExternalSecret, das der External Secrets Operator aus einem Secret-Store abgleicht. Zugangsdaten-Features erläutert beide im Einzelnen.

Ein FeatureRecipe kann Zugangsdaten stattdessen mit einer pipeline: aus zwei Schritten realisieren, jeder davon ein Plugin. Der erste, der Fetcher, schreibt die Store-spezifische Ressource — etwa ein ExternalSecret — und nennt dabei den Store-Eintrag, den die Werte der Anbindung angeben. Der zweite, der Injector, patcht die gerenderte Arbeitslast der Komponente, um das resultierende Secret in ihren Container einzuhängen, an den Variablen oder Dateien, die der Block inject: der Anbindung nennt und die der Schritt unter .inject liest. Der Wechsel zu einem anderen Secret-Store ersetzt den Fetcher; der Injector bleibt. Ein Schritt gibt die Ressourcen, die er hinzufügt, als Nebeneffekte und seine Änderungen an den gerenderten Dokumenten als Patches zurück; der Wasm-Plugin-Vertrag ist die Form von beiden.

Die eigenen Zugangsdaten eines Feature

Ein Feature kann eigene Zugangsdaten benötigen: ein Guardrail-Proxy, der sich bei einem Upstream-Dienst authentifiziert, ein Log-Shipper mit einem Ingest-Token. Das Feature deklariert den Slot in seinem eigenen featuresSchema, genau wie eine Component, und das daran gebundene FeatureRecipe liest, was diesen Slot füllt, wenn es die Arbeitslast des Feature rendert.

Anbindungen werden nicht verschachtelt. Die Zugangsdaten werden neben dem Feature angebunden, an derselben Komponente, unter dem Namen, den der Slot des Feature deklariert; der Slot-Name ist das, was beide verknüpft. Das Guard-Feature und die Komponente unten sind eigene Entitäten des Workspace; core/referenced-secret gehört zur Standardbibliothek.

# The Feature declares the slot
kind: Feature
metadata:
name: local/guard
spec:
appliesTo: "component.aggrega.ai/type in (server, worker)"
featuresSchema:
guard_api_key:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
---
# The Aggregate fills it beside the Feature
spec:
components:
finance-agent:
type: local/compute/guarded-worker
features:
ai-guard:
type: local/guard
guard_api_key:
type: core/referenced-secret
values:
origin: dev-guard-key-change-me
key: api-key

Das FeatureRecipe des Guards rendert eine Arbeitslast, deren Container den Slot referenziert, attachments: { GUARD_API_KEY: { from: guard_api_key, as: env } }, sodass der Verweis auf dem Container des Guards landet und auf keinem anderen. Das Recipe der Host-Komponente kann den Slot nicht referenzieren, weil er dem Feature gehört: Eine Arbeitslast, die danach greift, hält den Build an und nennt dabei den Slot. Ein Arbeitslast-Eintrag, der einen Slot nennt, den nichts füllt, hält ebenfalls an, da es keinen veröffentlichten Locator aufzulösen gibt.

Dasselbe gilt für die Verbindungen, die ein Feature zieht: Eine Verbindung im eigenen Block uses: des Feature trägt keine Anbindungen, sodass Zugangsdaten, die eine solche Verbindung braucht, ein Slot sind, den das Feature deklariert und der neben dem Feature gefüllt wird.

Die eigenen Zugangsdaten einer Verbindung

Ein Gateway, das zwei Modelle erreicht, kann jedem einen anderen Schlüssel präsentieren oder dem einen einen Schlüssel und dem anderen keinen. Ein Slot am Gateway hält einen einzigen Satz Zugangsdaten für die ganze Komponente, daher kommen die Zugangsdaten stattdessen auf die Verbindung: Der Socket des Gateways deklariert den Slot, den jede Verbindung durch ihn füllen darf, und jede Verbindung füllt ihn, oder nicht, für sich.

spec:
components:
router:
type: core/gateway/litellm
uses:
models:
gpt:
target: gpt
features:
credential: # a slot the models socket declares
type: core/referenced-secret
values:
key: api-key

Das Recipe des Gateways liest die Anbindung aus seiner Verbindung, unter .context.uses.gpt.features.credential, sodass ein Gateway, das mehrere Modelle erreicht, den eigenen Schlüssel jedes Modells liest; core/gateway/litellm stellt jeden als eigene Variable zu, die der Eintrag der Verbindung in seiner Routing-Tabelle nennt. Eine Anbindung unter einem Namen, für den der Socket keinen Slot deklariert, hält den Build an und nennt dabei die Slots, die er deklariert. Das Manifest kann die Zugangsdaten einer Verbindung anders realisieren als die übrigen, mit dem Schlüssel <connection>.credential in seiner Stufe pro Instanz. Zugangsdaten auf Verbindungen — ein Schlüssel pro Verbindung und ein Schlüssel an beiden Enden baut dies auf; ein Release kann eine solche Verbindung auch verdrahten und das Secret im infra der Anbindung nennen, wie Zugangsdaten-Features beschreibt.