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

Benennung einer gerenderten Ressource

Ein Recipe muss routinemäßig etwas benennen, das seine eigene Ausgabe erzeugt hat: einen Hostnamen, der über provides: veröffentlicht wird, eine Referenz innerhalb eines valuesMapping:, einen Bezeichner, der in einen Body in artifacts: geschrieben wird. Zwei Schlüssel des Template-Kontexts tragen die dafür verfügbaren Namen, und sie beantworten unterschiedliche Fragen. Den falschen zu lesen, erzeugt eine Ausgabe, die stillschweigend falsch statt abgelehnt ist — eine Adresse, die eine Ressource benennt, die nichts emittiert hat —, daher legt diese Seite dar, welcher Schlüssel welche Frage beantwortet.

Sie legt auch die Unterscheidung dar, auf der die beiden Schlüssel beruhen: Ein Ziel und eine Referenz sind nicht dasselbe, und ein Ziel ist nie ein Name, den eine Bereitstellungsplattform auflösen wird.

Ein Ziel benennt eine Komponente; eine Referenz benennt eine gerenderte Ressource

Ein Ziel ist eine Autorenidentität. Es ist der Wert, den ein Entwickler schreibt, um zu sagen, auf welche Komponente eine Kante zeigt — target: my_db in einem Block uses —, und es ist die Identität, die der Build verwendet, um diese Komponente zu finden, in Diagnosen über sie zu berichten und ihre Fakten danach zu schlüsseln. Es liest sich unter jedem Provider gleich, weil es eine Tatsache über Ihre Dokumente ist und nicht über irgendeine Plattform.

Eine Referenz ist das, was ein gerendertes Artefakt auf ein anderes zeigen lässt. Sie wird im eigenen Vokabular eines Providers geschrieben: eine clusterinterne Adresse unter helm, ein Dienstname unter compose, eine Interpolation unter terraform, ein importierter Wert unter cloudformation. Eine Referenz ist unter jedem Provider anders, weil jede Plattform Referenzen auf ihre eigene Weise auflöst.

🔴 Ein Ziel wird nie in gerenderte Ausgabe geschrieben. Jeder Provider leitet seine eigenen Namen ab, daher ist eine verfasste Identität, die einer Plattform als Name übergeben wird, immer dann falsch, wenn sich die beiden Schreibweisen unterscheiden — und sie unterscheiden sich genau bei den Zeichen, die das eigene Alphabet eines Ziels nicht zulässt. Eine Identität ohne ein solches Zeichen bleibt unverändert, und genau das macht es leicht, hier einen Fehler zu machen: Der Fehler funktioniert, bis jemand eine Komponente mit einem Unterstrich oder einem Großbuchstaben benennt.

Die Referenz, die ein Konsument braucht, wird daher vom Produzenten veröffentlicht, weil das Recipe eines Produzenten dasjenige ist, das das Vokabular seines eigenen Providers kennt — ein Konsument kann einen völlig anderen Provider binden und kann keine Referenz für eine Plattform schreiben, für die er nicht rendert. Der Konsument liest eine gewöhnliche veröffentlichte Zeichenkette.

Das ausgearbeitete Paar

Das Recipe des Produzenten veröffentlicht die Adresse; der Konsument liest sie über den Alias der Kante zurück.

# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.
# It publishes an in-cluster address built from the name that chart's own
# templates render their resources against.
spec:
capability: helm
source: ./charts/postgres
provides:
host: "{{ .context.rendered_name }}.svc.cluster.local"
port: "5432"
# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an
# authoring identity and stays in the documents. The uses block is keyed by the
# socket the catalog entity declares, then by the alias you choose for the edge.
spec:
components:
api:
type: core/compute/api-server
uses:
databases:
primary:
target: my_db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.
# The context keys an edge by its alias, so the socket does not reappear here.
spec:
capability: helm
valuesMapping: |
{
"db_host": "{{ .context.uses.primary.provides.host }}"
}

Bei einem vom Autor gelieferten Chart unter helm rendert eine Komponente namens my_db ihre Ressourcen unter dem Release-Namen my-zudb. Daher emittiert das Chart des Produzenten einen Service, dessen metadata.name my-zudb ist, der veröffentlichte host ist my-zudb.svc.cluster.local, und der Konsument wählt einen Service an, der existiert — ob er den Wert über .context.uses.primary.provides.host liest oder ihn als injiziertes DB_HOST erhält.

