Feature
Die konzeptionelle Rolle der Entität Feature (das modulare operative Merkmal in Domäne 2) wird in architecture/04-entity-taxonomy.md beschrieben. Die Unterscheidung zwischen operativen Features und Credential-Features (denen mit dem Label feature.aggrega.ai/kind: secret) wird in architecture/08-credential-model.md beschrieben. Das Vokabular der semantischen Labels, das Feature-Selektoren verwenden, steht in entities/component. Diese Seite behandelt die Authoring-Oberfläche des Feature-Katalogs.
Ort im Katalog
Anders als Components (die dreisegmentige URIs mit Kategorie-Unterverzeichnissen verwenden) sind Features flach organisiert: ein Verzeichnis pro Feature unter seinem Publisher, das ein Verzeichnis pro Version enthält.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...OCI-URI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (z. B. hub.aggrega.ai/feature/core/data-masking:1.0.0).
Authoring-Vertrag
Features deklarieren:
metadata.labels: Verwenden Siefeature.aggrega.ai/kind: secret, um ein Feature als Credential-Feature zu kennzeichnen. Das Label ist beschreibende Metadaten für den Autor, für die Katalog-Website und für Label-Selektoren; kein Zweig des Compilers liest es, und was eine Anbindung erzeugt, entscheidet das FeatureRecipe, auf das das Manifest ihren Typ abbildet, nicht das Label. Ein Credential-Feature und ein gewöhnliches Feature werden auf dieselbe Weise angebunden, auf derselben Anbindungsoberfläche, in jedem Geltungsbereich. Die Credential-Familie der Standardbibliothek teilt sich nach dem Ergebnis:core/secret-valueliefert einen Wert in die Inject-Pipe;core/referenced-secretbenennt eine referenzierbare Secret-Ressource (ein Kubernetes Secret, ein AWS-Secrets-Manager-Secret, einen Vault-Eintrag), die entweder die Ausgabe seines FeatureRecipe erzeugt oder die bereits existiert, und deklariert einenschema.provides-Ausgabevertrag —name(der providerneutrale Locator der Ressource) undkey(das Datenfeld darin) —, den ein Konsument als.features.<slot>.provides.<key>liest, um auf die Ressource zu verweisen, ohne ihren Namen neu abzuleiten;core/referenced-secret-setmaterialisiert eine Ressource mit einer vom Aufrufer gelieferten Menge von Datenschlüsseln und veröffentlicht nur den Locator, für einen Konsumenten, dessen Ziel die Schlüsselnamen, die es liest, bereits kennt;core/secret-providedlegt den Wert eines bereits vorhandenen Secrets offen;core/generated-secreterzeugt nichts, weil die Ziel-Engine die Zugangsdaten selbst generiert und verwaltet, daher deklariert es wedervaluesnochprovides, und seine FeatureRecipes sind reine Verdrahtung, die keine Bytes rendert. Zwei Achsen trennen die Mitglieder: wer das Material liefert — ein Autor schreibt es oder benennt, woher es zu holen ist, oder die Ziel-Engine besitzt es vollständig, wie beicore/generated-secret— und was die Anbindung ergibt: einen injizierten Wert, eine referenzierbare Ressource oder gar nichts Gerendertes. Jedes Mitglied ist den anderen auf derselben Anbindungsoberfläche gleichgestellt, sodass ein Credential-Slot immer gebunden ist und sich zwischen Releases nur ändert, was ihn bindet. Ein Credential-Feature, das einenschema.provides-Vertrag deklariert, verpflichtet jedes FeatureRecipe, das es implementiert, diese Schlüssel zu veröffentlichen — andernfalls hält der Build an —, und derselectoreinesfeaturesSchema-Slots zielt auf das Familienmitglied, das er benötigt.usesSchema(optional): Deklariert die topologischen Sockets, die das Feature konsumieren kann (z. B. denpath/key-Socket eines Credential-Features, der auf einen Vault zielt). Siehe architecture/13-catalog-and-registry.md §2 für den Split-Schema-Mechanismus.schema: Validiert die Blöckevaluesundinfrader Feature-Anbindung — die kognitive Absicht, die der Entwickler bei jeder Anbindung im Aggregate konfiguriert (valuessind die Domäne des Entwicklers, und das Release-Schema verbietetvalues:bei Feature-Anbindungen), und die Kapazität, die der Operator pro Umgebung im Release festlegt (infra). Ein Feld, das einendefault:deklariert, wird sowohl dagegen validiert als auch in die gerenderte Säule eingesetzt, wenn niemand es schreibt; siehe Feature-Geltungsbereich und Authoring-Form. Akzeptiert JSON Schema 2020-12, ausgedrückt in der kompakten YAML-Kurzschreibweise (der Standard; siehevocabulary/compact-form-authoring.md) oder in vollständigem JSON-Schema-YAML, mit dokumentübergreifendem$ref:auf SchemaLibrary-Einträge für gemeinsame Formen (siehevocabulary/cross-document-ref.md). Ein Blatt, das geheimes Material trägt, deklariertsensitive: true— die Credential-Features der Standardbibliothek kennzeichnen das Blatt, das das Material hält, und lassen ihre veröffentlichten Locators bewusst ungekennzeichnet, da ein Ressourcenname und ein Datenschlüssel beide öffentlich sind. Das Schlüsselwort und die Grenze dessen, was seine Deklaration bewirkt, stehen invocabulary/compact-form-authoring.md„Ein Blatt als sensibel deklarieren“.featuresSchema(optional): Deklariert die Anbindungs-Slots, die das Feature für seinen eigenen Betrieb benötigt — ein Feature deklariert Slots genau wie eine Component, sodass ein Feature, das selbst Zugangsdaten benötigt (etwa den API-Schlüssel eines Datadog-Sidecar-Features), den Bindungspunkt benennt, statt auf die Slots der Host-Component zuzugreifen. Siehe Die eigenen Zugangsdaten eines Features für ein Feature, das seinen eigenen Slot deklariert, und ein FeatureRecipe, das liest, was ihn füllt. Jeder Slot akzeptiert dieselben Felder wie einfeaturesSchema-Slot einer Component, mit derselben Semantik — einschließlich eines optionalenselector(ein Label-Selektor im Kubernetes-Stil, der einschränkt, welches Feature den Slot füllen darf, das Slot-Gegenstück zu einemusesSchema-Socket-Selektor; eine Füllung, deren Labels ihn nicht erfüllen, hält an, und der Selektor wird gegen die Labels des angebundenen Features ausgewertet und gegen nichts anderes), eines optionalensensitive(das deklariert, dass alles, was den Slot bindet, geheimes Material verarbeitet — eine Aussage über den Bindungspunkt statt über eine bestimmte Füllung) und derselben Offenheit: Das Deklarieren eines Slots verbietet nie eine Anbindung unter einem Namen, den kein Slot deklariert. Die vollständige Feldtabelle, die Sensibilitätsdeklaration auf Slot-Ebene und wie sie sich von der eines Schema-Blatts unterscheidet, sowie die zwei Formen, in denen eine Slot-deklarierende Entität bereitgestellt wird, stehen alle in entities/component.md „Anbindungs-Slots“.appliesTo/appliesToAnyOf: Label-Selektoren, die steuern, an welche Components das Feature angebunden werden kann. Sie werden von der nativen Label-Matching-Engine des Compilers während der statischen Analysephase ausgewertet. Siehe Label-basierte Anbindung unten und architecture/13-catalog-and-registry.md §2 „Selektoren im Kubernetes-Stil“ für die Referenz zur Selektor-Syntax.interoperability(optional): Ein verschachtelter Block mitconflictsWith— den Features, mit denen zusammen dieses Feature keine Komponente erreichen kann. Der Build hält vor dem Rendern an, wenn eine Komponente am Ende beide trägt, unabhängig davon, in welchem Geltungsbereich jedes angebunden wurde. Siehe Derinteroperability-Block unten für die vollständige Erläuterung.
Das strukturelle Rendering eines Features ist an sein entsprechendes FeatureRecipe gebunden, das die Feature-Schnittstelle auf eine konkrete Infrastrukturimplementierung abbildet.
Label-basierte Anbindung
Die beiden Applies-Selektoren im Feature-Schema steuern, an welche Components das Feature angebunden wird, ausgewertet von der nativen Label-Matching-Engine des Compilers während der statischen Analysephase:
appliesTo— eine Label-Selektor-Zeichenkette im Kubernetes-Stil; die Oberfläche für AND-Komposition. Kommagetrennte Anforderungen müssen alle gelten, mit dem vollständigen Operator-Vokabular:key=value,key!=value,key in (v1, v2),key notin (v1, v2), bloßeskey(Label vorhanden),!key(Label fehlt). Ein Feature, dasappliesTo: "datastore.aggrega.ai/engine=vector"deklariert, wird nur an Components angebunden, die genau dieses Schlüssel-Wert-Paar als Label tragen;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"drückt „jeder Server oder Worker, der keine eingeschränkten Daten hält“ in einer einzigen Selektor-Zeichenkette aus.appliesToAnyOf— die Oberfläche für OR-Komposition. Eine Liste von Selektor-Elementen, bei der es genügt, dass ein einzelnes Element passt. Jedes Element ist entweder ein Selektor in Zeichenkettenform (dieselbe Grammatik wieappliesTo; Anforderungen innerhalb der Zeichenkette werden mit AND verknüpft) oder eine flache Schlüssel-Wert-Map für reine Gleichheitsprüfung. Wird verwendet, wenn ein Feature zu mehreren nicht zusammenhängenden Komponentenformen passt — etwa ein Observability-Feature, das entweder für{ component.aggrega.ai/type: worker }ODER für{ component.aggrega.ai/type: task }gilt, ohne die beiden in eine einzige Selektor-Zeichenkette zu zwingen.
Ohne die Any-of-Form müssten Architekten dasselbe Feature-YAML für jede nicht zusammenhängende Komponentenform duplizieren, zu der das Feature passt. Die beiden Formen lassen sich kombinieren: Ein Feature darf beide deklarieren, und die Ergebnisse werden über die Formen hinweg mit AND verknüpft — die appliesTo-Zeichenkette muss gelten und mindestens ein appliesToAnyOf-Element muss passen. Ein ausgelassener oder leerer Selektor deklariert keine Einschränkung und passt auf jede Label-Menge.
Eine Selektor-Zeichenkette wird bei jeder Auswertung einer Anbindung des Features gegen die sechs Formen gelesen, und eine Anforderung außerhalb davon stoppt den Build, statt als ein anderer Selektor gelesen zu werden: eine leere Anforderung (ein führendes, abschließendes oder doppeltes Komma oder eine Zeichenkette nur aus Trennzeichen), ein Schlüssel, der Leerraum oder eines der Zeichen =, !, (, ) und das Komma enthält, und eine in (- oder notin (-Menge, die nicht geschlossen ist. Das fängt die Fehler ab, die sonst stillschweigend das Gegenteil des Gemeinten auswählen würden: appliesTo: "!tier=frontend", geschrieben, um ein Feature von Frontends fernzuhalten, wird abgelehnt, weil ! einen Label-Schlüssel benennt und nichts anderes — tier!=frontend ist die Art, einen Wert auszuschließen —, und tier in frontend wird zugunsten von tier in (frontend) abgelehnt. Ein Wert ist der Text nach seinem Operator, welche Zeichen er auch enthält, sodass tier==frontend nach einem Label fragt, dessen Wert =frontend ist. Der Abbruch nennt das Feature, seinen Selektor und die Anforderung, die nicht gelesen werden konnte. Ein Feature, das nichts anbindet, wird nie ausgewertet, sodass ein fehlerhafter Selektor darauf erst gemeldet wird, wenn eine Anbindung es benennt.
Siehe architecture/13-catalog-and-registry.md §2 „Selektoren im Kubernetes-Stil“ für die Referenz zur Selektor-Syntax — die Grammatik, die ein Feature-Selektor akzeptiert, ist dieselbe Grammatik, die usesSchema-Socket-Selektoren akzeptieren, die Zeichenkettenform, die Kubernetes-Nutzer von kubectl get -l kennen.
Der interoperability-Block
Das Feature-Schema deklariert einen optionalen spec.interoperability-Block mit einer einzigen Steuerung: mit welchen anderen Features dieses Feature auf einer Komponente koexistieren kann.
interoperability.conflictsWith — eine Liste der Features, die sich mit dem definierten Feature gegenseitig ausschließen, jedes so geschrieben, wie der type einer Anbindung ein Feature benennt. Sie verhindert das Erzeugen inkompatibler Konfigurationen — etwa das Anbinden sowohl eines reinen TCP-Mesh als auch eines HTTP-fähigen Proxys an dieselbe Komponente.
Der Build hält an, bevor irgendetwas gerendert wird, wenn eine Komponente am Ende dieses Feature und ein Feature trägt, das seine Liste nennt. Entscheidend ist die Reichweite: Eine Anbindung erreicht die Komponente, an der sie geschrieben ist, und jede Komponente innerhalb des Subsystems oder der Grenze, an der sie geschrieben ist, verschachtelte Grenzen eingeschlossen; eine Anbindung, die an einem Komponenteneintrag des Release geschrieben ist oder durch annotationsgesteuerte Expansion erzeugt wird, erreicht ihre Komponente auf dieselbe Weise. Ein deklarierter Konflikt hält also an, wenn die beiden Features an dieselbe Komponente angebunden sind, wenn eines an einer Grenze und das andere an einer Komponente darin hängt, wenn eines an einer äußeren Grenze und das andere an einer darin verschachtelten Grenze hängt, die eine Komponente enthält, und wenn eines an einem Subsystem und das andere an einer Komponente in diesem Subsystem hängt. Zwei Features, die an benachbarte Grenzen ohne gemeinsame Komponente angebunden sind, treffen nie aufeinander, und eine Grenze ohne Komponente erreicht nichts — in keinem der Fälle wird angehalten.
- Eine Deklaration genügt. Der Build hält an, wenn die Liste eines der beiden Features das andere nennt; das zweite Feature muss das erste nicht umgekehrt auflisten.
- Namen, unabhängig von den Versionen. Jeder Eintrag und der Typ jeder Anbindung werden ohne jegliche Version verglichen, sodass ein Eintrag
core/fixed-replica-controllerauf eine Anbindung voncore/fixed-replica-controller:2.0.0passt und ein Eintrag mit einer Version auf jede Version des Features passt, das er nennt. - Es liest nur Namen. Der Compiler vergleicht die Namen, die der Autor des Features deklariert hat, mit den Features, die eine Komponente trägt — dieselbe Art der Auswertung wie bei
appliesTo, über Daten, die der Autor geschrieben hat. Ob zwei Features inkompatibel sind, ist das Urteil des Autors, und die Liste ist der Ort, an dem es festgehalten wird.
Der Abbruch nennt das Feature, dessen Liste das andere nennt, jede Stelle, an der jedes der beiden angebunden wurde — an der Komponente im Aggregate, an einem Subsystem, an einer Release-Grenze mit ihrem Pfad, an einem Komponenteneintrag des Release oder durch annotationsgesteuerte Expansion einer benannten Annotation — und die Komponente, an der sie aufeinandertreffen. Ein Paar, das auf mehreren Komponenten aufeinandertrifft, wird für jede einmal gemeldet. Siehe errors/fatal-halts.md für die Meldung.
Beispiel:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerDieses Feature wird nur an Components vom Typ server angebunden und deklariert die Inkompatibilität mit einem anderen replikasteuernden Feature: Ein Build, in dem irgendeine Komponente am Ende beide trägt, hält vor dem Rendern an. Ein FeatureRecipe, das den Namen der Komponente benötigt, an die es angebunden ist — etwa um einen Autoscaler auf sein Ziel zu richten —, liest ihn aus seinem Template-Kontext und schreibt ihn überall dorthin, wo seine Ausgabe ihn braucht: .context.instance_id ist die Identität der Komponente, und .context.rendered_name ist der Name, den der eigene Provider der Komponente den Ressourcen gibt, die er für sie rendert, und mit ihm wird eine Ressource adressiert — unter helm der Name des Deployments, das eine synthetisierte Arbeitslast ausgibt, und der Release-Name, aus dem ein Chart seine eigenen Namen bildet.
Vererbung über extends
Ein Feature kann spec.extends: <feature-name> deklarieren, das auf ein Basis-Feature verweist, dessen Authoring-Oberfläche es erbt. Die Referenz benennt die Basis über ihren metadata.name, nicht über die Registry-Koordinate, unter der das Feature veröffentlicht wird, und akzeptiert dieselben drei Versionsformen wie jede Katalogreferenz: ohne Version (core/queue) für die höchste verfügbare Version, exakt (core/queue:1.0.0) oder ein Caret-Bereich (core/queue:^1.0.0). Der Compiler durchläuft die Elternkette beim Laden des Katalogs, prüft, dass die Kette azyklisch ist, und führt dann die Eltern-Specs in das Kind zusammen, um ein einziges aufgelöstes Feature zu erzeugen. Die vom Kind geschriebenen Felder haben bei Schlüsselkollisionen Vorrang; metadata.labels und metadata.annotations des Elternteils, die Selektoren appliesTo / appliesToAnyOf, der interoperability-Block, usesSchema, featuresSchema und die JSON-Schema-2020-12-Deklarationen in schema werden automatisch nach unten zusammengeführt. Jedes andere metadata-Feld ist wörtlich das des Kindes, sodass Identität und Herkunft nie vererbt werden.
Was das metadata: eines Features erbt. labels und annotations werden entlang der Kette pro Schlüssel zusammengeführt, die Basis zuerst, wobei bei einem gemeinsamen Schlüssel der Wert des erweiternden Features gewinnt — dieselbe Regel, der Components folgen. Der Rest von metadata: wandert nicht mit: name, version, description, maintainers, license, repository, home und keywords gehören dem erweiternden Feature selbst, genau wie geschrieben.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }Das zusammengeführte core/kafka-queue erbt appliesTo vom Elternteil, erbt die Eigenschaften values.qos und infra.partition_count und fügt values.compression_codec hinzu. Ein Kind, das appliesTo explizit deklariert, überschreibt den Selektor des Elternteils vollständig (die Zusammenführung von Label-Selektoren ist nicht tief — der Selektor des Kindes ersetzt den des Elternteils). Das schema.values.qos eines Kindes überschreibt die Deklaration des Elternteils für diese Eigenschaft.
Wie jeder Teil der Anbindungsoberfläche vererbt wird. Die beiden Selektorformen werden unabhängig voneinander vererbt, weil sie sich kombinieren, statt sich zu ersetzen: Jede vorhandene Form muss gelten — die appliesTo-Zeichenkette muss passen, und mindestens ein appliesToAnyOf-Element muss passen —, während eine fehlende Form nichts einschränkt. Ein Feature kann also den AND-Selektor seiner Basis übernehmen und zugleich eine eigene OR-Menge deklarieren. Der interoperability-Block wird Feld für Feld vererbt — ein Kind, das den Block ohne conflictsWith-Liste deklariert, trägt weiterhin die Liste, die seine Basis deklariert hat, während ein Kind, das sein eigenes conflictsWith deklariert, die Liste der Basis ersetzt, statt sie zu ergänzen. Ein Feature, das keines der drei deklariert, wird genau dort angebunden, wo seine Basis angebunden wird.
Vererbung ist Schema-Zusammenführung, nicht Schnittstellenbindung. Eine extends:-Kette eines Features erzeugt ein einziges aufgelöstes Feature, keine polymorphe Familie. Die URI des Basis-Features aus der Kette ist nicht das, worauf das Feld feature: einer Manifest-Bindung verweist — Manifests binden über die URI des Blatt-Features, und das aufgelöste Schema enthält die geerbten Eigenschaften. Der Feature-Vertrag, den ein FeatureRecipe mit implements: umsetzt, ist ebenso die Blatt-URI; FeatureRecipes durchlaufen die Vererbungskette nicht.
aggrega pull ruft die Basis ab. Ein Basis-Feature ist eine Abhängigkeit jedes Release, das ein Feature anhängt, das es erweitert, unabhängig davon, ob es sonst irgendwo genannt wird. aggrega pull folgt jedem extends: bis zum Ende der Kette, ruft eine Basis, die kein Katalogverzeichnis enthält, aus der Registry ab und verzeichnet jede Basis im Lockfile des Release, referenziert vom spec.extends des Feature, das sie nennt; ein Build liest die Basis von dort.
Fehlermodi. Eine zyklische extends:-Kette und ein Elternteil, das keine Katalogentität bereitstellt, halten den Build an und nennen das Feature, von dem die Auflösung ausging, das Feature, dessen extends:-Zeile zu öffnen ist, und die Referenz, die es deklariert. Die Meldungen stehen unter Cyclic extends on Components or Features (Zyklisches extends bei Components oder Features) und An extends: chain cannot be assembled (Eine Kette kann nicht zusammengesetzt werden).
Für das umfassendere Vokabular zu Vererbung und Schnittstellen über Components, Features und Credential-Features hinweg siehe vocabulary/inheritance-and-interface.md.
Komponierbarkeit: Der Gesellschaftsvertrag der Reinheit
Die Konvention der Standardbibliothek lautet ein Feature, eine interne Funktion — ein Observability-Sidecar ist ein Observability-Feature; ein Netzwerk-Proxy-Sidecar ist ein Netzwerk-Proxy-Feature; sie werden nicht zu einem einzigen Verbund mit zwei nicht zusammenhängenden Belangen kombiniert. Die Konvention hält einzelne Features komponierbar, unabhängig versioniert und unabhängig anbindbar.
Der zentrale Go-Compiler setzt diese Konvention nicht durch. Feature-Definitionen mit gemischten Belangen sind syntaktisch zulässig und kompilieren fehlerfrei. Die Durchsetzung ist optional:
- Unternehmen, die interne Kataloge erstellen, können ein eigenes Linter-Plugin schreiben, das Feature-Definitionen in CI/CD prüft und warnt, wenn die
appliesTo-Labels eines einzelnen Features nicht zusammenhängende Fähigkeitsdomänen überspannen. - Ein Feature-Autor, der in
interoperability.conflictsWithfesthält, dass sich zwei Features überschneiden würden, entscheidet sich für eine Prüfung zur Build-Zeit: Der Compiler hält überall dort an, wo die beiden eine Komponente erreichen. Er vergleicht die deklarierten Namen und sonst nichts, setzt also die Deklaration durch, die ein Autor geschrieben hat, und nicht die Reinheitskonvention selbst.
Open-Source-Features der Standardbibliothek folgen der Reinheitskonvention aus Authoring-Disziplin; Unternehmenskataloge dürfen davon abweichen, wenn ein eng gekoppelter Verbund wirklich zum Deployment-Modell passt.
Was ein Feature rechtfertigt, und wohin die eigene Stellschraube eines Produkts gehört
Ein Feature ist eine Anbindung: Es bringt etwas mit, das der Entwickler oder der Operator bewusst anbindet — Ressourcen, einen Pipeline-Schritt, Verdrahtung —, und die Konvention der Standardbibliothek lautet, dass es von mindestens zwei unabhängigen Produkten eingehalten werden kann. Diese zweite Hälfte ist der Test, der vor dem Verfassen anzuwenden ist, denn Portabilität ist das, was das Wort Anbindung verspricht. Eine Anbindung besagt, dass die Fähigkeit übertragbar ist: Binden Sie sie an eine Komponente an, binden Sie sie an eine andere an, und die Realisierung jedes Produkts hält sie auf ihre eigene Weise ein.
Eine Fähigkeit, die nur ein einziges Produkt im Feld besitzt, ist die eigene Stellschraube dieses Produkts und kein Feature. Sie gehört als verfasster Wert auf die eigene Oberfläche dieses Produkts, die der Autor, der darüber entscheidet, in seiner eigenen Säule setzt und neben allem anderen liest, was dasselbe Produkt konfiguriert. Sie stattdessen als Feature zu veröffentlichen, verspricht eine Portabilität, die kein anderes Produkt liefern kann: Die Anbindung benennt konstruktionsbedingt ein einziges Produkt, sodass ein Autor, der sie an das nächste Produkt anbindet, zu dem er greift, auf einen Build trifft, der unter Nennung des Typs anhält, und das Feature hat eine Fähigkeit gelehrt, die es nie hatte.
Der Test zählt Produkte im Feld, nicht Komponenten in diesem Katalog, jedes anhand seiner eigenen aktuellen Konfigurationsreferenz gelesen. Zwei unabhängige Produkte, die eine Fähigkeit implementieren, machen sie portabel, unabhängig davon, wie viele von ihnen hier ausgeliefert werden; daher kann ein Feature deklariert werden, bevor irgendetwas im Katalog es realisiert — eine Anbindung hält dann den Build unter Nennung des Typs an —, und jede ausgelieferte Realisierung ist ein FeatureRecipe für ein einzelnes Produkt, das die Anbindung auf die Weise einhält, in der dieses Produkt sie konfiguriert.
Das Pinning von Upstream-Zertifikaten ist das ausgearbeitete Beispiel. Ein Pin ist eine Kontrolle darüber, welchen Schlüssel ein Upstream vorlegen darf: Akzeptiert wird nur ein Zertifikat, dessen öffentlicher Schlüssel einem entspricht, den das Release bereitstellt. Das ist eine andere Zusicherung, als zu verlangen, dass sich das Zertifikat eines Upstreams zu einem Vertrauensanker verketten lässt, den das Release bereitstellt, und wiederum eine andere, als zuzusichern, was das Subject eines Zertifikats aussagt — beide legen fest, was ein Zertifikat aussagen muss, während ein Pin festlegt, welcher Schlüssel es sein muss. Mehrere Gateways hier können gegen einen Anker verifizieren, weshalb dataplane.aggrega.ai/upstream-tls: trust-anchor ein Wert ist, auf den ein Selektor passen kann. Pinning ist eine separate Fähigkeit, und mindestens zwei unabhängige Produkte implementieren sie für die Verbindungen, die sie zu einem Upstream öffnen: Tyk nimmt den öffentlichen Schlüssel des Upstreams im PEM-Format entgegen, und Envoy nimmt einen Hash davon entgegen. Es ist also ein Feature, core/upstream-key-pinning, dessen Selektor dataplane.aggrega.ai/upstream-pinning: public-key benennt, und was dieser Katalog realisiert, wird Produkt für Produkt beantwortet: core/gateway/tyk trägt den Wert und ein FeatureRecipe für jedes seiner Ziele, während die Gateways hier, die Envoy einbetten, dessen Pin-Einstellung nur für die von Clients vorgelegten Zertifikate oder gar nicht bereitstellen, sodass sie keinen Wert tragen und eine Anbindung an sie am Selektor anhält. Ein Pin schränkt ein, was ein Upstream vorlegen darf; er ist eine Kontrolle, keine Zusicherung, dass die Verbindung im Übrigen einwandfrei ist.
Zwei Grenzen des Tests, und die zweite ist die Hälfte, die am leichtesten wegfällt:
- Es ist Autorendisziplin, keine Prüfung des Compilers. Ein Feature, das Optionen deklariert, die kein Produkt implementiert, besteht die Schemavalidierung, den Linter für die Veröffentlichung und ein Rendering gleichermaßen — der Compiler interpretiert nicht, was ein Feature verspricht. Das Urteil bleibt beim Katalogautor.
- Dass ein Produkt eine Option nicht einhalten kann, ist kein Grund, diese Option zu streichen. Wo zwei oder mehr Produkte eine Fähigkeit unter Namen ausliefern, die sich gruppieren lassen, ist die Fähigkeit portabel und das Feature behält sie; das Produkt, das sie nicht einhalten kann, lehnt sie ab. Ein Feature, das auf das reduziert ist, was jedes Produkt unterstützt, hat kaum noch etwas zu sagen.
Feature-Geltungsbereich und Form des Authorings
Das spec.schema eines Feature definiert die Formen values: und infra: des Feature selbst — die kognitive Absicht, die der Entwickler pro Feature-Anbindung im Aggregate konfiguriert (values), getrennt von den Kapazitätszahlen, die der Operator pro Umgebung festlegt (infra). Die Säulen des Feature liegen in eigenen Namespaces und werden unabhängig von den Säulen der Host-Component validiert. Wenn der Entwickler ein Feature autoscaler an eine Component web-server im Aggregate anbindet, trägt das Aggregate die values: der Component (Host-Form) plus die values: des Feature (die Form der Skalierungsabsicht — welche Metrik die Skalierung steuert); die für den Operator bestimmten Kapazitätszahlen (min_replicas / max_replicas) fließen über den infra:-Block des Release an der Feature-Anbindung.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10Das schema: des Feature validiert die eigenen Blöcke values: und infra: der Feature-Anbindung. Das schema: der Component validiert die eigenen Blöcke der Component. Beide werden in der Phase der statischen Analyse unabhängig voneinander ausgewertet; eine Säule der Anbindung, die nicht zum schema: des Feature passt, hält den Build mit einem Fehler an, der auf die Stelle der Feature-Anbindung bezogen ist, nicht auf die Host-Component. Validiert wird die effektive Konfiguration der Anbindung — das Ergebnis der Komposition aller Geltungsbereiche, die sie konfiguriert haben —, sodass ein Wert, der in einem Geltungsbereich konform gemacht und dann in einem engeren mit etwas Unzulässigem überschrieben wird, erkannt wird.
Deklarierte Standardwerte werden in den gerenderten Säulen der Anbindung materialisiert. Über die Validierung hinaus wird ein default:, das auf einem values- oder infra-Feld eines Feature deklariert ist, beim Build für jeden Schlüssel, den niemand verfasst hat, in die gerenderte Säule dieser Anbindung eingefüllt — sodass ein FeatureRecipe-Template, das {{ .infra.tier }} liest, den im Schema deklarierten Wert statt eines leeren erhält. Vom Autor bereitgestellte Werte haben immer Vorrang, und ein Standardwert füllt nur die Schlüssel, die sie auslassen: Eine Anbindung, die einen Schlüssel des Feature-Schemas verfasst, erhält dennoch die deklarierten Standardwerte für die anderen Schlüssel dieses Schemas, und ein teilweise verfasstes verschachteltes Objekt behält, was geschrieben wurde, und erhält die Geschwister, die nicht geschrieben wurden.
Drei Eigenschaften des Einfüllens sind beim Verfassen wissenswert:
- Ein Standardwert verdrängt nie einen Wert, den irgendein Geltungsbereich bereitgestellt hat. Wo ein Feature in mehr als einem Geltungsbereich angebunden ist — etwa an einer Release-Grenze und an einer seiner Komponenten —, gilt der Wert des engeren Geltungsbereichs, und der Standardwert füllt nur, was überhaupt kein Geltungsbereich geschrieben hat.
- Ein Standardwert füllt eine Anbindung; er erzeugt nie eine. Standardwerte auf einem Feature zu deklarieren, das nichts anbindet, trägt nichts zur Ausgabe bei, sodass das Schema eines Feature keine Konfiguration hinzufügen kann, die kein Autor angefordert hat.
- Eine Anbindung, die an einer Release-Grenze statt an einer einzelnen Komponente deklariert ist, füllt nur
infra, weil diese Oberfläche keinenvalues:-Block zum Füllen trägt.
Da die Materialisierung dieselbe Schemaauflösung wie die Validierung verwendet, erreicht ein auf einem übergeordneten Feature deklarierter Standardwert die Anbindungen eines extends:-Kindes, und Standardwerte, die über eine dokumentübergreifende $ref: in eine SchemaLibrary erreicht werden, werden ebenfalls materialisiert. Standardwerte, die nur innerhalb einer lokalen dokumentinternen #/$defs/-Referenz oder unter einem allOf- / oneOf- / anyOf-Zweig deklariert sind, werden nicht materialisiert.
Eine Konsequenz verdient es, klar ausgesprochen zu werden, weil die Validierung allein sie nicht offenlegt: Ein required:-Feld, das auch ein default: trägt, wird durch diesen Standardwert erfüllt, sodass sein Weglassen zulässig ist — und der Wert, auf dessen Grundlage die Prüfung akzeptiert hat, ist der Wert, den die gerenderte Ausgabe trägt.
Der Template-Kontext des Compilers stellt dem gebundenen FeatureRecipe den Instanzzustand des Feature über das Feld .features.<alias> bereit (das pro Anbindung .type, .resolved_version, .labels, .values, .infra und .provides enthält). Templates innerhalb des FeatureRecipe lesen die eigenen values: des Feature über .values.<field> im eigenen Template-Geltungsbereich des FeatureRecipe; die values: der Host-Component sind für die Templates des FeatureRecipe nicht direkt sichtbar, es sei denn, das Feature deklariert explizit einen uses:-Socket zur Host-Component.
Diese Trennung der Geltungsbereiche macht Features komponierbar: Ein Feature autoscaler hängt nicht davon ab, an welche Component es angebunden wird; sein schema: beschreibt die Autoscaling-Absicht unabhängig vom Host. Die values: der Host-Component sind Sache des Hosts; die values: des Feature sind Sache des Feature; die beiden Säulen setzen sich zusammen, ohne Feldnamen über die Grenze hinweg durchsickern zu lassen.
Ziele von Annotation-Bindings
Ein Feature deklariert selbst keine Annotation-Bindings; die Map mappings.features.annotations des Manifest trägt sie. Ein Feature nimmt indirekt als Routing-Ziel an der Binding-Beziehung teil: Jedes Binding benennt über sein Feld feature: einen Feature-Typ, und die Listen maps.infra und maps.values des Bindings deklarieren gepunktete Pfade in die Eigenschaften spec.schema.infra.<path> und spec.schema.values.<path> des benannten Feature.
Beim Laden des Katalogs prüft der Compiler, dass jeder gepunktete Pfad in den maps-Listen eines Bindings einer Eigenschaft entspricht, die das spec.schema des Ziel-Feature in der benannten Säule tatsächlich deklariert. Ein Binding, das zu einem Pfad routet, den das Feature-Schema nicht deklariert, hält das Laden des Katalogs mit einem klaren OPS_ERROR an, der das Binding, das Ziel-Feature sowie die Säule und den Pfad nennt, über die es geroutet hat — das Binding ist im Manifest geschrieben, dem Dokument des Operators. Schema-Autoren wissen daher, dass jede Eigenschaft, die sie unter spec.schema.values.<path> oder spec.schema.infra.<path> deklarieren, als Binding-Ziel erreichbar ist; umgekehrt muss jede Eigenschaft, über die ein Manifest-Binding routet, im Schema des Ziel-Feature existieren.
Wenn eine Annotation auf Aggregate-Seite oder Release-Seite auf ein Binding passt, synthetisiert der Compiler eine Feature-Anbindung, deren Säulen-Payloads den Annotationswert in die benannten Pfade routen. Die synthetisierte Anbindung ist strukturell nicht von einer expliziten, vom Autor deklarierten Feature-Anbindung an derselben Stelle zu unterscheiden; das nachgelagerte Rendering, die Validierung und der Template-Kontext des FeatureRecipe verarbeiten beide Formen einheitlich. Zur Form des Bindings, zur Aufteilung nach Seite und Säule und zur Disziplin, nach der die explizite Anbindung Vorrang hat, siehe entities/manifest.md §„Annotationsgesteuerte Feature-Bindings“. Zur Kaskadenregel auf Aggregate-Seite und einem Authoring-Beispiel siehe providers/well-known-annotations.md §„Annotationskaskade auf Aggregate-Seite“.
Der Block assertions:
Feature.spec.assertions: ist eine optionale Map benannter Regeln, die architektonische Invarianten des Feature-Vertrags ausdrücken — feldübergreifende Regeln über die values: des Feature und den aufgelösten Zustand der angebundenen Component. Jeder Schlüssel ist ein Regelbezeichner, der in der Fehlermeldung erscheint; jeder Wert ist ein Go-Template-Rumpf. Der Compiler wertet sie nach der Schemavalidierung und vor dem Rendern des gebundenen FeatureRecipe aus, in der Reihenfolge, in der sie geschrieben sind, und die erste fehlschlagende Regel hält den Build mit der eigenen Fehlermeldung dieser Regel an.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Wie Component-Assertions drücken Feature-Assertions Invarianten auf Vertragsebene aus — Eigenschaften, die die Feature-Anbindung erfüllen muss, unabhängig davon, welches FeatureRecipe das Rendering implementiert. Für feldübergreifende Regeln, die von der konkreten Implementierung abhängen (eine Anforderung eines Wasm-Plugins, eine Eigenheit eines Charts), verwenden Sie stattdessen das Feld assertions: des FeatureRecipe. Zur vollständigen Authoring-Grammatik, zum Template-Kontext und zur Aufteilung der Verantwortung zwischen Feature- und FeatureRecipe-Assertions siehe templates/assertions-block.md.