Bekannte Annotationen
Providers lesen bestimmte Annotationen, um plattformspezifischen Kontext zu konfigurieren — gesetzt auf der Boundary eines Release oder auf dem Eintrag einer Komponente im Release, oder im Aggregate auf einem Subsystem oder einer Komponenteninstanz deklariert. Der Compiler selbst ist agnostisch gegenüber den Werten dieser Annotationen — er reicht sie als opake Zeichenketten durch. Jeder Provider deklariert, welche Annotationen er liest, in welchem Gültigkeitsbereich und welcher Standard gilt, wenn die Annotation fehlt. Diese Deklaration befindet sich in spec.provider.wellKnownAnnotations eines Plugin, das als Provider rendert, und sie ist bewusst eng gefasst: Ein Provider führt einen Schlüssel nur dort auf, wo er ihn liest. Ein Provider, der keinen davon liest, deklariert stattdessen spec.provider.readsNoWellKnownAnnotations: true.
Die Unterstützungsmatrix in diesem Kapitel ist aus diesen Deklarationen generiert, in der Granularität, die die Deklaration trägt — pro Provider pro Eingabeart, weil ein Provider einen Schlüssel lesen kann, wenn er eine Bereitstellungseinheit synthetisiert, und keine Möglichkeit haben kann, ihn zu lesen, wenn er ein lokal kopiertes Artefakt rendert. Verfassen Sie anhand der Matrix hier: Eine Zelle sagt, was dieser Provider auf diesem Pfad liest, weil eine Zelle nichts sagen kann, was der Provider nicht deklariert hat. Eine Deklaration, die eine Eingabeart nennt, die der eigene Render-Verhaltensvertrag des Providers nicht rendert, wird abgelehnt, wenn die Plugin-Entität gelesen wird, sodass die beiden Aussagen nicht voneinander abweichen können.
Das reservierte Vokabular ist die umfassendere Menge, und es befindet sich stattdessen an zwei Orten — in diesem Kapitel, das jeden reservierten Schlüssel nennt, einschließlich derer, die kein Provider liest, und in der Menge reservierter Präfixe, die der Veröffentlichungs-Lint prüft.
Die Invarianten
- Der Compiler interpretiert oder validiert niemals den Wert einer bekannten Provider-Annotation: Er trägt den Schlüssel und seinen Wert durch die Kaskade und warnt, wo ein Ziel nicht auf den Schlüssel reagiert.
- Jeder Provider dokumentiert, welche Annotationen er liest und welche Standardwerte er anwendet.
- Annotationen gelten einheitlich innerhalb einer Boundary. Wenn ein Wert pro Komponente variiert, gehört er in Annotationen auf Komponentenebene (die Boundary-Annotationen überschreiben) oder in das
infrader Komponente. - Bekannte Annotationen der Provider duplizieren niemals Komponenten-Labels. Component-Labels beschreiben, was eine Komponente ist. Boundary-Annotationen beschreiben, wo eine Komponente bereitgestellt wird.
- Recipes behandeln keine bekannten Provider-Annotationen. Der Provider wendet den Platzierungskontext (Namespace, Registry-Präfix, Service-Account) automatisch an, nachdem das Recipe seinen Inhalt erzeugt hat.
- Das Präfix
aggrega.ai/ist der Standardbibliothek vorbehalten. Benutzerdefinierte Unternehmensannotationen verwenden ihr eigenes Präfix. - Annotationen auf Component-Ebene im Release überschreiben Annotationen auf Boundary-Ebene (Deep-Merge, die Komponente gewinnt). Wo ein Provider die Ausgabe mehrerer Boundaries zu einem Artefakt zusammensetzt, kann er verlangen, dass eine Annotation über sie hinweg einheitlich aufgelöst wird — der Provider
helm-chartübernimmt den Namen des Umbrella-Charts ausaggrega.ai/chart-name, und wenn mehr als eine Boundary zum selben Chart beiträgt und sie diese Annotation zu unterschiedlichen Werten auflösen, bricht der Build ab und nennt die abweichenden Boundaries, weil ein Chart nicht zwei Namen tragen kann. - Annotationen, die das Aggregate deklariert, erreichen dieselben Schlüssel unterhalb derer des Release. Ein Schlüssel, der auf einem Subsystem oder auf einer Komponenteninstanz deklariert ist — im Aggregate selbst oder in einem Modul, das es importiert, wo er die eigenen Komponenten des Moduls erreicht —, gilt für die Komponente überall dort, wo das Release keinen Wert für diesen Schlüssel setzt; wo das Release einen setzt, auf der Boundary oder auf dem Eintrag der Komponente, ist der Wert des Release derjenige, der angewendet wird. Die eigenen Annotationen einer Katalogentität setzen niemals einen.
aggrega.ai/chart-nameist die Ausnahme von der Reichweite des Aggregate: Es benennt eine Zusammensetzung statt einer Komponente und wird aus den Release-Boundaries gelesen, die dazu beitragen.
Die vollständige Annotationsmatrix
Wie diese Matrix zu lesen ist
Die sechs Kategorietabellen unten nennen jede Annotation im reservierten Vokabular aggrega.ai/, was sie steuert und was der Provider tut, wenn sie fehlt. Ob ein bestimmter Provider einen bestimmten Schlüssel anwendet, ist eine feinere Frage, weil ein Provider mehr als eine Eingabeart rendert — ein lokal kopiertes Artefakt (sourced), eine Workload, die der Provider selbst synthetisiert (synthesized), oder die artifacts: eines Recipe als die ganze Ausgabe eines Knotens (artifacts-only) —, und ein Schlüssel kann auf einem dieser Pfade gelesen werden, während er auf einem anderen unerreichbar ist. Welcher Provider welche Eingabeart rendert, steht unter ../../architecture/16-recipe-input-composition.md; was jeder anwendet, ist Unterstützung nach Provider und Eingabeart unten, die maßgebliche Aussage dieser Seite.
Jede Zelle in diesem Raster trägt eine von drei Stufen:
- Angewendet — der Provider wendet den Schlüssel bei dieser Eingabeart an, und die gerenderte Ausgabe ändert sich dadurch deterministisch.
- Bedingt angewendet — der Compiler gibt einen additiven Override neben dem Zielartefakt aus, statt das Artefakt zu bearbeiten, daher hängt es davon ab, ob dieses Artefakt einen eigenen passenden Schlüssel anbietet, ob der Wert wirksam wird. In der Praxis wirksam, niemals eine Garantie. Kein Provider implementiert eine bedingte Zelle, und die Deklarationsoberfläche bietet keine Möglichkeit, eine auszudrücken, daher gibt das generierte Raster unten nur die anderen beiden Stufen aus. Die Stufe wird benannt, weil der Weg für ein lokal kopiertes Artefakt tatsächlich existiert, und ein Vokabular mit zwei Stufen würde die Matrix zwingen, entweder eine Garantie zu beanspruchen, die sie nicht geben kann, oder zu bestreiten, dass der Weg überhaupt existiert.
- Nicht angewendet — kein Provider wendet den Schlüssel auf diesem Pfad an: Das Ziel hat dort keinen Render-Slot dafür, daher trägt der Platzierungsmechanismus nichts zu dem bei, was gerendert wird, und die Spalte Standard der Kategorietabelle sagt, was Sie stattdessen erhalten. Der Wert läuft trotzdem als opake Zeichenkette unverändert durch den Build. Die Stufe ist nach dem Mechanismus benannt statt nach dem Schicksal des Werts, weil das verschiedene Fragen sind und nur die erste eine ist, die eine Zelle beantworten kann: Was ein Provider anwendet, ist eine Eigenschaft der Render-Slots dieses Ziels, und genau das gibt die Deklaration hinter jeder Zelle an.
Zwei Gültigkeitsbereiche, und nur einer davon macht die Eingabeart zu einer sinnvollen Achse:
- Knotenbezogen —
aggrega.ai/namespace,aggrega.ai/image-registry,aggrega.ai/image-pull-secret,aggrega.ai/service-accountundaggrega.ai/kubernetes-versionformen die eigene gerenderte Ausgabe einer Komponente, die der Pfad erzeugt, den ihre Eingabeart auswählt. Das sind die Spalten des Rasters. - Auf Zusammensetzung und Referenz bezogen —
aggrega.ai/chart-namewird einmal aufgelöst, wenn ein Umbrella-Chart zusammengesetzt wird, und die drei Schlüsselaggrega.ai/aws-*werden aufgelöst, wenn eine Referenz eine Boundary überquert. Die Eingabeart ist für keinen von beiden eine Achse: Der Wert wird bei der Zusammensetzung oder bei der Referenz gelesen, wie auch immer jeder beitragende Knoten gerendert wurde. Sie haben ihre eigene Tabelle unter Pro Zusammensetzung und pro Referenz aufgelöste Schlüssel.
Kategorie 1 — Platzierung
| Annotation | Angewendet von | Zweck | Standard |
|---|---|---|---|
aggrega.ai/namespace | helm (mit Quelle, synthetisiert); compose (mit Quelle, synthetisiert) | Kubernetes-Namespace (helm); Docker-Netzwerkname (compose) | Wird nicht injiziert, wenn sie fehlt (helm); ein nach dem Pfad der compose-Datei benanntes Netzwerk, das jeder Knoten in dieser Datei ohne die Annotation teilt (compose) |
aggrega.ai/project-name | reserviert; kein Provider liest sie | Reserviert für einen Docker-Compose-Projektnamen | — |
aggrega.ai/region | reserviert; kein Provider liest sie | Reserviert für eine Cloud-Region auf Platzierungsebene | — |
aggrega.ai/account-id | reserviert; kein Provider liest sie | Reserviert für eine Cloud-Account-Kennung auf Platzierungsebene | — |
aggrega.ai/kubernetes-version | helm (mit Quelle) | Kubernetes-Version des Clusters, in dem die Komponente bereitgestellt wird, die ein aus der Quelle gerendertes Chart als .Capabilities.KubeVersion liest | Die Version, für die das unveränderte helm template desselben helm-Release rendert: die der Kubernetes-Clientbibliothek, mit der der Provider gebaut ist |
aggrega.ai/namespace ist bewusst zweifach verwendbar. Es drückt dieselbe Absicht logischer Isolation aus — „die Ressourcen dieser Boundary leben in ihrem eigenen adressierbaren Bereich“ — in der nativen Form jedes Ziels: ein metadata.namespace von Kubernetes für helm, ein Docker-Netzwerkname für compose. Recipe-Autoren setzen eine Annotation; jeder Provider materialisiert sie passend für das Ziel. Im Fall von compose wird der Netzwerkname pro Knoten aus der Annotation auf diesem Knoten aufgelöst, mit dem Pfad der compose-Datei als Rückfall, wo der Knoten keine Annotation trägt — sodass nicht annotierte Boundaries, die sich eine compose-Datei teilen, sich ein Netzwerk teilen, und aggrega.ai/namespace ist das, was sie trennt. Welches von beiden auch die Identität liefert, sie wird dann in die Zeichen geschrieben, die ein compose-Netzwerkname akzeptiert — jedes andere Zeichen wird maskiert ausgeschrieben, statt ersetzt zu werden, sodass zwei Identitäten, die sich überhaupt unterscheiden, auf zwei Netzwerken bleiben, und die Groß- und Kleinschreibung der Identität bleibt wie verfasst erhalten. Die Referenz zum compose-Provider dokumentiert die Ableitung vollständig, einschließlich dessen, wie ein codierter Name zu lesen ist und was eine Umbenennung kostet.
aggrega.ai/kubernetes-version gibt eine Eigenschaft des Clusters an, in dem eine Komponente bereitgestellt wird, statt anzugeben, wo darin die Komponente landet: Chart-Templates wählen eine API-Version, ein Feld oder einen ganzen Mechanismus nach der Version aus, für die sie gerendert werden, und der Build hat keinen Cluster, den er fragen könnte. Der helm-Provider liest den Wert so, wie helm template --kube-version sein Flag liest, und bricht den Build bei einem Wert ab, der keine Version ist; wo keine genannt ist, wird ein Chart für die Version gerendert, für die helm template desselben helm-Release rendert. Die Referenz zum helm-Provider dokumentiert die akzeptierten Formen und den Standardwert.
Kategorie 2 — Registry
| Annotation | Angewendet von | Zweck | Standard |
|---|---|---|---|
aggrega.ai/image-registry | helm, compose — nur synthetisiert | Registry-Präfix für Container-Images, angewendet auf jede synthetisierte Container-Image-Referenz | Kein Präfix |
aggrega.ai/image-pull-secret | helm — nur synthetisiert | Name in imagePullSecrets von Kubernetes, vereinigt mit den vorhandenen Einträgen des synthetisierten Pods | Keiner |
Kategorie 3 — Netzwerk
| Annotation | Angewendet von | Zweck | Standard |
|---|---|---|---|
aggrega.ai/cluster-domain | reserviert; kein Provider liest sie | Reserviert für ein DNS-Suffix für die namespaceübergreifende Diensterkennung | — |
aggrega.ai/ingress-class | reserviert; kein Provider liest sie | Reserviert für eine Kubernetes-IngressClass auf Ingress-Ressourcen | — |
aggrega.ai/service-mesh | reserviert; kein Provider liest sie | Reserviert für Annotationen zur Sidecar-Injektion eines Mesh | — |
Kategorie 4 — Sicherheit
| Annotation | Angewendet von | Zweck | Standard |
|---|---|---|---|
aggrega.ai/service-account | helm — nur synthetisiert | ServiceAccount von Kubernetes für synthetisierte Pods; überschreibt workload.serviceAccount des Recipe, wenn beide gesetzt sind | workload.serviceAccount des Recipe oder nicht gesetzt, wenn das Recipe keines deklariert |
aggrega.ai/pod-security-standard | reserviert; kein Provider liest sie | Reserviert für eine Stufe der Pod Security Standards | — |
aggrega.ai/iam-role | reserviert; kein Provider liest sie | Reserviert für eine an eine Arbeitslast gebundene Cloud-Identitätsrolle | — |
Kategorie 5 — Paketierung
| Annotation | Angewendet von | Zweck | Standard |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — pro Zusammensetzung | Name des Umbrella-Charts | Name des Aggregate und Zusammensetzungspfad des Umbrella-Charts, verbunden — siehe Auflösung des Chart-Namens |
aggrega.ai/chart-version | reserviert; kein Provider liest sie | Reserviert für eine Helm-Chart-Version | — |
aggrega.ai/stack-name | reserviert; kein Provider liest sie | Reserviert für einen explizit benannten Stack | — |
aggrega.ai/tf-backend | reserviert; kein Provider liest sie | Reserviert für eine Kennung des Terraform-State-Backends | — |
Kategorie 6 — Cloud-Ziel
| Annotation | Angewendet von | Zweck | Standard |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — pro Boundary-übergreifender Referenz | AWS-Account, in dem der Stack (Boundary) bereitgestellt wird | Gleicher Account — eine Stack-übergreifende Referenz wird über den Import eines Stack-Exports im selben Account aufgelöst |
aggrega.ai/aws-region | cloudformation — pro Boundary-übergreifender Referenz | AWS-Region, in der der Stack (Boundary) bereitgestellt wird | Gleiche Region — eine Stack-übergreifende Referenz wird über den Import eines Stack-Exports in derselben Region aufgelöst |
aggrega.ai/aws-assume-role-arn | cloudformation — pro Boundary-übergreifender Referenz | ARN der IAM-Rolle, die ein Account-übergreifender Stack-Lesezugriff übernimmt, um die exportierten Werte eines Peer-Stacks zu erreichen | Bei einer Account-übergreifenden Referenz wird keine Rolle übergeben |
Jede CloudFormation-Boundary wird in einen Stack gerendert. Wenn eine Kante uses von einer Boundary zu einer anderen führt, muss der Provider cloudformation wissen, wo der Peer-Stack liegt, um die Referenz zu formen: Zwei Stacks im selben Account und in derselben Region tauschen Werte über einen Stack-Export und -Import aus; ein Peer in einem anderen Account oder einer anderen Region benötigt einen Account-übergreifenden Lesezugriff auf die Stack-Outputs, optional unter einer übernommenen Rolle. Diese Annotationen tragen diesen Platzierungskontext. Jede wird in dem Moment gelesen, in dem der Provider eine solche Referenz formt, und in diesem Moment über die gewöhnliche Annotationskaskade aufgelöst — ein auf der Komponente gesetzter Wert gewinnt gegenüber einem auf der Boundary gesetzten Wert, und ein Wert, den das Release setzt, gewinnt gegenüber einem, den das Aggregate deklariert. Ein Wert auf Boundary-Ebene ist daher die übliche Art, sie auszudrücken, nicht die einzige. Sie sind opake skalare Zeiger-Strings — der Provider leitet sie in die Referenz weiter, die er aufbaut, und löst sie niemals gegen den tatsächlichen Zustand von AWS auf; Account, Region und Rolle werden vom Release übergeben oder im Aggregate deklariert, und die Laufzeitumgebung löst den endgültigen physischen Lesezugriff auf. Wenn jede Annotation fehlt, behandelt der Provider den Peer als im selben Account und in derselben Region liegend und übergibt keine Rolle.
Unterstützung nach Provider und Eingabeart
Die knotenbezogenen Schlüssel, pro Provider und pro Eingabeart. Die Spaltenüberschriften lassen das Präfix aggrega.ai/ weg, das jeder Schlüssel trägt. applied und — tragen die oben definierten Stufen, wobei — nicht angewendet bedeutet; n/a bedeutet, dass der Provider diese Eingabeart überhaupt nicht rendert, sodass dort kein Pfad existiert, auf dem der Schlüssel angewendet oder verfehlt werden könnte.
| Provider | Eingabeart | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-only | — | — | — | — | — |
Jeder mit dem Compiler ausgelieferte Provider hat hier Zeilen, einschließlich eines, der überhaupt keine Platzierungsannotation liest — eine leere Zeilenmenge wäre nicht von einem Provider zu unterscheiden, den noch niemand beschrieben hat. Ein separat gelieferter Provider deklariert auf dieselbe Weise, was er liest, und ist hier nicht aufgeführt, weil eine veröffentlichte Seite keine Provider aufzählen kann, die sie nie gesehen hat.
Ein Recipe kann mehrere Eingabearten gleichzeitig deklarieren — etwa ein workload: mit artifacts: daneben. Lesen Sie das Raster pro Art: Die synthetisierte Ausgabe eines solchen Knotens ist die Zeile synthesized, und seine Artefaktdateien sind der Artefaktfall. Die Zeile artifacts-only ist die Eingabeart, bei der ein Recipe artifacts: und sonst nichts deklariert.
Sie müssen das Raster nicht konsultieren, um es herauszufinden. Das Setzen eines Schlüssels, den das Ziel eines Ihrer Renderings bei keiner der Eingabearten dieses Renderings liest, erzeugt eine Warnung, die den Schlüssel, das Ziel und jede Eingabeart nennt, die dieses Rendering deklariert, sodass sich eine Zelle, in der Sie versehentlich gelandet sind, in dem Moment meldet, in dem Sie bauen, statt darauf zu warten, dass Sie daran denken, hier nachzusehen:
warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored itBei einem Rendering, das mehr als eine Eingabeart deklariert, betrifft die Warnung dieses Rendering als Ganzes, nicht eine seiner Hälften. Weil sich die Arten additiv zusammensetzen, wendet ein Ziel, das den Schlüssel bei irgendeiner davon liest, ihn tatsächlich an, und die Ausgabe dieses Renderings trägt das Ergebnis — daher wird keine Warnung ausgegeben. Eine Warnung erscheint nur, wenn jede Art, die dieses Rendering deklariert, den Schlüssel verfehlt, und sie nennt sie alle:
warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored itEin workload: neben einem source: genügt also, damit aggrega.ai/service-account auf diesem Knoten wirksam wird, und der Build bleibt dazu still — was die ehrliche Meldung ist, weil der Wert die synthetisierte Hälfte erreicht und in den ausgegebenen Manifesten erscheint.
Lesen Sie das Raster pro Rendering, nicht pro Komponente. Ein an einen Knoten angebundenes Feature erzeugt seine Ressourcen über das Ziel, das sein eigenes FeatureRecipe nennt, bei den Eingabearten, die dieses FeatureRecipe deklariert — es landet also in seiner eigenen Zeile dieses Rasters, die nicht die Zeile sein muss, in der seine Host-Komponente landet. Eine Komponente, die ihre Workload synthetisiert, während ein angebundenes Feature daneben artifacts: beisteuert, liest die Zeile synthesized für die eigenen Manifeste der Komponente und die Zeile artifacts-only für die Dateien der Anbindung, und ein bei der ersten angewendeter Schlüssel kann bei der zweiten verfehlt werden. Die Warnung folgt derselben Aufteilung und informiert Sie über jede getrennt, weil es verschiedene Dateien sind. Ein an eine Boundary statt an eine benannte Komponente angebundenes Feature liest das Raster auf dieselbe Weise.
Der Wert läuft trotzdem unverändert durch — der Build bricht nicht ab, weil eine Boundary, die Komponenten auf heterogenen Zielen umspannt, immer ein Rendering haben wird, das auf einen bestimmten Schlüssel nicht reagieren kann, und das ist ein gewöhnliches Release und kein Fehler. Eine Boundary-Annotation kaskadiert, sodass eine verfasste Zeile eine Warnung pro Rendering ergibt, das nicht darauf reagieren kann — so sehen Sie, welche Teile Ihrer Ausgabe betroffen sind. Sie gehört zur Klasse unsupported-field und wird mit dem Flag dieser Klasse stummgeschaltet; Warnungen enthält die Einzelheiten. Zwei Grenzen, die man kennen sollte: Nur die Schlüssel mit dem blanken Präfix aggrega.ai/ werden geprüft, da ein Schlüssel mit Unterpräfix Ihr eigenes Vokabular ist, und ein Provider, der überhaupt keine Unterstützungsaussage deklariert, erzeugt keine Warnung, weil es nichts gibt, womit sich vergleichen ließe, was Sie verfasst haben. Ein Provider, der deklariert, dass er keinen dieser Schlüssel liest, ist auf diese Weise nicht still: readsNoWellKnownAnnotations: true auf seiner Plugin-Entität ist eine Aussage, die keinen Schlüssel abdeckt, sodass jeder Schlüssel mit blankem Präfix, der eines seiner Renderings erreicht, die Warnung auslöst. Der Provider terraform deklariert es.
Warum ein lokal kopiertes Artefakt weniger Schlüssel anwendet. Eine knotenbezogene Annotation wird dort angewendet, wo der Provider einen Render-Slot dafür hat. Wenn der Provider die Bereitstellungseinheit selbst synthetisiert, gehört ihm jedes Feld des Ergebnisses, sodass ein Registry-Präfix, ein Pull-Secret und ein Service-Account alle einen Ort haben, an dem sie landen können. Ein lokal kopiertes Artefakt — ein Helm-Chart, eine compose-Datei, ein Terraform-Modul — trägt stattdessen seine eigene Konfigurationsschnittstelle, und der Compiler liest diese Schnittstelle nicht, sodass er nicht wissen kann, welchem der eigenen Schlüssel des Artefakts ein Registry-Präfix oder ein Service-Account entsprechen würde. Platzierung, die der umgebende Render-Aufruf steuert, gilt weiterhin, weshalb aggrega.ai/namespace auf ein aus der Quelle gerendertes Chart angewendet wird. Platzierung, die bedeuten würde zu entscheiden, wohin innerhalb des Artefakts eines anderen ein Wert gehört, gilt nicht, und ein Autor liefert sie über die eigenen Werte dieses Artefakts. Deshalb sind die Zeilen mit Quelle spärlich, wo die synthetisierten Zeilen voll sind, und das ist die Form, die man von jedem später hinzugefügten Schlüssel erwarten sollte.
Pro Zusammensetzung und pro Referenz aufgelöste Schlüssel
Vier der ausgelieferten Schlüssel sind nicht knotenbezogen, daher stehen sie außerhalb des Rasters oben, statt in es eingefügt zu sein: Die Eingabeart ist für sie keine sinnvolle Achse, und jedem eine Zeile pro Eingabeart zu geben, würde eine einzige Zelle dreimal wiederholen und eine Unterscheidung andeuten, die nicht existiert. Jeder deklariert den Boundary-Gültigkeitsbereich, und die Tabelle unten wird aus diesen Deklarationen generiert.
| Annotation | Angewendet von | Zweck | Standard |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | Name des zusammengesetzten Umbrella-Helm-Charts. | Der Name des Aggregate und der Zusammensetzungspfad des Umbrella-Charts — sein Ausgabeverzeichnis unter dist/, etwa boundaries/data/helm-chart — werden verwendet, jeweils codiert und verbunden. |
aggrega.ai/aws-account | cloudformation | Der AWS-Account, in dem der Stack (Boundary) bereitgestellt wird. Eine Boundary-übergreifende Referenz liest ihn, um zu entscheiden, ob ein Peer-Stack im selben Account liegt. | Der Peer wird als im selben Account liegend behandelt, und eine Stack-übergreifende Referenz wird über den Import eines Stack-Exports im selben Account aufgelöst statt über einen Account-übergreifenden Lesezugriff auf die Stack-Outputs. |
aggrega.ai/aws-region | cloudformation | Die AWS-Region, in der der Stack (Boundary) bereitgestellt wird. Eine Boundary-übergreifende Referenz liest sie, um zu entscheiden, ob ein Peer-Stack in derselben Region liegt. | Der Peer wird als in derselben Region liegend behandelt, und eine Stack-übergreifende Referenz wird über den Import eines Stack-Exports in derselben Region aufgelöst. |
aggrega.ai/aws-assume-role-arn | cloudformation | Der ARN der IAM-Rolle, die ein Account-übergreifender Stack-Lesezugriff übernimmt, um die exportierten Werte eines Peer-Stacks zu erreichen. | Es wird keine Rolle übergeben, und eine Account-übergreifende Referenz trägt kein assume-role. |
Wann jeder aufgelöst wird, was die Deklaration selbst nicht trägt. aggrega.ai/chart-name wird einmal pro Zusammensetzung eines Umbrella-Charts aufgelöst, aus der Boundary-Annotationskaskade; jeder Beitragende zu einer Zusammensetzung muss ihn zum selben Wert auflösen, und eine Abweichung bricht den Build ab und nennt die Boundaries. Die drei Schlüssel aggrega.ai/aws-* werden pro Boundary-übergreifender Referenz mit Vorrang der Komponente vor der Boundary aufgelöst, sodass ein Komponentenwert gegenüber einem Boundary-Wert gewinnt; Kategorie 6 oben beschreibt die Referenz, die jeder davon formt.
Reservierte Namen, die kein Provider liest
Elf Schlüssel in der Matrix oben sind als reserviert; kein Provider liest sie markiert: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name und aggrega.ai/tf-backend.
Einen davon auf einem Release oder in einem Aggregate zu setzen, hat keine Auswirkung auf die gerenderte Ausgabe. Kein Provider liest sie, und kein Standardwert wird an ihrer Stelle angewendet — insbesondere wird für aggrega.ai/cluster-domain kein DNS-Suffix angewendet, sodass ein Recipe, das eine Cluster-Domain benötigt, sie als gewöhnlichen Wert liefern muss, statt sich auf diese Annotation zu verlassen. Ein Recipe-Autor, der eine dieser Verhaltensweisen benötigt, drückt sie als Recipe-Wert oder als Feld infra einer Komponente aus.
Kein Provider deklariert diese elf. In wellKnownAnnotations führt ein Provider nur auf, was er liest, sodass keiner der elf dort erscheint — wer das Plugin helm, helm-chart, compose oder cloudformation öffnet, sieht die Schlüssel, die funktionieren, und nichts sonst. Das ist der Sinn der engen Deklaration: Ein deklarierter Schlüssel ist ein funktionierender Schlüssel, und der Gültigkeitsbereich daneben sagt, auf welchem Pfad.
Zwei der reservierten Namen liegen nahe an aktiven Schlüsseln und sind nicht mit ihnen austauschbar. aggrega.ai/region und aggrega.ai/account-id benennen eine Region und einen Account auf Platzierungsebene und erreichen keinen Provider; die Schlüssel, die der Provider cloudformation liest, sind die im Cloud-Namespace liegenden aggrega.ai/aws-region und aggrega.ai/aws-account in Kategorie 6. Wenn Sie den Stack-übergreifenden Platzierungskontext von CloudFormation meinen, verfassen Sie die Form aws- — das Paar ohne Präfix ist gegen Kollisionen zurückgehalten, nicht mit irgendetwas verbunden. Zwei weitere reservierte Namen werden durch andere Oberflächen statt durch eine Annotation abgedeckt: aggrega.ai/stack-name ist reserviert, während der Stack-Name, in den eine Boundary cloudformation gerendert wird, deterministisch aus der Identität des Release und der Boundary abgeleitet wird; und die Cloud-Identitätsrolle einer Arbeitslast wird als gewöhnliches, vom Operator gesetztes Feld auf dem Feature übergeben, das die Bindung ausgibt, nicht über aggrega.ai/iam-role.
Die Namen bleiben reserviert und bleiben hier aufgeführt, weil das Präfix aggrega.ai/ reserviert ist: Ein Unternehmenskatalog darf keinen dieser Schlüssel für eine eigene Bedeutung wiederverwenden, weil die Plattform den Schlüssel für eine eigene Bedeutung hält. Diese Matrix und die Menge reservierter Präfixe, die der Veröffentlichungs-Lint prüft, bilden zusammen das Reservierungsregister, und beide werden durch eine Prüfung, die beide liest und fehlschlägt, wenn sie auseinanderlaufen, auf derselben Menge von Namen gehalten. Einen der elf zu verfassen, lässt daher weder die Validierung fehlschlagen noch löst es die Regel „das blanke Präfix aggrega.ai/ nicht verwenden“ aus — es hat einfach keine Wirkung.
Die Version des Umbrella-Charts, die eine Boundary helm-chart ausgibt, ist immer 0.1.0; sie ist ein fester Wert und kein Standardwert von aggrega.ai/chart-version.
Hinweis: Bindungen in
features.annotationsdes Manifest, die das Präfixaggrega.ai/verwenden, werden beim Laden abgelehnt; das Präfix ist ausschließlich für die in diesem Kapitel dokumentierten bekannten Provider-Annotationen reserviert. Autoren annotationsgesteuerter Feature-Bindungen verwendenfeature.aggrega.ai/für Abkürzungen der Standardbibliothek oder eine eigene Domain für Unternehmensabkürzungen.Hinweis: Ein explizites
nullauf einer Release-Annotation entfernt die geerbte Bindung von der überschreibenden Boundary oder Komponente (annotationsgesteuertes Feature-Opt-out). Geschwisterkomponenten in derselben Boundary, die sich nicht abgemeldet haben, behalten die geerbte Bindung; fehlende Schlüssel erben wie gewohnt weiter aus der übergeordneten Kaskade.
Im Katalog verfasste Annotationen, die der Compiler liest
Alles oben Genannte ist eine Provider-Annotation: auf dem Release verfasst oder im Aggregate deklariert, vom Compiler als opake Zeichenkette durchgereicht, von einem Provider gelesen. Ein zweites, viel kleineres Vokabular läuft in die andere Richtung — vom Architekten auf den metadata.annotations der Katalogentität selbst verfasst, vom Compiler gelesen und nie von einem Provider gesehen. Invariante 1 oben betrifft das Provider-Vokabular und erstreckt sich nicht auf diese; der Compiler liest genau die hier aufgeführten Schlüssel und keine anderen.
Diese Schlüssel liegen unter einem Unterpräfix <scope>.aggrega.ai/, nicht unter dem blanken Präfix aggrega.ai/, daher liegen sie außerhalb des Reservierungsregisters, das die Matrix oben trägt, und außerhalb der Regel für reservierte Präfixe, die der Veröffentlichungs-Lint auf Schlüssel mit blankem Präfix anwendet.
| Annotation | Verfasst auf | Gelesen von | Zweck |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | metadata.annotations der Component | der Compiler, auf dem finalisierten Graphen | Deklariert eine Präsenzvorgabe: Jede Instanz dieser Component muss mindestens eine Anbindung tragen, deren Typ dem Wert der Annotation entspricht. <label> ist ein vom Autor gewähltes Suffix, das die Anforderung in der Diagnose benennt; es ist kein Slot-Name, und nichts dereferenziert es. Wiederholen Sie den Schlüssel mit unterschiedlichen Labels, um mehrere Vorgaben zu deklarieren. |
Die Vorgabe wird durch eine Anbindung in jedem Gültigkeitsbereich erfüllt — einen Block features: auf Komponenten- oder Subsystemebene, einen Block des Release auf Boundary- oder Komponentenebene oder eine annotationsgesteuerte Expansion —, weil sie die endgültige Anbindungsmenge der Instanz prüft und nicht, woher jede Anbindung stammt. Eine unerfüllte Vorgabe bricht den Build ab und nennt das Label und den erforderlichen Typ; ein Wert, der keine Feature-Typ-URI ist, oder ein Schlüssel ohne Label nach dem Präfix bricht mit einer eigenen Diagnose für eine fehlerhafte Deklaration ab. Die vollständige Behandlung des Verfassens und wie sich eine Vorgabe von einem Slot featuresSchema unterscheidet, steht unter entities/component.md „Präsenzpflichten“.
Von Providern ausgegebene Provenienz-Labels
Die obigen Annotationen fließen in den Build — das Release oder das Aggregate verfasst sie, Provider verarbeiten sie. Providers emittieren außerdem eine parallele Menge von Labels aus dem Build heraus und hängen sie an die gerenderte Ausgabe, damit nachgelagerte Werkzeuge Laufzeitressourcen auf den Kataloginhalt zurückführen können, der sie erzeugt hat. Diese Provenienz-Labels werden nicht im Release verfasst; sie werden aus dem eigenen Zustand des Builds abgeleitet (Identität des Recipe, Boundary-Pfad, Aggregatname, Umgebung, sync wave, Compiler-Version) und vom Provider zur Render-Zeit ausgegeben.
Die Menge, die die Provider ausgeben, angehängt an alle Kubernetes-Manifeste, die der helm-Provider rendert, an jedes über $import: geladene Artefakt, das der helm-chart-Provider einem Sub-Chart hinzufügt, und an jeden von compose ausgegebenen Service — die eigenen Templates eines helm-chart-Sub-Charts werden so kopiert, wie ihr Autor sie geschrieben hat, und tragen daher, was auch immer dieser Autor geschrieben hat:
| Label | Quelle | Ausgabe |
|---|---|---|
app.kubernetes.io/name | Knoten-ID (oder, für eine Ressource, die ein FeatureRecipe ausgibt, der für diese Anbindung abgeleitete Bezeichner — siehe unten) | Nur helm und helm-chart — Kubernetes-Standard-Label, nicht auf compose-Services ausgegeben |
aggrega.ai/component-id | Knoten-ID (oder, für eine Ressource, die ein FeatureRecipe ausgibt, der für diese Anbindung abgeleitete Bezeichner — siehe unten) | Alle drei Provider |
aggrega.ai/recipe-uri | <recipe-name>:<recipe-version> des erzeugenden Recipe (oder des erzeugenden FeatureRecipe bei von einem FR ausgegebenen Ressourcen) | Alle drei Provider, wenn für die erzeugende Entität sowohl Name als auch Version gesetzt sind; eine Annotation bei helm und helm-chart |
aggrega.ai/boundary-path | Boundary-Pfad, in den die Komponente geleitet wurde | Alle drei Provider, wenn der Boundary-Pfad nicht leer ist; eine Annotation bei helm und helm-chart |
aggrega.ai/aggregate-name | metadata.name des Aggregate | Alle drei Provider, wenn gesetzt |
aggrega.ai/compiler-version | Zur Build-Zeit eingestempelte Compiler-Version | Alle drei Provider, wenn gesetzt |
aggrega.ai/provider | Der Provider, der die Ressource gerendert hat | Alle drei Provider |
aggrega.ai/provider-version | Die Version von diesem Provider | Alle drei Provider |
aggrega.ai/environment | metadata.environment des Release | Alle drei Provider — jedes Release deklariert es |
aggrega.ai/sync-wave | Ganzzahl syncWave pro Boundary | Alle drei Provider, wenn ungleich null; eine Annotation bei helm und helm-chart |
Die Werte von aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider und aggrega.ai/provider-version stammen aus Zeichenketten, die der Build nicht an die Kubernetes-Regeln für Label-Werte bindet — ein Aggregate namens imported/flow, eine Umgebung namens eu/prod, die Version (devel) eines Entwicklungs-Builds. Auf helm und helm-chart trägt jedes dieser Labels seinen Wert wie geschrieben, wenn der Wert bereits ein gültiger Label-Wert ist: Buchstaben, Ziffern, -, _ und ., ein Buchstabe oder eine Ziffer an beiden Enden, höchstens 63 Zeichen. Andernfalls trägt das Label den in diese Form umgeschriebenen Wert — jedes andere Zeichen wird zu -, Folgen von - werden zu einem zusammengefasst, die Enden werden bis auf einen Buchstaben oder eine Ziffer gekürzt, und das Ergebnis wird auf höchstens 63 Zeichen abgeschnitten —, und der unveränderte Wert wird als Annotation unter demselben Schlüssel hinzugefügt. Ein Aggregate namens imported/flow erhält daher das Label aggrega.ai/aggregate-name: imported-flow und die Annotation aggrega.ai/aggregate-name: imported/flow; ein Wert ohne ein einziges Zeichen, das ein Label behält, wird allein von der Annotation getragen. Ein Selektor gleicht den Label-Wert so ab, wie er in der gerenderten Ausgabe erscheint, und Werkzeuge, die den exakten Namen benötigen, lesen die Annotation, wenn eine vorhanden ist. Compose, dessen Label-Werte keinen Beschränkungen unterliegen, trägt den unveränderten Wert als Label.
Hinweise zur Ausgabe pro Provider
helm— Labels landen inmetadata.labelsauf jeder gerenderten Kubernetes-Ressource (Deployment, Service, PVC usw.), und die Schlüssel, die ein Label-Wert nicht tragen kann —aggrega.ai/recipe-uri,aggrega.ai/boundary-path,aggrega.ai/sync-wavesowie der unveränderte Wert jedes wie oben beschrieben umgeschriebenen Labels —, inmetadata.annotations. Die Pfade des Modus mit Quelle (Rendern über das Helm SDK mit Label-Injektion nach dem Rendern), des synthetisierten Modus (Arbeitslast-Synthese) und vonartifacts:erzeugen dieselbe Menge.helm-chart— dieselben Labels und Annotationen landen auf jedem über$import:geladenen Artefakt, das der Provider dem Verzeichnistemplates/eines Sub-Charts hinzufügt. Die eigenen Templates des Quell-Charts und ein am Root des Sub-Charts platziertes Artefakt mit Inline-Inhalt tragen keines davon — siehe helm-chart.md.compose— Labels landen inservices.<name>.labelsauf jedem ausgegebenen compose-Service. Der Modus mit Quelle (Label-Injektion nach dem Zusammenführen auf dem zusammengeführten Dokument aus Basis + valuesMapping) und der synthetisierte Modus (Arbeitslast-Synthese, die den Label-Block des Service direkt setzt) erzeugen beide dieselbe Menge. Das Kubernetes-spezifischeapp.kubernetes.io/namewird in der compose-Ausgabe weggelassen.
Bei Ressourcen, die ein FeatureRecipe ausgibt, wird der Wert von aggrega.ai/component-id aus der Anbindung statt aus dem Namen der Host-Komponente gebildet — für jeden Weg, auf dem ein FeatureRecipe diese Ressourcen liefern kann, sodass die Ressourcen einer Anbindung per Label nie von den eigenen Ressourcen der Host-Komponente ununterscheidbar sind. Ob diese Identität auch das ist, wonach diese Ressourcen benannt werden, hängt von der Lieferung ab: Eine Arbeitslast, die Aggrega synthetisiert, wird nach der Identität benannt, während ein Chart oder Fragment, das der Autor der Anbindung geliefert hat, den Helm-Release-Namen und das Ausgabedatei-Präfix der Host-Komponente behält, weil die eigenen Templates des Autors gegen diesen Namen rendern. Wie der Wert zusammengesetzt wird — die beiden möglichen Anfänge, die Teile und ihre Verbindung über --, wie ein Zeichen ausgeschrieben wird, das ein Label nicht tragen kann, wie ein für sein Ziel zu langer Wert gekürzt wird und für welche Namen er die Basis ist und für welche nicht —, ist Provider-unabhängig und wird daher einmal unter vocabulary/labels-and-annotations.md „Provenienz-Labels in der gerenderten Ausgabe“ angegeben, statt hier wiederholt zu werden. Diese Seite verantwortet die andere Hälfte: wo auf der gerenderten Ausgabe jedes Providers die Labels landen.
Der Schlüssel aggrega.ai/recipe-uri wird zum eigenen name:version des FeatureRecipe aufgelöst, nicht zur Identität des konsumierenden Recipe — nachgelagerte Werkzeuge, die das Label lesen, um die erzeugende Entität zu identifizieren, erhalten die korrekte Provenienz sowohl für von Komponenten ausgegebene als auch für von FR ausgegebene Ausgabe.
Sync-wave-Annotationen
Der obige Schlüssel aggrega.ai/sync-wave ist mit einer sync-wave-Annotation gekoppelt, die nachgelagerte Werkzeuge lesen, um die Reihenfolge dessen festzulegen, was sie anwenden. Bei compose ist der Schlüssel ein Label, das den Wert der Welle für Selektor-Abfragen verfügbar macht; bei helm und helm-chart ist er eine Annotation, und die gekoppelte Annotation macht den Wert dort sichtbar, wo jedes Werkzeug ihn üblicherweise liest.
| Annotation | Ausgabe | Verarbeitet von |
|---|---|---|
argocd.argoproj.io/sync-wave | helm, auf jeder Kubernetes-Ressource, die es rendert, und helm-chart, auf jedem über $import: geladenen Artefakt — wo syncWave auf der beitragenden Boundary ungleich null ist | Sync-wave-Reihenfolge von ArgoCD |
helm.sh/hook-weight | Nur helm, auf über Chart-Templates erzeugten Manifesten, die bereits eine Annotation helm.sh/hook tragen, wenn syncWave ungleich null ist | Reihenfolge nach hook-weight von Helm innerhalb einer Hook-Phase |
Die Ausgabe von helm.sh/hook-weight hängt vom Pfad ab
Eine Feinheit, auf die Chart-Autoren hingewiesen werden sollten: helm.sh/hook-weight wird nur auf Manifesten ausgegeben, die über den Chart-Templating-Pfad gerendert werden — das Verzeichnis templates/ des Charts, gerendert über das Helm SDK. Die Manifests, die über den Artefaktpfad erzeugt werden — beim helm-Provider jeder Eintrag des Blocks artifacts: des Recipe, ob Inline-Inhalt oder über $import: geladen, und bei helm-chart ein über $import: geladener Eintrag —, tragen die Annotation argocd.argoproj.io/sync-wave und die vollständige Menge der Provenienz-Labels, erhalten aber nicht helm.sh/hook-weight — selbst dann nicht, wenn das Artefakt eine Annotation helm.sh/hook trägt.
Die Unterscheidung ist struktureller Art: helm.sh/hook und helm.sh/hook-weight sind Reihenfolge-Primitive der Helm-Laufzeit, die für über Chart-Templates erzeugte Hook-Ressourcen gelten. Artefakte des Recipe-Autors sind zusätzliche Ressourcen, die auf der Recipe-Ebene deklariert werden; sie nehmen standardmäßig nicht am Hook-Lebenszyklus von Helm teil.
Wenn Sie für eine Hook-Ressource eine Reihenfolge nach hook-weight von Helm benötigen, verfassen Sie die Ressource als Chart-Template im Verzeichnis source: eines Recipe, das der helm-Provider rendert, statt als Eintrag in artifacts:; die Templates eines helm-chart-Sub-Charts werden so kopiert, wie sie geschrieben wurden, und erhalten keine der beiden Annotationen. Das Chart-Template erhält sowohl argocd.argoproj.io/sync-wave als auch helm.sh/hook-weight, passend zum Wert syncWave der beitragenden Boundary.
Authoring-Beispiele
Platzierung und Registry-Konfiguration auf Boundary-Ebene:
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east aggrega.ai/image-registry: registry.corp.com aggrega.ai/image-pull-secret: corp-registry-creds components: api: {} worker: {}Überschreibung pro Komponente (die Komponente gewinnt gegenüber der Boundary bei demselben Annotationsschlüssel):
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereAnnotationskaskade auf Aggregate-Seite
Annotationen befinden sich auch auf der Authoring-Oberfläche des Aggregate — im Gültigkeitsbereich des Subsystems (spec.subsystems.<name>.annotations) und im Gültigkeitsbereich der Komponenteninstanz (spec.subsystems.<name>.components.<name>.annotations oder spec.components.<name>.annotations für Komponenten auf oberster Ebene). Die Kaskade auf Aggregate-Seite trägt vom Entwickler verfasste Annotationen durch den Subsystembaum nach unten bis zu den enthaltenen Komponenten.
Die Kaskadenregel
Eine Annotation auf Subsystemebene pflanzt sich zu jedem verschachtelten Subsystem und zu jeder enthaltenen Komponente im Teilbaum des Subsystems fort. Annotationen einer näheren Ebene überschreiben Annotationen einer äußeren Ebene mit der Granularität einzelner Schlüssel: Eine Annotation auf Komponentenebene überschreibt jede geerbte Annotation auf Subsystemebene für denselben Schlüssel, ohne Geschwisterschlüssel oder Geschwisterkomponenten zu beeinflussen.
Ein Annotationsschlüssel befindet sich in einem Gültigkeitsbereich in einem von drei Zuständen:
- Fehlender Schlüssel — der Geltungsbereich deklariert keinen Wert für diese Annotation. Verschachtelte Subsysteme und enthaltene Komponenten erben jedes Binding aus einem übergeordneten Geltungsbereich.
- Ein String-Wert — der Gültigkeitsbereich deklariert einen Wert. Verschachtelte Subsysteme und enthaltene Komponenten erben diesen Wert, sofern sie keinen eigenen Wert deklarieren oder darauf verzichten.
- Explizites
nullin YAML — der Gültigkeitsbereich entfernt jede geerbte Bindung für diesen Schlüssel aus seinem Teilbaum. Geschwisterkomponenten und Geschwister-Subsysteme behalten ihre unabhängige Vererbung; nur der Teilbaum des verzichtenden Gültigkeitsbereichs verliert die Bindung.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # propagates to api and worker components: api: # inherits feature.myco/db-pool: "shared-pool" worker: annotations: feature.myco/db-pool: null # opts out for this component only special: annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideIm Aggregate deklarierte Annotationen der Provider
Die Schlüssel der obigen Matrix werden auch durch das Aggregate kaskadiert, und ein Provider wendet an, was die Kaskade auf jeder Komponente hinterlässt. Das aggrega.ai/namespace eines Subsystems platziert jede Komponente darunter; der eigene Wert einer Komponenteninstanz platziert stattdessen diese Komponente. Ein Modul, das das Aggregate importiert, trägt seine eigene Kaskade: Seine Subsysteme und Komponenteninstanzen erreichen die eigenen Komponenten des Moduls, und nichts, was das importierende Aggregate deklariert, reicht in ein Modul hinein.
Das Release steht bei jedem Schlüssel über dem Aggregate. Wo das Release einen Schlüssel für eine Komponente setzt — auf seiner Boundary oder auf dem eigenen Eintrag der Komponente —, wird der Wert des Release angewendet; wo es keinen setzt, der des Aggregate. Die beiden Seiten überlagern sich Schlüssel für Schlüssel, sodass ein Release, das nur aggrega.ai/namespace setzt, ein vom Aggregate deklariertes aggrega.ai/image-registry in Kraft lässt.
Ein explizites null im Release zieht nur den eigenen Wert des Release zurück. Ein Komponenteneintrag, der aggrega.ai/namespace: null schreibt, entfernt den Namespace, den ihm die Boundary seines Release übergeben hätte, und die Komponente übernimmt dann den Wert, den ihr Aggregate deklariert — oder keinen, wo auch das Aggregate keinen deklariert. Ein Release kann einen Wert, den das Aggregate deklariert, nicht entfernen; es kann nur einen eigenen darüber setzen.
# Aggregatespec: subsystems: billing: annotations: aggrega.ai/namespace: billing # api and worker render into billing components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0 annotations: aggrega.ai/namespace: billing-batch # worker renders into billing-batch# Releasespec: boundaries: production: components: api: annotations: aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing worker: {}aggrega.ai/chart-name ist der einzige Schlüssel außerhalb dieser Reichweite: Er benennt ein Umbrella-Chart, das aus mehreren Komponenten zusammengesetzt wird, und wird daher aus den Release-Boundaries gelesen, die zu diesem Chart beitragen, niemals aus den Annotationen einer Komponente.
Ein Template eines Recipe oder FeatureRecipe liest die Annotations-Buckets nach Namen — .context.annotations.aggregate, .context.annotations.release und .context.annotations.catalog enthalten jeweils, was diese Seite geschrieben hat —, sodass ein Template, das einen Platzierungsschlüssel aus einem Bucket liest, nur den Wert dieser Seite sieht.
Die Aufteilung nach Seite und Säule
Die Invariante des Aggregate als Authoring-Oberfläche beschränkt Annotationen auf Aggregate-Seite auf die Werte-Säule. Eine Annotationsbindung eines Manifest deklariert Routing-Pfade entweder unter maps.infra (Routing auf Release-Seite) oder unter maps.values (Routing auf Aggregate-Seite); eine Annotation auf Aggregate-Seite, deren Bindung nur Pfade unter maps.infra deklariert, bricht den Build mit einer klaren Diagnose ab, die den Annotationsschlüssel, die geroutete Säule und die Authoring-Seite nennt. Die symmetrische Regel gilt für die Release-Seite: Annotationen auf Release-Seite dürfen nur über maps.infra routen; eine Annotation auf Release-Seite gegen eine Bindung nur für Werte löst den parallelen Fehler aus. Jede Diagnose wird unter der Domäne des Dokuments eingeordnet, in dem der Annotationswert verfasst wurde — [DEVELOPER_ERROR] aus einem Aggregate, [OPS_ERROR] aus einem Release —, sodass der Kopf die zu öffnende Oberfläche nennt.
Bindungen, die Pfade in beiden Säulen deklarieren, routen in jedem Durchlauf die zur Seite passende Teilmenge: Eine Annotation auf Aggregate-Seite löst nur die Pfade der Werte-Säule aus, und eine Annotation auf Release-Seite löst nur die Pfade der Infra-Säule aus. Seitenübergreifende Komposition — values aus dem Aggregate, infra aus dem Release — erzeugt eine Feature-Anbindung pro Paar (Component, Feature) mit beiden befüllten Säulen und einer Provenienz pro Blatt, die festhält, welche Seite jedes Blatt beigetragen hat.
Authoring-Beispiel — eine Subsystem-Annotation wird zu values geroutet
# Manifest bindingspec: mappings: features: type: core/db-pool: db-pool-helm:1.0.0 annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - pool # routes to values.pool# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0Nach der Annotationsexpansion tragen sowohl api als auch worker eine synthetische Anbindung des Feature feature.myco/db-pool, deren Feld values.pool den Wert "shared-pool" hat. Der Build-Graph (aggrega validate --release <release> --ir-graph) erfasst jedes Blatt mit origin: annotation, side: aggregate und annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.
Strukturierte Annotationswerte
Ein Feature mit mehreren konfigurierbaren Feldern legt einen einzigen Annotationsschlüssel nahe, der Werte für mehrere davon auf einmal trägt. Die strukturierte Annotationsform erlaubt es einem Schlüssel, in einer einzigen Deklaration zu mehreren Pfaden der Bindung zu routen:
# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100Die Bindung des Manifest deklariert das Routing aller vier Unterschlüssel in nach Säulen gruppierten Listen maps::
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connectionsDie Form des Annotationswerts ist eine von drei:
- Skalarer String — ein einzelner Wert. Die Bindung muss insgesamt genau einen Pfad deklarieren; der Skalar wird zu diesem Pfad geroutet.
- Strukturiertes Objekt — eine Map von Unterschlüssel zu Unterwert. Der Pfad jedes Unterschlüssels muss in der Liste
maps.infraodermaps.valuesder Bindung erscheinen; der Unterwert wird zum benannten Feld des Feature-Schemas in der deklarierten Säule geroutet. - Explizites
nullin YAML — verzichtet für diesen Gültigkeitsbereich der Kaskade vollständig auf die geerbte Bindung.
Jeder Unterschlüssel innerhalb eines strukturierten Werts wird unabhängig gegen die Liste maps der Bindung aufgelöst. Ein Unterschlüssel, der weder in maps.infra noch in maps.values vorkommt, bricht den Build mit einem klaren Fehler ab, der den betreffenden Unterschlüssel und die deklarierten Pfade nennt.
Kaskaden-Merge für strukturierte Werte
Strukturierte Annotationen kaskadieren mit einem Deep-Merge pro Unterschlüssel. Die Annotation eines untergeordneten Gültigkeitsbereichs der Kaskade wird pro Unterschlüssel mit der Annotation des übergeordneten zusammengeführt; die nähere Ebene überschreibt die übergeordnete mit der Granularität einzelner Unterschlüssel:
subsystems: data: annotations: feature.myco/db-pool: db_name: "data-default" read_replicas: 3 components: api: annotations: feature.myco/db-pool: db_name: "api-override" # overrides parent at this subkey only # read_replicas not listed → inherits 3 from parent analytics: annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out: removes inherited subkey # db_name not listed → inherits "data-default" from parentEffektive Annotationen nach der Kaskade:
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" }— aufread_replicaswird in diesem Gültigkeitsbereich verzichtet
Eine untergeordnete Kaskadenebene, deren Wert ein Skalar ist (gegenüber einer strukturierten übergeordneten Ebene), ersetzt vollständig, statt zusammenzuführen. Formabweichungen zwischen Kaskadenebenen werden zugunsten des Werts der näheren Ebene aufgelöst; der Compiler warnt bei einer Formabweichung nicht.
null für den ganzen Wert und null pro Unterschlüssel
Die Kaskade kennt zwei Verzichtsmechanismen mit unterschiedlicher Granularität:
# Whole-value null — opts out wholesale at this scopecomponents: api: annotations: feature.myco/db-pool: nullDie gesamte Annotationsbindung wird bei dieser Komponente unterdrückt; aus diesem Annotationsschlüssel wird in diesem Gültigkeitsbereich keine synthetische Feature-Anbindung synthetisiert. Geschwisterkomponenten behalten ihre geerbte Bindung.
# Per-subkey null — opts out just one subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: nullDie Annotation trägt in diesem Gültigkeitsbereich weiterhin bei, aber der Unterschlüssel read_replicas wird unterdrückt. Andere Unterschlüssel (in diesem Gültigkeitsbereich deklariert oder von übergeordneten Kaskadenebenen geerbt) bleiben bestehen.
Hinweis zum Authoring: Verwenden Sie null für den ganzen Wert, um eine annotationsgesteuerte Feature-Anbindung in einem Gültigkeitsbereich zu deaktivieren. Verwenden Sie null pro Unterschlüssel, wenn Sie den größten Teil des Beitrags einer Annotation behalten, aber ein oder mehrere bestimmte Felder unterdrücken möchten.
Aufteilung nach Seite und Säule pro Unterschlüssel
Die Invariante des Aggregate als Authoring-Oberfläche gilt pro Unterschlüssel, wenn ein Annotationswert strukturiert ist. Die Säule jedes Unterschlüssels (gemäß der Deklaration maps der Bindung) muss mit der Authoring-Seite vereinbar sein:
- Eine Annotation auf Aggregate-Seite darf nur Unterschlüssel tragen, die zu
maps.valuesrouten. - Eine Annotation auf Release-Seite darf nur Unterschlüssel tragen, die zu
maps.infrarouten.
Ein Unterschlüssel, der zu einer unvereinbaren Säule routet, bricht den Build mit einem klaren Fehler ab, der den betreffenden Unterschlüssel und die Säule nennt. Die Fehlerkette sammelt vor dem Abbruch alle unvereinbaren Unterschlüssel pro Annotation — Betreiber sehen jedes Problem in einem einzigen Build-Durchlauf, statt immer wieder zu korrigieren und neu zu bauen.
Typvalidierung pro Unterschlüssel
Der Laufzeitwert jedes Unterschlüssels wird gegen den in spec.schema des Ziel-Feature deklarierten Typ in der gerouteten Säule validiert. Die unterstützten deklarierten Typen sind string, integer, number, boolean, object, array, null. Ein Unterwert, dessen YAML-Typ nicht dem deklarierten Typ des Schemas entspricht, bricht den Build mit einem klaren Fehler ab, der den Unterschlüssel, den tatsächlichen Typ und den deklarierten Typ nennt.
Der Typabgleich ist strikt — keine Typumwandlung. Ein String "20" gegen ein Schemafeld vom Typ Integer bricht den Build ab; Autoren deklarieren Typen korrekt im Schema des Feature oder verwenden skalare Annotationen, die als Strings durchgereicht werden.
Authoring-Hebel für strikte Validierung. Eigenschaften ohne deklarierten type in spec.schema des Feature akzeptieren jede Form des Laufzeitwerts, einschließlich verschachtelter Maps. Wenn das Schema keine Einschränkung deklariert, erfindet der Build keine. Autoren, die eine strikte Typvalidierung pro Unterschlüssel wünschen, deklarieren type für jede Eigenschaft in spec.schema. Die nachgelagerte Rendering-Schicht des FeatureRecipe verarbeitet jede Form, die der Annotationsbeitrag trägt.
Seitenübergreifende Komposition
Wenn sowohl eine Annotation auf Aggregate-Seite (values-Unterschlüssel) als auch eine Annotation auf Release-Seite (infra-Unterschlüssel) dieselbe Feature-Anbindung an derselben Component betreffen, führt der Build die Beiträge zu einer einzigen Feature-Anbindung mit beiden befüllten Säulen zusammen. Die Provenienz pro Blatt erfasst die Quelle jedes Unterschlüssels — die synthetisierte Anbindung trägt values.db_name, zugeordnet zur Authoring-Stelle des Aggregate, und infra.pool_size, zugeordnet zur Authoring-Stelle des Release.
Das Muster der seitenübergreifenden Komposition ist die kanonische Authoring-Form für Features mit gemischten Feldern aus Entwicklerabsicht und Dimensionierung durch den Betreiber: Das Aggregate deklariert die kognitiven Entscheidungen (welche Datenbank, wie viele Replikate auf Anwendungsebene); das Release deklariert die physische Dimensionierung (wie groß der Pool, wie viele Verbindungen auf Infrastrukturebene). Eine einzige Bindung des Manifest verbindet beide mit einer einzigen Menge von Deklarationen maps.
Verwandte Referenzen
- Provider-Architektur — die Plugin-Architektur der Provider und die Rolle des Plugin, das als Provider rendert.
- ../entities/release.md — die Authoring-Oberfläche des Release, auf der Boundary- und Komponenten-Annotationen liegen.
- ../entities/aggregate.md — die Authoring-Oberfläche des Aggregate, auf der Annotationen auf Subsystem- und Komponentenebene liegen.
- ../entities/manifest.md — die Map
mappings.features.annotationsdes Manifest, in der Annotationsbindungen ihr Routingmaps:deklarieren. - ../../architecture/11-governance-and-compliance.md — wie die Provenienz zur Kompilierzeit eingestempelt wird, als Ergänzung zu den vom Autor gesteuerten Annotationen.