Würde man dort {{ .context.uses.primary.target }} schreiben, würde stattdessen my_db.svc.cluster.local veröffentlicht. Dieser Wert sieht nicht falsch aus: Er ist die Identität, die der Entwickler geschrieben hat, genau so geschrieben, wie er sie geschrieben hat. Er benennt einfach keinen Service, und nichts am Build weist darauf hin.

Die beiden Schlüssel als Paar

Keiner der beiden Schlüssel ist für sich allein verständlich, weil jeder durch das definiert ist, was der andere nicht ist.

SchlüsselWas er benennt
{{ .context.instance_id }}Die Identität des Knotens und der Name der für diesen Knoten erstellten Ressourcen, für die kein Provider einen Namen ableitet — ein aus Ihrem Block artifacts: platzierter Artefaktsatz und eine Workload, die ein Provider, der sie nach der Identität benennt, wie es compose tut, aus Ihrem Block workload: synthetisiert. Immer vorhanden.
{{ .context.rendered_name }}Der Name, den der gebundene Provider für die Ressourcen ableitet, die er für diesen Knoten rendert — für Quellen, die Sie bereitgestellt haben, der Name, gegen den Ihre eigenen bereitgestellten Templates ihre Ressourcen rendern, etwa der Release-Name, den ein Chart liest; für einen workload:, den er synthetisiert, der Name, den er diesen Ressourcen gibt, wenn er sie nach einem eigenen Namen statt nach der Identität benennt, wie es helm tut. Nur vorhanden, wo dieser Provider einen ableitet. In den eigenen Templates einer Feature-Anbindung ist es der Name der Host-Komponente — siehe unten.

Die Aufteilung ergibt sich daraus, wo der Name verwendbar sein muss. Ein Chart oder Modul, das Sie bereitgestellt haben, hat Templates, und diese Templates benennen ihre Ressourcen nach der Identität, die die Plattform ihnen übergibt — daher muss der Name derjenige sein, den diese Plattform verwenden wird, geschrieben im eigenen Alphabet dieser Plattform. Eine synthetisierte Workload hat keine Templates von Ihnen, aber ihre Ressourcen müssen dennoch Namen tragen, die die Plattform akzeptiert: Ein Provider, dessen Namen alles zulassen, was ein verfasster Name enthalten darf, benennt sie nach der Identität, und einer, dessen Namen das nicht tun, benennt sie nach dem Namen, den er ableitet — und meldet diesen Namen dann hier, sodass Sie ihn nie vorhersagen müssen.

Ein Knoten, der sowohl eine bereitgestellte Quelle als auch einen workload: deklariert, erzeugt beide Arten von Ausgabe zugleich und braucht keinen dritten Schlüssel. Unter helm werden beide nach dem einen Release-Namen benannt, daher dient rendered_name für beide: Die eigenen Ressourcen des Charts tragen ihn, wie auch immer seine Templates ihn zusammensetzen, und jeder synthetisierte Service ist <rendered_name>-<service key>. Unter einem Provider, der eine synthetisierte Workload nach der Identität benennt, benennen Sie die Ressourcen dieser Workload mit instance_id und die der bereitgestellten Ausgabe mit dem, was der Provider dafür meldet.

Die Alphabete sind der Grund, warum sich die beiden überhaupt unterscheiden können. Ein verfasster Komponentenname darf einen Unterstrich oder einen Großbuchstaben enthalten; der Release-Name eines Charts nicht, und statt ein solches Zeichen auf ein ähnliches abzubilden — wodurch zwei Komponenten, die Sie unterscheiden können, in einem Cluster bei einem einzigen Namen ankämen — schreibt die Ableitung es aus. Siehe ../providers/helm.md „How the release name is derived (Wie der Release-Name abgeleitet wird)“ für das eigene Alphabet und die Längenbegrenzung dieses Providers.

Welche Provider einen Namen melden und warum die anderen nicht

helm meldet einen: den Release-Namen. Ein als Quelle bereitgestelltes Chart liest ihn als .Release.Name und benennt seine Ressourcen routinemäßig danach, und der Provider benennt auch jede Ressource, die er für eine Komponente synthetisiert, danach — den Controller mit dem Release-Namen selbst und jeden Service als <release name>-<service key>. Daher wird eine Adresse, die für eine der beiden Arten von Ausgabe veröffentlicht wird, aus rendered_name gebildet. Für einen Knoten, der allein einen Artefaktsatz platziert, meldet er keinen: Die Namen in diesem Satz sind diejenigen, die sein Autor geschrieben hat.

