Labels und Annotationen
Aggrega-Entitäten tragen zwei strukturell ähnliche Metadatenmechanismen — metadata.labels und metadata.annotations — sowie annotationstragende Felder, die über Boundary-kaskadierende Oberflächen und Oberflächen der Funktionsanbindung verstreut sind. Sechs unterschiedliche Oberflächen verfassen oder tragen Annotations-/Label-Inhalte, jede mit anderen Kaskadenregeln, anderen Konsumenten und anderen Präfixkonventionen. Diese Seite dokumentiert die Oberflächen an einer Stelle, definiert die drei semantischen Buckets, die der Template-Kontext zur Laufzeit bereitstellt, nennt die Präfixdisziplin, der Autoren folgen sollten, und dokumentiert die fünf Feature-Anbindungsoberflächen nebeneinander, damit sie neben dem umfassenderen Vokabular für Labels/Annotationen sichtbar sind.
Die sechs Annotations- und Label-tragenden Oberflächen
Autoren begegnen Labels und Annotationen auf sechs unterschiedlichen Oberflächen. Jede hat einen anderen Geltungsbereich, eine andere Kaskadenregel und einen anderen Konsumenten.
| # | Oberfläche | Geltungsbereich | Kaskadenregel | Primärer Konsument |
|---|---|---|---|---|
| 1 | metadata.labels der Katalogentität | Identität pro Entität (Component, Feature, Aggregate) | Kaskadiert nicht auf Instanzen; wird an der Katalogentität selbst getragen | aggrega search -l für Components und Features; die Labels eines Aggregate werden in seinem Dokument getragen, und kein Befehl liest sie |
| 2 | metadata.labels der Component (intrinsisch) | Eigenschaften pro Component-Instanz (component.aggrega.ai/type usw.) | Kaskadiert nach den label-transform-Mutationen in das .context.labels pro IR-Knoten | Selektorabgleich (selector:-Deklarationen in usesSchema, im synthetisierten JSON Schema als x-aggrega-selector: getragen), Template-Logik des Recipe |
| 3 | metadata.annotations der Component | Vom Architekten verfasste Merkmale pro Component-Instanz | Kaskadiert in den Bucket .context.annotations.catalog pro IR-Knoten | Verdict-Rollen der Governance (Richtlinien für intrinsische Merkmale), Template-Logik des Recipe |
| 4 | annotations: von Aggregate / Subsystem | Aggregate-seitige kognitive Metadaten | Kaskadiert in den Bucket .context.annotations.aggregate pro IR-Knoten | valuesMapping: des Recipe für kognitives Routing |
| 5 | Release-Boundary annotations: | Ops-seitige physische Metadaten, einschließlich der bekannten aggrega.ai/*-Annotationen | Kaskadiert in den Bucket .context.annotations.release pro IR-Knoten | Providers (helm liest aggrega.ai/namespace; compose leitet den Netzwerknamen aus demselben Schlüssel ab); injectMapping: des FeatureRecipe für Boundary-übergreifendes Routing |
| 6 | features.annotations-Bindungen des Manifest | Bindung Annotationsschlüssel → Feature-Typ mit nach Säulen gruppiertem Routing der Unterschlüssel (maps.infra / maps.values) für die annotationsgesteuerte Feature-Anbindung | Die Teilphase der Auflösung für die Annotationsexpansion durchläuft Release-Boundaries (von außen nach innen) und Aggregate-Subsysteme (von außen nach innen); Überschreibung pro Komponente und Null-Opt-out für den ganzen Wert / pro Unterschlüssel gelten; die Durchsetzung von Seite gegenüber Säule steuert, welche Säule pro Authoring-Seite greift | Annotationsgesteuerte Feature-Expansion (synthetische Feature-Anbindungen, im IR-Graphen mit origin: annotation erfasst) |
Die Oberflächen 4 und 5 teilen eine YAML-Form (eine annotations:-Map an der kaskadierenden Boundary), kaskadieren aber in unterschiedliche IR-Buckets — die Unterscheidung der Buckets ist die tragende Regel, die die Laufzeit bereitstellt. Oberfläche 6 ist strukturell getrennt: Sie liegt auf der Manifest-Entität statt auf Aggregate- / Release-Inhalten, und ihre Nutzung hängt vom annotationsgesteuerten Expansionsdurchlauf ab.
Die Drei-Bucket-Semantik von .context.annotations.*
Wenn der Renderer ein Template eines Recipe auswertet, trägt das knotenbezogene Feld .context.annotations drei benannte Buckets. Jeder Bucket ist eine flache Map vom Typ string → string, deren Schlüssel Annotationsnamen sind; der Bucket bestimmt, wer die Annotation verfasst hat und welche Absicht sie verfolgt.
.context.annotations.release— Annotationen der Release-Boundary (Oberfläche 5). Sie dienen dazu, physische Gegebenheiten zu steuern; Renderer leiten sie, wo angebracht, in die Felderinfra:weiter. Die bekannten Annotationenaggrega.ai/*liegen in diesem Bucket..context.annotations.catalog— Annotationen aus den Metadaten der Component (Oberfläche 3). Unveränderliche intrinsische Merkmale, die der Architekt verfasst; vor allem von Wasm-Policy-Plugins konsumiert..context.annotations.aggregate— Annotationen der Subsysteme des Aggregate (Oberfläche 4). Kognitive Metadaten; Renderer leiten sie, wo angebracht, in die Payloadsvalues:weiter.
Die Drei-Bucket-Trennung ist ein Gesellschaftsvertrag
Der Compiler erzwingt die Grenzen zwischen den Buckets nicht. Die drei Buckets teilen eine flache Form string → string; das Template eines Recipe kann alle drei lesen, und nichts verhindert, dass eine Annotation einer Release-Boundary als kognitives Metadatenfeld interpretiert oder eine Katalog-Annotation in infra: geleitet wird. Die Trennung ist Authoring-Disziplin, keine Garantie des Compilers.
Das Ziel der Disziplin — was die Buckets ausdrücken sollen:
- release = „wo diese Komponente läuft, gesteuert von Ops“
- catalog = „was diese Komponente ist, verfasst vom Architekten“
- aggregate = „was diese Komponente tut, verfasst vom Entwickler“
Wenn Autoren die Trennung einhalten, können nachgelagerte Werkzeuge den richtigen Bucket für das richtige Anliegen lesen. Wenn Autoren sie verletzen (z. B. indem sie kognitive Metadaten in die Annotationen release legen, weil die Release-Datei bequem ist), funktioniert die Laufzeit weiterhin, aber die Absicht des Buckets verschwimmt.
Linter-Socket — Markieren Bucket-übergreifender Lesezugriffe
Ein Linter-Plugin (Out-of-Band-Meldung; siehe plugins/plugin-contract.md für das Platzierungskriterium) kann Bucket-übergreifende Lesezugriffe markieren, bei denen das Template eines Recipe aus einem Bucket liest, dessen Absicht nicht zu dem weitergeleiteten Feld passt. Das Kriterium:
.context.annotations.releaselesen, um ein Feldvalues:zu befüllen — markieren (kognitive Metadaten sollten aus dem Bucketaggregatestammen)..context.annotations.aggregatelesen, um ein Feldinfra:zu befüllen — markieren (physische Metadaten sollten aus dem Bucketreleasestammen)..context.annotations.cataloglesen, umvalues:oderinfra:zu befüllen — in der Regel nur eine Meldung (Katalog-Annotationen sind intrinsische Merkmale; sie in Säulen weiterzuleiten ist ungewöhnlich, aber nicht immer falsch).
Der Veröffentlichungs-Linter enthält keine Regel für dieses Kriterium, und der Build prüft es nicht; ein eigenes Linter-Plugin kann es, über den Linter-Socket, den aggrega lint ausführt. Die Disziplin wird von Reviewern und Autoren getragen, die der Konvention zur Bucket-Absicht folgen.
Präfixdisziplin
Annotations- und Label-Schlüssel folgen einer einheitlichen Form <namespace>/<name>. Die folgenden Präfixfamilien geben an, wer Schlüssel unter jeder von ihnen verfasst und wie jede aufrechterhalten wird — ein Präfix ist reserviert, und ein Build hält an, wo eine Manifest-Bindung oder ein Ausgabe-Label eines Recipe einen neuen Schlüssel darin beansprucht; die übrigen sind Katalogkonvention, und nichts weist dort einen Schlüssel zurück. Der Unterschied zwischen beiden ist, ob ein Build anhält; lesen Sie daher die mittlere Spalte vor den anderen.
| Präfix | Wer hier Schlüssel verfasst | Wie es aufrechterhalten wird | Zweck | Beispiele |
|---|---|---|---|---|
aggrega.ai/ | Nur die Aggrega-Plattform | Reserviert und durchgesetzt. Die Plattform definiert die Schlüssel hier, und Sie schreiben diejenigen, die sie definiert — etwa aggrega.ai/namespace an einer Release-Boundary. Einen neuen Schlüssel innerhalb des Präfixes zu beanspruchen führt zum Anhalten: eine Manifest-Bindung features.annotations unter dem bloßen Präfix ebenso wie ein Ausgabe-Label-Schlüssel eines Recipe darunter in outputLabels: oder outputComponentLabels:. Eine darunter geschriebene Annotation, die die Plattform nicht definiert, wird nicht zurückgewiesen: Der Build trägt sie mit, und wo sie an einem Release steht, meldet ein Ziel, das nicht auf sie reagiert, dies mit einer Warnung. Siehe errors/fatal-halts.md „A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Eine Annotationsbindung eines Manifest beansprucht das reservierte Präfix)“ und „An output-label key uses a reserved namespace (Ein Ausgabe-Label-Schlüssel verwendet einen reservierten Namespace)“. | Plattformnative Annotationen, die direkt vom Provider konsumiert werden | aggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment |
feature.aggrega.ai/ | Offizielle Standardbibliothek | Konvention. Nichts weist hier einen Schlüssel zurück; das Vokabular gehört der Standardbibliothek durch Übereinkunft statt durch eine Prüfung. | Feature-Annotations-Kurzformen, gebunden in features.annotations des Manifest | feature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking |
component.aggrega.ai/ | Offizielle Standardbibliothek | Konvention. Nichts weist hier einen Schlüssel zurück. | Labels für Component-intrinsische Merkmale (hier liegt der Selektorschlüssel component.aggrega.ai/type) | component.aggrega.ai/type |
aggregate.aggrega.ai/ | Offizielle Standardbibliothek | Konvention. Nichts weist hier einen Schlüssel zurück. | Identitäts-Labels eines Aggregate auf Modulebene | aggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance |
<role>.aggrega.ai/ | Offizielle Standardbibliothek sowie Unternehmen in ihren eigenen Katalogen | Konvention. Nichts weist hier einen Schlüssel zurück. | Fähigkeits-Labels — die Verhaltensdimensionen, nach denen ein Selektor usesSchema oder das appliesTo eines Feature unterscheidet. Der Teil <role> benennt das Anliegen, zu dem die Dimension gehört: entweder eine Komponentenrolle oder ein übergreifendes Anliegen, das mehrere Rollen teilen. | model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring |
<any-other-domain>/ | Unternehmen / Community | Offen. Verfassen Sie unter einer Domain, die Sie kontrollieren. | Benutzerdefinierte Annotationen und Labels | acme.com/billing-tier, corp/cost-center |
Autoren, die benutzerdefinierte Annotationen schreiben, verwenden eine Domain, die sie kontrollieren (typischerweise im Reverse-DNS-Stil). Das Verfassen direkt unter aggrega.ai/ (ohne Unterpräfix) ist der Plattform vorbehalten; auch die Bindungen features.annotations des Manifest können keine Schlüssel direkt unter aggrega.ai/ binden — siehe entities/manifest.md „aggrega.ai/ Prefix Reservation (Reservierung des Präfixes aggrega.ai/)“.
Benennung eines Fähigkeitspräfixes
Ein Fähigkeitsschlüssel ist <role>.aggrega.ai/<dimension>, und der Teil <role> ist derjenige, der Urteilsvermögen erfordert. Drei Regeln bestimmen ihn, und die erste wird am häufigsten falsch herum angewendet.
- Benennen Sie das Anliegen, nicht die Art von Komponente, die es zufällig zuerst trägt. Wo eine Dimension etwas beschreibt, das mehrere Komponentenarten teilen, benennt das Präfix das gemeinsame Anliegen, damit die nächste Art, die es erhält, das Vokabular wiederverwendet, statt ein paralleles zu erfinden.
component.aggrega.ai/hostingist ein Anliegen — wer die zugrunde liegende Ressource betreibt — und beschreibt eine Datenbank und eine Modell-API mit denselben Worten;dataplane.aggrega.ai/*benennt eine Position auf dem Verkehrspfad, sodass sich ein Proxy, ein Ingress-Gateway und ein Service Mesh gleich beschreiben. Eine Dimension, die wirklich spezifisch für eine Rolle ist, erhält den Namen dieser Rolle, wie esmodel.aggrega.ai/capabilitytut. - Ein einziges Wort in Kleinbuchstaben, ohne Bindestrich, im Präfix. Der Bindestrich gehört in die Hälfte
<dimension>, wo sich ein zusammengesetzter Begriff natürlich liest (request-mirroring,data-class,upstream-licensing). - Eine Dimension wird hinzugefügt, wenn ein Selektor sie braucht, und jeder Wert, den sie deklariert, hat eine Komponente, die ihn trägt. Jedes Wort hier muss ein Katalogautor lernen und kann einem Feature-Autor begegnen, daher verdient sich eine Dimension ihren Platz, indem sie etwas unterscheidet, wonach ein
usesSchemaoder einappliesTotatsächlich fragt. Ein Wert, den keine Komponente trägt, ist schlechter als ein fehlender: Ein Selektor, der ihn nennt, wird geparst, passt auf nichts und meldet nichts — daher bleibt ein Wert, den der Katalog nicht vorführen kann, aus dem Vokabular heraus, bis eine Komponente ihn trägt. Ein Schlüssel, dessen Wert die Aussage einer Organisation darüber ist, wie sie ihre eigenen Komponenten verwendet, statt einer Eigenschaft des Produkts, ist die Ausnahme, undcompliance.aggrega.ai/data-classist dieser Fall: Welche Klasse die Daten einer Komponente haben, hängt davon ab, wie eine Organisation die Komponente verwendet, daher trägt keine Component der Standardbibliothek einen seiner Werte, und kein Socket und kein Feature der Standardbibliothek selektiert danach. Der Schlüssel und seine Werte sind deklariert, damit die eigenen Components einer Organisation und die Policies, die sie anbindet, eine einzige Schreibweise teilen; ein Selektor oder eine Policy, die einen Wert nennt, passt nur in einem Katalog, dessen Components ihn tragen. policy-data-class-route zeigt eine solche Component und die Policy, die sie liest.
Eine Reservierung und ein plattformdefinierter Schlüssel sind nicht dasselbe
Die Reservierung gilt für die bloße Wurzel aggrega.ai/. Jeder Namespace <scope>.aggrega.ai/ darunter ist ein eigener Schlüsselraum, der nicht der Plattform gehört, und genau das hält das Vokabular des Katalogs erweiterbar: Ein Unternehmenskatalog kann acme.aggrega.ai/team verfassen, ohne etwas streitig zu machen, das der Build stempelt.
Einige Schlüssel in diesen offenen Namespaces sind dennoch von der Plattform definiert und vom Build gelesen, und das macht ihren Namespace nicht reserviert:
component.aggrega.ai/typeist in denmetadata.labelsjeder Component erforderlich und nimmt einen Wert aus einer festen Menge an. Selektoren gleichen darauf ab; der Compiler verzweigt nicht danach, welchen Wert er enthält.features.aggrega.ai/requiredType.<label>, in denmetadata.annotationseiner Component verfasst, deklariert, dass ein Feature des genannten Typs angebunden sein muss. Der Build prüft diese Vorgabe gegen die fertige Anbindungsmenge jedes Knotens und hält an, wo nichts sie erfüllt — sieheerrors/fatal-halts.md„Required feature not attached (Erforderliches Feature nicht angebunden)“. Beachten Sie den Plural:features.aggrega.ai/ist ein eigener Namespace, verschieden vom Singularfeature.aggrega.ai/in der Tabelle oben, der die Kurzformen für Manifest-Bindungen trägt.
Lesen Sie den Unterschied so: Ein reserviertes Präfix weist einen Schlüssel zurück, den Sie darin zu definieren versuchen, während ein plattformdefinierter Schlüssel ein einzelner benannter Schlüssel ist, den der Build kennt und der in einem Namespace liegt, in dem Sie ansonsten frei verfassen dürfen. Jeder andere Schlüssel unter component.aggrega.ai/, features.aggrega.ai/ und den übrigen sind Metadaten, die der Build mitträgt, ohne sie zu interpretieren.
Ein solcher Schlüssel in den metadata.annotations einer Component wird vom Standard-Veröffentlichungs-Linter statt vom Build gelesen: observability.aggrega.ai/metrics-credential gibt an, wie sich die Metriken des Produkts authentifizieren — none, sie werden ohne Anmeldedaten bereitgestellt; target-key, sie verlangen den Schlüssel, den die Component von jedem Aufrufer verlangt; separate-token, sie verlangen ein eigenes Token. Der Build trägt ihn mit wie jede andere Annotation. Der Linter liest ihn, um zu entscheiden, ob die Anmeldedaten einer Scrape-Verbindung mit dem Aufruferschlüssel des Ziels verglichen werden, und verlangt, dass er mit dem provides-Schlüssel metrics_credential_required übereinstimmt, den die Component deklariert — siehe „The discipline rules (Die Disziplinregeln)“ in cli/aggrega-lint.md.
Provenienz-Labels in der gerenderten Ausgabe
Über die eingehenden Annotationen hinaus, die die Provider konsumieren, emittiert Aggrega außerdem Provenienz-Labels auf jede Kubernetes-Manifestdatei, die der helm-Provider rendert, und auf jeden ausgegebenen compose-Dienst, und der helm-chart-Provider schreibt dieselbe Menge, so wie der helm-Provider sie schreibt, auf jedes Artefakt, das er mit $import: lädt. Die Label-Menge erlaubt nachgelagerten Werkzeugen (Kosten-Dashboards, Observability-Stacks, GitOps-Controller), Laufzeitressourcen auf den Kataloginhalt zurückzuführen, der sie erzeugt hat. Die eigenen Templates eines helm-chart-Sub-Charts werden so kopiert, wie ihr Autor sie geschrieben hat, und tragen daher die Labels, die dieser Autor geschrieben hat.
Die Menge, die die Provider helm und compose ausgeben — bei helm werden drei der Schlüssel als Annotationen statt als Labels geschrieben, wie die Tabelle angibt:
| Label | Quelle | Immer ausgegeben? |
|---|---|---|
app.kubernetes.io/name | Component-Identität — der Name, den Sie geschrieben haben, oder für eine Komponente, die ein importiertes Aggregate beisteuert, ihr qualifizierter Name mit ausgeschriebenem Modultrennzeichen (siehe unten); oder, für eine Ressource, die ein FeatureRecipe ausgibt, der für diese Anbindung abgeleitete Bezeichner | Ja bei Kubernetes-Manifestdateien; bei compose-Diensten nicht ausgegeben (das Standard-Label ist K8s-spezifisch) |
aggrega.ai/component-id | Component-Identität — der Name, den Sie geschrieben haben, oder für eine Komponente, die ein importiertes Aggregate beisteuert, ihr qualifizierter Name mit ausgeschriebenem Modultrennzeichen (siehe unten); oder, für eine Ressource, die ein FeatureRecipe ausgibt, der für diese Anbindung abgeleitete Bezeichner | Ja |
aggrega.ai/recipe-uri | <recipe-name>:<recipe-version> des erzeugenden Recipe (oder des erzeugenden FeatureRecipe bei von einem FR ausgegebenen Ressourcen) | Wenn für die erzeugende Entität sowohl Name als auch Version gesetzt sind; bei helm eine Annotation |
aggrega.ai/boundary-path | Boundary-Pfad, in den die Komponente geleitet wurde | Wenn der Boundary-Pfad nicht leer ist; bei helm eine Annotation |
aggrega.ai/aggregate-name | metadata.name des Aggregate | Wenn gesetzt |
aggrega.ai/compiler-version | Zur Build-Zeit eingestempelte Compiler-Version | Wenn gesetzt |
aggrega.ai/provider | Der Provider, der die Ressource gerendert hat (helm, helm-chart, compose) | Ja |
aggrega.ai/provider-version | Die Version von diesem Provider | Ja |
aggrega.ai/environment | metadata.environment des Release | Ja — jedes Release deklariert es |
aggrega.ai/sync-wave | Ganzzahl syncWave pro Boundary, die Reihenfolge, in der ein GitOps-Werkzeug Ressourcen anwendet | Wenn ungleich null; bei helm eine Annotation, neben argocd.argoproj.io/sync-wave |
Der Name des Aggregats, die Umgebung, die Compiler-Version sowie Name und Version des Providers sind Zeichenketten, die Sie oder der Build gewählt haben, und keine davon unterliegt an der Stelle, an der sie geschrieben wird, den Kubernetes-Regeln für Label-Werte. Auf helm trägt jedes dieser Labels den Wert wie geschrieben, wenn er bereits ein gültiger Label-Wert ist — Buchstaben, Ziffern, -, _ und ., ein Buchstabe oder eine Ziffer an beiden Enden, höchstens 63 Zeichen —, und andernfalls den in einen gültigen Wert umgeschriebenen Wert, wobei der unveränderte Wert als Annotation unter demselben Schlüssel hinzugefügt wird: Ein Aggregate namens imported/flow erhält das Label aggrega.ai/aggregate-name: imported-flow und die Annotation aggrega.ai/aggregate-name: imported/flow. Ein Wert, der bereits passt, fügt keine Annotation hinzu. Compose trägt den unveränderten Wert als Label. Die Umschreibregel ist unter providers/well-known-annotations.md „Von Providern ausgegebene Provenienz-Labels“ beschrieben.
Für Ressourcen, die ein FeatureRecipe ausgibt, wird der Wert aggrega.ai/component-id aus der Anbindung statt aus dem Namen der Host-Komponente gebildet — für jede Art, auf die ein FeatureRecipe diese Ressourcen liefern kann, ob es eine Arbeitslast synthetisiert, eine eigenständige Artefaktmenge ausgibt oder ein Chart oder ein Fragment rendert, das sein Autor bereitgestellt hat. So liefert eine Abfrage, die die Ressourcen einer Anbindung nach Identität auswählt, alle davon, und keine davon ist von einer Ressource ununterscheidbar, die die Host-Komponente selbst ausgegeben hat. Wie der Wert gebildet wird, hängt davon ab, wo das Feature angebunden ist; in beiden Fällen ist das Ergebnis ein gültiger Kubernetes-Label-String.
Für eine Komponente, die ein importiertes Aggregate beisteuert, ist die Identität der qualifizierte Name dieser Komponente, wobei das Trennzeichen, das das Modul mit der Komponente verbindet, ausgeschrieben wird — data-layer.main-db wird als data-layer-zdmain-db gestempelt —, weil ein Punkt kein Zeichen ist, das ein Ressourcenname oder eine Cluster-Adresse sicher tragen kann. Ein von Ihnen geschriebener Name ohne Trennzeichen wird Byte für Byte gestempelt.
Die Identität sagt, wozu eine Ressource gehört. Das ist eine andere Frage als die, wie eine Ressource heißt, und für eine Art der Lieferung haben die beiden unterschiedliche Antworten:
- Wo ein FeatureRecipe eine Arbeitslast synthetisiert, baut Aggrega diese Ressourcen selbst und benennt sie daher ebenfalls nach der Identität: Die Identität erreicht ihren
metadata.name, ihre Selektor-Labels und ihre ausgegebenen Dateinamen ebenso wie ihre Labels. Sie ist ein Name innerhalb des Clusters und nicht nur ein Label. - Wo ein FeatureRecipe ein Chart oder ein Fragment, das sein Autor geschrieben hat, liefert, gehören die Namen demjenigen, der es geschrieben hat. Der Helm-Releasename, gegen den diese Templates gerendert werden — und das Präfix der Dateien, die dieses Rendering ausgibt — bleiben die der Host-Komponente. Charts benennen ihre Ressourcen routinemäßig nach dem Releasenamen, sodass eine Änderung daran Ressourcen umbenennen würde, die das Chart selbst deklariert, in einem Cluster, in dem sie bereits bereitgestellt sind, aus einem Grund, der nichts mit dem Chart zu tun hat. Die Labels tragen weiterhin die eigene Identität der Anbindung, und das hält die Ressourcen der Anbindung auffindbar.
- Wo das Feature an eine Boundary angebunden ist, gibt es keine Host-Komponente, deren Name einspringen könnte, daher ist die zusammengesetzte Identität dort die Grundlage der Benennung ebenso wie das Label.
In beiden Fällen wird der Wert aus den Teilen, die Sie geschrieben haben, zusammengesetzt, verbunden durch --, hinter einem festen Anfang, der angibt, welcher der beiden Fälle es ist. Zwei Anfänge sind in Gebrauch, und eine Komponentenidentität, die Sie schreiben, darf mit keinem davon beginnen — genau das verhindert, dass ein von Ihnen geschriebener Name und ein von Aggrega zusammengesetzter Name je miteinander verwechselt werden.
Wo das Feature an eine Komponente angebunden ist, sind die Teile ein fester Anfang cfr, die Identität der Komponente, an die das Feature angebunden ist, und der Schlüssel, unter dem es angebunden ist. Ein Feature, das an die Komponente api unter mon angebunden ist, ergibt cfr--api--mon. Die Host-Komponente ist Teil des Werts, weil ein einziger Feature-Name, der an mehrere Komponenten angebunden ist, auf jeder eine eigene Menge von Ressourcen ausgibt und jede Menge eine eigene Identität braucht: mon sowohl an api als auch an worker anzubinden ergibt cfr--api--mon und cfr--worker--mon statt eines Werts für beide. Eine Anbindung, die genau wie die Komponente heißt, die sie beherbergt, ergibt aus demselben Grund einen Wert, der sich vom eigenen Wert dieser Komponente unterscheidet — mon an mon angebunden ergibt cfr--mon--mon.
Wo das Feature an eine Boundary angebunden ist — der Gateway-Dienst compose-bridge ist das kanonische Beispiel —, sind die Teile ein fester Anfang bfr, dann jedes Segment des Pfads der Boundary, das äußerste zuerst, dann der Name, unter dem das Feature angebunden ist. Ein Feature namens gateway an einer Boundary bei bridge ergibt bfr--bridge--gateway; dasselbe Feature an einer Boundary bei prod/eu ergibt bfr--prod--eu--gateway.
Ein Zeichen, das der Wert nicht tragen kann, wird ausgeschrieben statt ersetzt, und weil der Wert ein Name innerhalb des Clusters und zugleich ein Label ist, ist er auf die Zeichen beschränkt, die jede Art von Kubernetes-Ressourcenname zulässt: Kleinbuchstaben, Ziffern und den Bindestrich. Ein von Ihnen geschriebener Bindestrich bleibt also ein Bindestrich, ein Kleinbuchstabe oder eine Ziffer bleibt, wie er ist, und alles andere — einschließlich eines Großbuchstabens, den ein Label-Wert zulässt und ein Ressourcenname zurückweist — wird zu einem kurzen Escape: Eine Anbindung namens my_zone steuert my-zuzone bei, und eine Komponente myApi mit einer Anbindung worker ergibt cfr--my-zx000041pi--worker. Dieser maskierte Wert ist derjenige, nach dem die Ressourcen der Anbindung auf jedem Ziel gelabelt und ausgewählt werden, derjenige, nach dem eine von der Anbindung synthetisierte Arbeitslast und ihre Dateien benannt werden, und derjenige, aus dem der Releasename einer Boundary-Anbindung abgeleitet wird. Ein Großbuchstabe ist das einzige Zeichen, das die Regel für Ressourcennamen zu dem hinzufügt, was ein Label allein ausgeschrieben hätte, daher ist ein zusammengesetzter Wert, dessen Teile keinen enthalten — cfr--api--mon, bfr--prod--eu--gateway —, genau der Wert, den ein Label allein tragen würde. Zwei Anbindungen, die Sie unterscheiden können, ergeben daher zwei Werte — wie auch immer Sie sie benannt haben und wie tief die Boundary auch liegt —, weil -- eine Folge ist, die kein geschriebener Teil enthalten kann, sodass das Verschieben der Trennung zwischen den Teilen den Wert ändert, statt mit ihm zu kollidieren.
Wie lang ein zusammengesetzter Wert sein darf, ist die Antwort des Ziels und keine Zahl, die Aggrega festhält: Das Ziel, für das die Ressourcen gerendert werden, wird gefragt, und der Wert wird gekürzt, bis dieses Ziel ihn akzeptiert. Ein Kubernetes-Label-Wert umfasst höchstens 63 Zeichen, und ein aus derselben Identität abgeleiteter Helm-Releasename ist noch enger begrenzt, sodass dieselbe Anbindung unter einem Ziel kürzer ausfallen kann als unter einem anderen. Ein Wert, der passt, wird genau so ausgegeben, wie er zusammengesetzt wurde; das ist der gewöhnliche Fall und der Fall für jede Anbindung im Katalog der Standardbibliothek. Einer, der nicht passt, wird gekürzt: Jeder Teil behält seinen Anfang, und ein zehnstelliger Digest der gesamten Identität wird hinter einer Markierung angehängt, die kein Name, den Sie schreiben können, erzeugt — so ist ein gekürzter Wert als solcher erkennbar und kann nie als ein Wert gelesen werden, der gepasst hat. Eine tief verschachtelte Anbindung gateway kann daher als bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e gerendert werden. Dass zwei gekürzte Werte zusammentreffen, ist sehr unwahrscheinlich, und falls doch, hält ein Build an, statt zwei davon einen Namen teilen zu lassen.
Siehe errors/fatal-halts.md „The same name is derived more than once inside the output (Derselbe Name wird innerhalb der Ausgabe mehr als einmal abgeleitet)“ dazu, welche Paare zum Anhalten führen und wie man sie trennt.
Der Wert aggrega.ai/recipe-uri einer von einem FR ausgegebenen Ressource ergibt sich aus dem eigenen name:version des FeatureRecipe, nicht aus der Identität des konsumierenden Recipe — so erhalten nachgelagerte Werkzeuge, die recipe-uri lesen, um die erzeugende Entität zu identifizieren, die korrekte Provenienz sowohl für von Komponenten ausgegebene als auch für von FRs ausgegebene Ausgabe.
Für Provider-spezifische Einzelheiten der Ausgabe (wo auf der gerenderten Ausgabe die Labels landen und wie jeder Provider sie serialisiert) siehe providers/well-known-annotations.md „Provenance labels emitted by providers (Von Providern ausgegebene Provenienz-Labels)“.
Vom Recipe deklarierte Ausgabe-Labels
Neben der vom Compiler verwalteten Provenienzmenge kann der Autor eines Recipe eigene Labels deklarieren, die auf die gerenderte Ausgabe des Recipe gestempelt werden, über Recipe.spec.outputLabels:. Diese laufen über dieselbe Ausgabeschiene wie die Provenienz-Labels — sie werden in dieselbe Label-Menge zusammengeführt und landen überall dort, wo die Provenienz landet —, gehören aber dem Autor statt dem Compiler. Der vorgesehene Einsatz ist ein Realisierungsmerkmal: eine Eigenschaft dessen, wie ein bestimmtes Recipe eine Komponente realisiert (zum Beispiel hosting: managed gegenüber hosting: self-hosted für ein Recipe mit verwaltetem Dienst gegenüber einem Recipe mit selbst gehostetem Chart desselben Komponententyps), die auf der Ausgabe sichtbar gemacht wird, damit Kosten-, Policy- und Inventarwerkzeuge sie abfragen können.
Die Namespaces aggrega.ai/ und app.kubernetes.io/ sind der Provenienzmenge vorbehalten; ein Schlüssel unter einem der beiden Präfixe wird beim Laden zurückgewiesen — in outputLabels: und in outputComponentLabels:, dem Begleitblock, der einen Label-Schlüssel der Komponente benennt und den Wert stempelt, den die Komponente selbst deklariert. Eine validierte Ausgabe-Label-Menge ist daher immer disjunkt zu den Provenienzschlüsseln, sodass die beiden auf der zusammengeführten Ausgabe nie kollidieren. Maßgeblich ist die bloße Wurzel: Ein Schlüssel mit eigenem Bereich wie component.aggrega.ai/hosting liegt in einem eigenen Namespace und darf wörtlich geschrieben oder hochgestuft werden. Die Darstellung pro Provider (helm-Objekt und Pod-Template bei der Synthese; Objekt beim Quell-Rendering und bei Artefakten; Labels der compose-Dienste; terraform-Tags pro Ressource auf Artefaktinhalten .tf.json) entspricht der Platzierung der Provenienz und ist auf der Recipe-Entitätsseite unter „The outputLabels: field (Das Feld outputLabels:)“ und „The outputComponentLabels: field (Das Feld outputComponentLabels:)“ vollständig dokumentiert.
Feature-Anbindung — fünf Oberflächen
Features werden über fünf verschiedene Authoring-Oberflächen an Components angebunden, jede mit eigenem Geltungsbereich, eigenem vorgesehenem Nutzer und eigenem Ordnungsvorrang innerhalb des 5-Ebenen-Zwiebelmodells. Die vollständige Anbindungsreihenfolge und das Zwiebelmodell selbst sind in architecture/10-compilation-pipeline.md dokumentiert; die folgende Tabelle stellt die fünf Oberflächen nebeneinander dar.
| Stufe | Oberfläche | Verfasst von | Geltungsbereich | Kaskadenregel |
|---|---|---|---|---|
| 1 | Block features: einer Komponente im Aggregate | Entwickler | Pro Komponenteninstanz (granular) | Keine — direkt durch den Autor |
| 2 | Block features: eines Subsystems im Aggregate | Entwickler | Subsystem-Geltungsbereich (übergreifend innerhalb des Aggregate) | Kaskadiert auf jede Komponente im Subsystem |
| 3 | components.<id>.features der Release-Boundary | Ops | Pro Komponenteninstanz (granular, Ops-Seite) | Keine — direkt durch den Autor |
| 4 | Block features: der Release-Boundary | Ops | Boundary-Geltungsbereich (übergreifend innerhalb der Boundary) | Kaskadiert auf jede Komponente in der Boundary |
| 5 | Expansion von features.annotations des Manifest | Plattformbetreiber | Annotationsgesteuert (synthetische Anbindung) | Kaskadiert durch den Boundary-Baum (Release-Seite) oder den Subsystem-Baum (Aggregate-Seite); es gelten das Überschreiben pro Komponente und das Opt-out pro Unterschlüssel per null |
Die fünf Oberflächen akkumulieren sich; eine Anbindung, die auf einer beliebigen Oberfläche vorhanden ist, trägt zur aufgelösten Funktionsmenge der Component bei. Wenn derselbe Instanzname eines Feature auf mehr als einer Oberfläche erscheint, werden die Beiträge zu einer Anbindung zusammengeführt, statt einander zu ersetzen, und eine Typabweichung zwischen ihnen hält den Build mit einem Fehler feature-merge-conflict an.
Die fünf Oberflächen sind gemäß der Trennung der Zuständigkeiten in der Architektur beabsichtigt — Entwickler (Ebenen 1-2), Ops (Ebenen 3-4), Plattformbetreiber (Ebene 5) — und nicht redundant. Autoren wählen die Oberfläche, die dazu passt, wem die Anbindung gehört und in welchem Geltungsbereich.
Welche Labels entscheiden, ob ein Feature anwendbar ist
Ein Feature deklariert mit spec.appliesTo und spec.appliesToAnyOf, wo es angebunden werden darf, und der Build beurteilt diese Deklaration anhand der finalisierten Labels des Knotens, an dem die Anbindung landet. Ein Feature an einen Knoten anzubinden, den diese Labels nicht erfüllen, hält den Build an; ein Feature, das keine der beiden Oberflächen deklariert, stellt keine Anforderung und ist überall anwendbar.
Die finalisierte Label-Menge wird in zwei Schritten zusammengesetzt, und keiner davon ist der, den Autoren am häufigsten annehmen.
- Ein Knoten erhält seine Labels von der Katalogentität Component, die sein
type:nennt. Sie sind eine Eigenschaft des Typs der Komponente, nicht der Instanz: Das Aggregate kann keine Komponenteninstanz labeln, und das Release ebenso wenig. Die eigenenmetadata.labelseines Aggregate beschreiben das Aggregate als wiederverwendbares Modul und kaskadieren nicht auf die Komponenten darin. Zwei Instanzen eines Typs tragen also identische Labels, und zu ändern, welche Labels ein Knoten hat, heißt, den Typ zu ändern, auf den er verweist — oder die Entität dieses Typs zu ändern. - Eine Anbindung
label-transformkann sie anschließend umschreiben. Wo die Workspace-Konfiguration ein Governance-Plugin in der Rollelabel-transformanbindet, läuft es bei der Topologiekonstruktion und kann Knoten-Labels hinzufügen, ändern oder entfernen, bevor irgendetwas an ihnen gemessen wird. Es darf nichts anderes berühren, daher sind Labels der einzige Teil eines Knotens, den es verschieben kann — und genau der Teil, an dem die Anwendbarkeit hängt.
Ein Vorschlag, der anhand der Labels gemacht wird, die ein einzelnes Dokument deklariert, ist daher eine Annäherung, keine Vorhersage. Die metadata.labels einer Component-Entität zu lesen sagt Ihnen, womit ein Knoten dieses Typs beginnt; das ist oft genug die richtige Antwort, um nützlich zu sein, und auf zwei bestimmte Arten falsch: Ein Dokument, das lediglich den Namen eines Knotens teilt, ist ein anderer Gegenstand mit anderen Labels, und eine Anbindung label-transform kann die Menge unter jedem beliebigen Dokument verschieben. Werkzeuge, die Anbindungsvorschläge allein aus dem Quelltext anbieten, arbeiten mit dieser Annäherung; das Urteil, das ein Build fällt, betrifft die finalisierte Menge.
Vorrang von Attachments
Wenn zwei Beiträge dasselbe Feld derselben Anbindung liefern, entscheiden vier Regeln, welchen die gerenderte Ausgabe trägt. Sie werden in dieser Reihenfolge angewendet, und die Reihenfolge macht das Ergebnis vorhersagbar:
- Herkunft. Ein explizit verfasster Beitrag schlägt einen annotationsgesteuerten, gleich in welchem Geltungsbereich einer von beiden deklariert wurde. Ein Feld in einem Block
features:niederzuschreiben ist die Art, wie ein Autor überschreibt, was eine Annotation beigetragen hätte, und eine Annotation verdrängt nie stillschweigend etwas von Hand Geschriebenes. Der Compiler zeichnet die unterdrückte Annotation neben dem gewinnenden Wert auf und meldet sie als Hinweis, sodass die Überschreibung sichtbar statt rätselhaft ist. - Säulenzuständigkeit. Jede Domäne füllt ihre eigene Säule: Die Oberflächen des Aggregate tragen
valuesbei, die Oberflächen des Release trageninfrabei. Weil die beiden Seiten nie dieselbe Säule schreiben, können ein Entwicklerbeitrag und ein Betreiberbeitrag nicht um dasselbe Feld konkurrieren — es gibt keine Vorrangfrage zwischen Entwickler und Betreiber zu beantworten. - Kompositionsautorität. Eine Deklaration im Aggregate, das Sie bereitstellen, hat Vorrang vor einer Deklaration in einem Aggregate, das es komponiert, selbst wenn das komponierte Aggregate im engeren Geltungsbereich deklariert hat. Die Komposition bleibt maßgeblich: Ein Modul kann das Aggregate, das es konsumiert, nicht einfach dadurch überstimmen, dass es einen engeren Geltungsbereich wählt.
- Spezifität. Innerhalb einer Authoring-Ebene und einer Säule verfeinert der engere Geltungsbereich den breiteren, Feld für Feld. Eine komponentenbezogene Anbindung überschreibt eine subsystemweite oder Boundary-weite Anbindung desselben Instanznamens — aber nur für die Felder, die sie tatsächlich nennt. Felder, die der engere Geltungsbereich auslässt, behalten die Werte des breiteren, sodass eine gemeinsame Anbindung die gemeinsame Konfiguration liefern kann, während eine einzelne Komponente ein Feld davon anpasst. Zwei Beiträge im selben Geltungsbereich werden nach Autorenreihenfolge aufgelöst, wobei der spätere gewinnt; das erlaubt es einem inneren Subsystem, ein äußeres zu verfeinern, und einer tieferen Boundary, eine flachere zu verfeinern.
Der Vorrang regelt Feldwerte. Er ordnet die Auswertung nicht um: Die Abfolge, in der der Compiler die Oberflächen zusammenführt und in der er das injectMapping vor dem Rendering jeder Anbindung ausführt, ist die feste fünfstufige Abfolge, die in architecture/10-compilation-pipeline.md dokumentiert ist. Der verfasste Block inject einer Anbindung folgt dieser Auswertungsabfolge statt der obigen Rangfolge der Geltungsbereiche, sodass eine Anbindung nie zwei konkurrierende Reihenfolgen trägt.
Welche Arten metadata.labels und metadata.annotations tragen
metadata.labels steht an Component, Feature, Aggregate und den vier Bibliotheksarten; metadata.annotations an denselben Arten außer Aggregate. Manifest, Release, Recipe, FeatureRecipe und Plugin tragen keines von beiden.
Zusammenfassung der Kaskadierung
Die Kaskadierungsregeln über die sechs Oberflächen, wie der Compiler sie auswertet:
- Labels der Katalogentitäten (Oberfläche 1) bleiben an der Katalogentität. Sie fließen nicht zu Instanzen; Konsumenten lesen sie, indem sie den Kataloginhalt direkt untersuchen.
metadata.labelsder Component (Oberfläche 2) fließen nach dem optionalen Durchlauflabel-transformbei der Topologiekonstruktion in das knotenbezogene.context.labels.metadata.annotationsder Component (Oberfläche 3) fließen in den knotenbezogenen Bucket.context.annotations.catalog.annotations:des Aggregate / Subsystems (Oberfläche 4) kaskadieren durch die Subsystemhierarchie, wobei sie sich von äußeren Subsystemen nach innen ansammeln, in den knotenbezogenen Bucket.context.annotations.aggregate.annotations:der Release-Boundary (Oberfläche 5) kaskadieren durch die Boundary-Hierarchie von äußeren Boundaries nach innen in den knotenbezogenen Bucket.context.annotations.release.features.annotationsdes Manifest (Oberfläche 6) kaskadiert nicht direkt in knotenbezogene IR-Daten; die Teilphase der annotationsgesteuerten Expansion in der Auflösung konsumiert die Bindungen, um knotenbezogene Feature-Anbindungen zu synthetisieren, die der IR-Graph (--ir-graph) mitorigin: annotationaufzeichnet. Die synthetischen Anbindungen sind nach der Auflösung strukturell nicht von expliziten zu unterscheiden, außer über diese Provenienz — sieheproviders/well-known-annotations.mdfür die vollständige Darstellung der Expansion undarchitecture/13-catalog-and-registry.md§„Annotation-driven Feature expansion (annotationsgesteuerte Feature-Expansion)“ für die Mechanik beim Laden des Katalogs und zur Inspektionszeit.
Zum kanonischen Design der kaskadierenden Annotationen siehe architecture/06-data-taxonomy-and-composition.md §2 (Fluss 5).
Querverweise
templates/template-context-contract.md— Laufzeitsicht auf.context.labelsund die drei Buckets.context.annotations.*.providers/well-known-annotations.md— Matrix der Boundary-Annotationen pro Provider und Asymmetrie bei der Ausgabe von Provenienz-Labels.entities/manifest.md— die Bindungsoberflächefeatures.annotationsdes Manifest (Oberfläche 6).vocabulary/publishing-surface.md— einheitliches Metadatenvokabular, das Labels/Annotationen auf der Veröffentlichungsseite ergänzt.plugins/plugin-contract.md— das Platzierungskriterium des Linter-Sockets für Hinweisprüfungen bei Bucket-übergreifenden Lesezugriffen.architecture/06-data-taxonomy-and-composition.md— kanonisches Design der kaskadierenden Annotationen.architecture/10-compilation-pipeline.md— 5-Ebenen-Zwiebelmodell, das die Feature-Anbindung ordnet.