# A synthesized helm Recipe publishing the address of the Service its workload
# declares under the key `default`.
spec:
capability: helm
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
containers:
main:
image: "valkey/valkey:8"
ports:
redis: 6379
services:
default:
type: ClusterIP
ports:
redis: 6379
provides:
host: "{{ .context.rendered_name }}-default"
port: "6379"

Eine Komponente namens cache veröffentlicht cache-default, und eine namens my_cache veröffentlicht my-zucache-default — in jedem Fall der Name des Service, den der Build erzeugt.

Die anderen vier melden keinen, und die Gründe sind nicht dieselben. Keiner von ihnen ist ein Provider, der auf Unterstützung wartet — in jedem Fall gibt es entweder keinen abgeleiteten Namen zu melden, oder der gewünschte Name ist bereits auf anderem Weg erreichbar.

  • cloudformation und compose — Sie haben die Namen geschrieben, oder die Identität ist der Name. Ein cloudformation-Recipe verfasst die logischen IDs seiner Ressourcen, und der Provider liest sie genau so, wie sie geschrieben sind; eine von Ihnen bereitgestellte Compose-Datei benennt ihre eigenen Services, und der Provider führt diese Datei zusammen und versieht sie mit Labels, ohne darin etwas umzubenennen. Eine Workload, die compose synthetisiert, wird nach der Identität des Knotens benannt, die eine Compose-Datei so zulässt, wie sie geschrieben ist, daher ist {{ .context.instance_id }} dieser Name. Es gibt keine Ableitung zu melden, und die Namen sind diejenigen, die in Ihren eigenen Dokumenten stehen. Dieser Name ist der Haupt-Service der Workload, derjenige, den ein Peer erreicht; ein Sidecar- oder Init-Service, den sie trägt, wird aus derselben Identität und dem Namen des Containers benannt, verbunden durch --, wie Wie ein Sidecar- oder Init-Service benannt wird beschreibt.

  • terraform — der Name hängt davon ab, wo die Dateien platziert wurden. Der Block module eines Beitragenden wird nach dem Ausgabeverzeichnis benannt, in das seine Konfiguration geschrieben wurde, und das steht fest, wenn die Dateien der Boundary zusammengestellt werden, nicht wenn ein Knoten gerendert wird. Zu dem Zeitpunkt, an dem die Templates eines Recipe laufen, existiert diese Position noch nicht.

  • helm-chart — der Name, den er ableitet, ist die eigene Adresse des platzierten Charts, und das ist etwas anderes als der Name, gegen den die Templates dieses Charts rendern. Dieser Provider setzt das Feld name eines Charts, das Sie per Vendoring eingebunden haben, auf die kodierte Identität dessen, was es beigetragen hat; das ist zugleich der Alias, unter dem das Umbrella-Chart dieses Sub-Chart bindet, und der Schlüssel, unter dem seine Werte eingeordnet sind. Für eine Komponente ist diese Identität das, was {{ .context.instance_id }} trägt, daher ist der Name des platzierten Charts bereits unter dem Schlüssel erreichbar, der sagt, was er ist. Der Name, gegen den die eigenen Templates des eingebundenen Charts rendern, ist der Release-Name, den das Release des Umbrella-Charts zur Installationszeit liefert, statt dass dieser Provider ihn ableitet — daher gibt es hier keinen solchen Namen, den dieser Schlüssel melden könnte. Siehe ../providers/helm-chart.md „The chart name the umbrella owns (Der Chart-Name, der dem Umbrella-Chart gehört)“.

Den Schlüssel lesen, wo kein Name gemeldet wird

Das Lesen von {{ .context.rendered_name }} auf einem Knoten, dessen Provider keinen solchen Namen meldet, hält den Build an, und die Diagnose sagt, welcher Schlüssel stattdessen zu schreiben ist. Es wird kein leerer Wert gerendert: Eine Adresse, der ein Segment fehlt, ist ein falsches Artefakt, das bereitgestellt wird, und das ist schlimmer als ein Build, der anhält.

Welche Abhilfe der Abbruch anbietet, hängt vom Knoten ab und nicht davon, wo Sie die Referenz geschrieben haben:

  • Ein Knoten, der keine eigene Quelle bereitstellt, hat unter einem Provider, der keinen Namen für ihn meldet, seine Ressourcen nach seiner Identität benannt, daher nennt der Abbruch {{ .context.instance_id }} — es gibt einen korrekten Wert, und er sagt es.
  • Ein Knoten, der sehr wohl Quellen bereitstellt, hat unter einem Provider, der keinen Namen für ihn ableitet, keinen Ersatz. Der Abbruch sagt das, statt einen anzubieten, denn Sie dort auf die Identität zu verweisen, würde Ressourcen benennen, die Ihr Knoten nicht trägt.

Die Ablehnung umfasst provides: und jedes andere Template, das ein Recipe inline schreibt — sein valuesMapping:, seinen Körper workload:, jeden Eintrag artifacts: sowie with: und when: jedes Pipeline-Schritts.

🔴 Beide Importformen liegen außerhalb davon. Ein Eintrag valuesMapping:, workload: oder artifacts:, der über $import: bereitgestellt wird — ob der Import eine lokale Datei oder einen Bibliothekseintrag nennt —, trägt keinen Text in Ihrem Recipe, bis das Rendering ihn auflöst, daher wird eine Referenz auf diesen Schlüssel innerhalb eines solchen Körpers nicht geprüft. Sie rendert den Namen, den der Provider des importierenden Knotens meldet, wo dieser Provider einen meldet, und einen leeren Wert statt eines Abbruchs, wo er keinen meldet. Ein importierter Körper liest den Schlüssel daher nur, wenn jedes Recipe, das ihn importiert, einen Provider bindet, der einen Namen meldet — ein Bibliothekseintrag, der für Recipes unter helm geschrieben ist, die ein Chart als Quelle verwenden, und der das in seiner Beschreibung sagt. Ein Körper, der für Importer gedacht ist, deren Provider womöglich keinen meldet, bezieht den Namen stattdessen über einen Wert, den das importierende Recipe setzt.

Die Einträge locals: eines Recipe lesen den Schlüssel überhaupt nicht. Ein Local teilt seinen Kontext mit dem Template source: des Recipe, und ob der Knoten Quellen bereitstellt, ist eines der Dinge, von denen der Name abhängt, daher wird der Name dort nicht angeboten. Eine Referenz auf {{ .context.rendered_name }} in einem Local bricht daher ab, was auch immer der Provider meldet, mit der Diagnose für eine Referenz, die der Render-Kontext nicht definiert (E0060), die .context.instance_id als den einen Schlüssel aufführt, den .context dort anbietet. Lesen Sie den Schlüssel in dem Eintrag provides: oder dem Inline-Template, das ihn braucht.

In den eigenen Templates einer Feature-Anbindung

In den Templates, die das FeatureRecipe einer Feature-Anbindung schreibt — seine locals:, source:, provides:, injectMapping:, valuesMapping:, workload:, jeder Eintrag artifacts: sowie with: und when: jedes Pipeline-Schritts —, ist {{ .context.rendered_name }} der Name der Host-Komponente: derjenige, den der eigene Provider des Hosts für die Ressourcen meldet, die er für den Host rendert, und das ist der Wert, den das eigene Recipe des Hosts liest. Er bildet ein Paar mit {{ .context.instance_id }}, das in diesen Templates die Identität der Host-Komponente ist; die Anbindung selbst ist .attachment_name. Eine Anbindung, die auf einer der Verbindungen einer Komponente geschrieben ist, liest den Namen der konsumierenden Komponente, weil diese Komponente ihr Host ist.

Das ist der Schlüssel, aus dem die eigenen Ressourcennamen einer Anbindung zu bilden sind. Ein FeatureRecipe, das ein Secret, eine Route oder eine Policy nach der Komponente benennt, an die es angebunden ist, braucht einen Namen, den die Plattform akzeptiert, und die Identität des Hosts, wie sie geschrieben ist, ist keiner, wo immer sie einen Unterstrich oder einen Großbuchstaben enthält. Unter helm meldet eine Komponente namens my_db den Namen my-zudb, daher wird ein Secret namens {{ .context.rendered_name }}-{{ .attachment_name }} für eine Anbindung root als my-zudb-root gerendert, wo {{ .context.instance_id }} den Namen my_db-root ergäbe, den ein Cluster ablehnt. Der Wert bleibt der des Hosts, über welchen Provider die Anbindung auch rendert.

Er ist überall vorhanden, wo der Provider des Hosts einen Namen meldet — unter helm bei einem Host, dessen Recipe ein Chart bereitstellt oder einen workload: deklariert — und fehlt, wo er keinen meldet: bei einem Host, der allein einen Artefaktsatz platziert, und bei einem Host unter jedem anderen Provider. Ihn auf einer Anbindung eines solchen Hosts zu lesen, hält den Build an, mit der Diagnose für eine Referenz, die der Render-Kontext nicht definiert (E0060), die die Schlüssel aufführt, die .context dort definiert. {{ .context.instance_id }} ist darunter, und danach werden die eigenen Ressourcen des Hosts auf einem solchen Host benannt, daher liest ein FeatureRecipe, das für Hosts geschrieben ist, die womöglich keinen Namen melden, stattdessen die Identität.

Die Ablehnung umfasst die Templates, die ein FeatureRecipe inline schreibt, mit Ausnahme seines injectMapping:. Ein injectMapping: sowie ein Eintrag valuesMapping:, workload: oder artifacts:, den das FeatureRecipe über $import: bereitstellt, wird nicht geprüft: Auf einem Host, der keinen Namen meldet, rendert eine Referenz dort einen leeren Wert, statt abzubrechen.

Wo eine Anbindung ein Chart liefert, das ihr Autor bereitgestellt hat, rendern die Templates dieses Charts bewusst gegen den Release-Namen der Host-Komponente: Ihn stattdessen aus der Anbindung abzuleiten, würde Ressourcen umbenennen, die der Autor des Charts deklariert und womöglich bereits bereitgestellt hat. .attachment_name ist der Wert, der zwei Anbindungen auf einem Host unterscheidet — siehe ../providers/helm.md „How the release name is derived (Wie der Release-Name abgeleitet wird)“.

Aus der Anbindung einer Verbindung abgeleitete Namen

Eine Anbindung, die eine Verbindung trägt, ist eine Anbindung der konsumierenden Komponente, benannt <alias>.<slot> — gpt.credential für den Slot credential der Verbindung, die unter dem Alias gpt geschrieben ist (siehe den Verbindungseintrag des Aggregate). Dieser zusammengesetzte Name ist der .attachment_name, gegen den ihr FeatureRecipe rendert, und er enthält den Punkt.

Daraus ergeben sich zwei Arten von Namen, und sie behandeln den Punkt unterschiedlich.

Ein Name, den das FeatureRecipe zusammensetzt, behält, was auch immer sein Template schreibt. Die Anmeldedaten-Realisierungen der Standardbibliothek benennen ihre Ressource {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, daher werden die Anmeldedaten auf der Verbindung gpt einer Komponente namens router als Ressource namens router-gpt.credential gerendert, einschließlich des Punkts, und das ist ein gültiger Kubernetes-Objektname. Der Punkt bleibt in einem Namen dieser Art genau dann erhalten, wenn das Template ihn behält.

Ein Name, den der Build aus der Identität der Anbindung ableitet, schreibt den Punkt aus. Die Identitäts-Labels und die erzeugte Datei werden aus der Host-Komponente und dem Namen der Anbindung über dieselbe Kodierung zusammengesetzt, die jeder aus einer Identität abgeleitete Name durchläuft, und sie schreibt den Punkt als zd und einen Großbuchstaben als Escape seines Codepunkts, weil die Identität sowohl als Ressourcenname als auch als Label verwendet wird und ein Service-Name keines von beiden zulässt: Eine Verbindung, die unter dem Alias gptPro geschrieben ist, käme bei cfr--router--gpt-zx000050ro-zdcredential an. Die obige Ressource trägt das Label aggrega.ai/component-id: cfr--router--gpt-zdcredential (und app.kubernetes.io/name ebenso), und unter dem Provider helm wird sie als router--gpt-zdcredential--router-secret-router-gpt-credential.yaml erzeugt. Siehe Namenskonventionen „The separator does not reach a name (Das Trennzeichen erreicht keinen Namen)“, warum der Punkt ausgeschrieben statt ersetzt wird.