provides, inject, uses
Kontrakt wstrzykiwania i wstępnie rozwiązana mapa
Ponieważ Aggrega jest statycznym kompilatorem Ahead-of-Time (AOT), podczas kompilacji żadne dane nie płyną wstecz z działającej infrastruktury. Kompilator mechanicznie nie jest w stanie aktywnie pobrać fizycznego poświadczenia (np. sekretu AWS) i przekazać go „z powrotem” do środowiska kontenera dewelopera.
Zamiast tego platforma opiera się na prawdziwym odwróceniu sterowania. Gdy deweloper pisze inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] }, nie inicjuje pobierania danych; narzuca infrastrukturze ścisły kontrakt.
- Intencja (domena 1): deweloper deklaruje abstrakcyjny interfejs: „Potrzebuję sekretu. Nie wiem, gdzie się znajduje. Po prostu wstrzyknij go do mojego środowiska jako
ORACLE_PASSWORD, mapując na kluczpasswordz katalogu.” - Przekazanie przez kompilator (podczas renderowania): Kompilator Go pobiera wpis
{ in: ORACLE_PASSWORD, from: "password" }i przekazuje go do Recipe zespołu Ops. Żaden fizyczny sekret nie jest pobierany. - Wynik Plugin (Domena 3): Potok Wasm encji FeatureRecipe odpowiedzialnej za poświadczenia generuje dokładnie te powiązane ze sobą artefakty, których wymaga infrastruktura docelowa. Na przykład w Kubernetes generuje CRD
ExternalSecret(instruujący klaster, aby pobrał dane z sejfu) ORAZ wykonuje JSONPatch na docelowym Podzie, aby zmapować wynikowy lokalny Secret K8s dokładnie na zmienną środowiskową"ORACLE_PASSWORD", której zażądał deweloper. - Rzeczywistość w czasie działania: W czasie działania operator w klastrze po prostu wykonuje te wygenerowane artefakty — pobiera poświadczenie i fizycznie montuje je w kontenerze — co całkowicie oddziela fizyczne mechanizmy bezpieczeństwa od kompilatora AOT.
Aby dostarczyć tę fizyczną rzeczywistość do aplikacji bez naruszania separacji odpowiedzialności, Aggrega wykorzystuje kontrakt wstrzykiwania. Kontrakt ten ściśle jednak rozróżnia własny kod aplikacji i gotową infrastrukturę komercyjną (COTS, Commercial Off-The-Shelf):
- White-Box (własny kod): komponent jest ogólnym procesem roboczym (np. własnym agentem w Pythonie). Kompilator Go i Recipe zespołu Ops nie mają pojęcia, jakich zmiennych oczekuje własny skrypt dewelopera. Dlatego wszędzie tam, gdzie kod odczytuje nazwy, których jego Recipe domyślnie nie dostarcza, deweloper narzuca sposób dostarczenia za pomocą bloku
inject:— zarówno dla zależności między komponentami (przezuses[].injectzfrom:odwołującym się doprovidescelu), jak i dla własnych wartości komponentu (przezinjectna poziomie komponentu z literałamivalue:lubfrom:odwołującym się do jego własnegoprovides). Dozwolone mechanizmy deklaruje się osobno dla każdej powierzchni i są to dwie odrębne deklaracje: własne wartości komponentu podlegają liście dozwolonychspec.inject(np.inject: ["env", "file"]), a krawędźuses:podlega liście dozwolonych gniazda, przez które jest połączona,spec.usesSchema.<socket>.inject. Narzucenie mechanizmu, którego nie wymienia właściwa lista dozwolonych, zatrzymuje kompilację na każdej z tych powierzchni. - Black-Box (spakowane obliczenia): komponent jest systemem zamkniętym (np. Redis, zarządzana API Gateway). Recipe zespołu Ops już dokładnie wie, jak system konsumuje swoje dane. Dlatego encja katalogowa Component pomija listę dozwolonych, co całkowicie zabrania narzucania, a nie tylko je zawęża — pominięcie
spec.injectzabrania samowstrzykiwania na poziomie komponentu, a gniazdo zadeklarowane bez listy dozwolonychinject:zabrania jakiegokolwiek blokuinject:na krawędzi połączonej przez to gniazdo. Deweloper po prostu wskazuje cel zależności przezuses, a platforma natywnie obsługuje wewnętrzne połączenia przezvaluesMappingencji Recipe.
Reguła deterministycznego adresowania (fizyka sieci wewnętrznej)
Potok .context.uses w Aggrega dynamicznie wstrzykuje ciągi docelowe do kontenerów w czasie kompilacji. Ponieważ rdzeń kompilatora Go jest całkowicie agnostyczny wobec fizycznej sieci, to, co liczy się jako prawidłowy ciąg adresu, opiera się całkowicie na umowie społecznej przestrzeganej przez zespół Platform Ops, a nie na funkcji kompilatora — kompilator bez interpretacji przekazuje do kontekstu szablonu w dół strumienia dowolny deterministyczny ciąg wskaźnika, który wygenerowała Recipe zespołu Ops.
Reguła: Recipe zespołu Ops musi eksportować deterministyczny, stabilny wskaźnik adresu. Dostawca nie oblicza adresów IP. Zamiast tego Recipe zespołu Ops dla celu powinna sformułować przewidywalny ciąg i udostępnić go przez swój kontrakt provides: (np. publikując provides.internal_host: "http://agent-b.namespace.svc.cluster.local" w Kubernetes lub ciąg interpolacji taki jak "${module.db.endpoint}" w Terraform, gdzie moduł deklaruje odpowiadające wartości output).
Poleganie na tym, że kompilator pobierze dynamiczne adresy IP po provisioningu, wprost narusza model wykonania AOT. Ponieważ kompilator ocenia topologię zanim chmura udostępni jakiekolwiek rzeczywiste zasoby obliczeniowe, nie może fizycznie pobrać danych, które jeszcze nie istnieją. Jeśli usługa wymaga losowego adresu IP generowanego dopiero po uruchomieniu zasobów obliczeniowych, kompilator nie może go fizycznie pobrać. Jedynym zadaniem kompilatora jest przekazanie deterministycznego ciągu wskaźnika dostarczonego przez Recipe zespołu Ops, dosłownie, do zmiennych środowiskowych wywołującego kontenera, pozostawiając ostateczne rozwiązanie DNS klastra lub aktywnemu menedżerowi stanu IaC.
Wymuszenie deterministycznego adresowania natywnie rozwiązuje problem zależności cyklicznych (np. agent A deleguje do agenta B, a agent B deleguje z powrotem do agenta A). Ponieważ stabilny URL lub wskaźnik IaC można obliczyć jako ciąg, zanim którykolwiek kontener faktycznie się uruchomi, kompilator bezpiecznie łączy oba agenty bez wprowadzania wyścigów czasowych.
(Uwaga: ta reguła dotyczy również ruchu przychodzącego z zewnątrz. Jeśli architektura udostępnia publiczną API Gateway i wymaga wstrzyknięcia jej URL z powrotem do wewnętrznego kontenera, kompilator Go nie może pobrać losowego URL wygenerowanego przez chmurę (np. xyz123.execute-api.aws.com), ponieważ nie istnieje on w czasie kompilacji. Zespół Ops musi napisać swoją Recipe tak, aby albo mapowała deterministyczną własną domenę (np. api.enterprise.com), albo eksportowała natywny ciąg interpolacji IaC, zapewniając kompilatorowi AOT znane odwołanie do bezpiecznego wstrzyknięcia).
Mechanika implementacji (katalog jako kontrakt API) Aby zaimplementować to bez ścisłego wiązania deweloperów z zespołem Ops, Aggrega używa katalogu platformy (domena 2) jako ścisłego kontraktu API, wykorzystując trzy odrębne warstwy walidacji:
- Schemat Feature dla poświadczeń (oznaczony
feature.aggrega.ai/kind: secret): waliduje WYŁĄCZNIE zapytanie do sejfu (path,key). Jest całkowicie agnostyczny wobec tego, jak kontener konsumuje dane. - Schemat
Component(lista dozwolonychspec.inject): wymusza regułę Black-Box/White-Box za pomocą polaspec.inject. Jeślispec.injectjest obecne (np.inject: ["env", "file"]), deweloper może używać samowstrzykiwania na poziomie komponentu z tymi mechanizmami dostarczania. Jeślispec.injectpominięto, kompilator strukturalnie zabrania samowstrzykiwania — komponenty Black-Box polegają w całości navaluesMappingencji Recipe w zakresie wewnętrznych połączeń. Kompilacja egzekwuje to podczas rozwiązywania encji Aggregate, odrzucając blokinject:komponentu i wskazując mechanizm, co jest odrębne od walidacji treści poszczególnych filarów wschema:. - Mapa
featuresSchema: zdefiniowana w katalogu Component, jawnie deklaruje sloty poświadczeń, których deweloper musi (lub może) używać. Każdy wpis określarequired(domyślniefalse), listę dozwolonychinject([]= blackbox,[env, file]= transparentny) orazdescription. Ponieważ te klucze są stabilne i gwarantowane kontraktem, inżynier Ops może bezpośrednio na nich polegać, aby niezawodnie narzucać deterministyczne cele w swoim szablonie Go (np.existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}"na celuhelm), jawnie eksportując sufiks nazwy przez.locals— zmienna lokalna nie może odczytać.context.rendered_name— dzięki czemu FeatureRecipe poświadczeń w dół strumienia łączy te same dwie części i spełnia wymaganie bez naruszania kolejności wykonania AOT. Pełny projektfeaturesSchemaopisano wentities/component.md.
Reguła ścisłego umiejscowienia: mechanizm inject: jest dostępny w trzech miejscach w encji Aggregate dewelopera:
- Self-inject na poziomie komponentu: jako bezpośredni element równorzędny
values:w instancji komponentu. Wstrzykuje własne wartości literalne komponentu lub jego własne kluczeprovidesdo potoku dostarczania. Dozwolone tylko wtedy, gdy katalog encji Component deklarujespec.injectz odpowiednimi mechanizmami. - Cross-inject na poziomie uses: wewnątrz jawnych definicji celów w bloku
uses:. Wstrzykuje kluczeprovidescelu zależności do potoku dostarczania. - Inject na poziomie Feature/Secret: jako element równorzędny z
values:przy dołączaniu funkcji i sekretów. Wstrzykuje do potoku dostarczania własne rozwiązane kluczeprovidesdołączenia — rozwiązane poświadczenie w przypadku sekretu lub wartości udostępniane przez funkcję.
Wszystkie trzy formy zasilają ten sam potok .context.inject. Recipe odczytuje jeden, ujednolicony potok niezależnie od tego, ile źródeł się do niego przyczyniło.
Schemat inject definiuje standardowe wartości wyliczeniowe (env, file, arg) na potrzeby narzędzi, ale pozostawia additionalProperties otwarte, więc można nazwać niestandardowy mechanizm (np. ssm_param dla AWS Systems Manager Parameter Store). Jedna nazwa jest zajęta: all to scalony widok wszystkich mechanizmów, które Recipe odczytuje w .context.inject.all, więc blok inject nazywający mechanizm all zatrzymuje kompilację na poziomie koperty dokumentu, informując o tym.
Składnia wpisu inject: w bloku inject każdy mechanizm dostarczania — env, file, arg lub niestandardowy — jest listą wpisów, a każde umiejscowienie używa tego samego kształtu wpisu. To, czym jest ciąg wpisu, określa słowo kluczowe, które wpis zawiera, a nie umiejscowienie, w którym się znajduje, więc wpis czyta się tak samo, gdziekolwiek się pojawi. Mechanizm zapisany jako mapa zamiast listy albo wpis zawierający oba słowa kluczowe zatrzymuje kompilację na etapie koperty dokumentu Aggregate, z podaniem ścieżki w Aggregate, w której kształt jest błędny.
Słowa kluczowe wpisu (from: i value:): każdy wpis używa słowa kluczowego in dla identyfikatora lokalnego — nazwy zmiennej środowiskowej, ścieżki pliku, flagi argumentu — oraz dokładnie jednego z from: (odwołanie do klucza provides) lub value: (ciąg literalny). from: jest rozwiązywane względem provides węzła wskazanego przez umiejscowienie: własnych kluczy komponentu w component.inject, kluczy celu w uses[target].inject i własnych kluczy załącznika w features[<name>].inject:
| Słowo kluczowe | Znaczenie | Dozwolone w component.inject | Dozwolone w uses[].inject | Dozwolone w features[<name>].inject |
|---|---|---|---|---|
from: | Rozwiązanie względem provides | ✅ Provides własnego węzła | ✅ Provides węzła docelowego | ✅ Własne provides dołączenia |
value: | Ciąg literalny (obsługuje szablony Go) | ✅ | ❌ (value: nie jest prawidłowe w uses[].inject; do self-inject należy użyć inject na poziomie komponentu) | ❌ (value: zatrzymuje kompilację w inject dołączenia; do self-inject należy użyć inject na poziomie komponentu) |
Przykłady:
# Component-level self-inject (White-Box custom code)components: my-worker: type: core/python-worker:1.0.0 values: app_token: "xyz" inject: env: - in: MY_TOKEN value: "xyz" # Literal value - in: LOG_LEVEL value: "debug" # Literal value - in: CALLBACK_HOST from: "host" # From own provides (already evaluated) - in: APP_VERSION value: '{{"{{"}} .values.app_token }}' # Go template expanding own values uses: databases: my_db: target: postgres-db inject: env: - in: DB_HOST from: "host" # Provides key from target - in: DB_PORT from: "port" # Provides key from target - in: DB_URL from: "dsn" # From target's providesSzablon w value: dla APP_VERSION zaczyna się od {{"{{"}}, a nie od {{: cały tekst Aggregate jest raz odczytywany jako szablon, na potrzeby interpolacji parametrów, zanim zostanie uruchomione rozwiązywanie self-inject, a .values w tym momencie nie istnieje, więc sekwencja ucieczki przywraca {{, aby rozwiązywanie self-inject mogło go obliczyć. Zobacz Tekst zawierający własne podwójne nawiasy klamrowe.
Uwaga specyficzna dla Provider (compose). Gdy krawędzie uses: są rozwiązywane między węzłami kierowanymi do compose, provider compose wyprowadza z tych krawędzi wpisy depends_on. Wpisy te zawsze używają semantyki service_started, niezależnie od bloku health: jakiegokolwiek celu; uzależnianie ich od stanu zdrowia celu nie jest zaimplementowane. Pełne reguły wnioskowania opisano w providers/compose.md.
Reguła kolizji kluczy inject: Żądanie przez dewelopera tego samego klucza dostarczania (np. tej samej nazwy zmiennej środowiskowej) z dwóch różnych źródeł jest błędem krytycznym, a nie scaleniem. Kompilator wykrywa kolizję i zatrzymuje kompilację:
| Źródło A | Źródło B | Wynik |
|---|---|---|
component.inject | uses[].inject | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania |
uses[target_A].inject | uses[target_B].inject | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania |
component.inject | features[<name>].inject | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania |
uses[].inject | features[<name>].inject | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania |
features[A].inject | features[B].inject | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania |
component.inject (ten sam klucz dwukrotnie) | — | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania |
injectMapping encji FeatureRecipe dla features[A] | injectMapping encji FeatureRecipe dla features[B] | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania w dwóch dołączeniach |
features[A].inject | injectMapping encji FeatureRecipe dla features[B] | ❌ zatrzymanie krytyczne — zduplikowany klucz dostarczania w dwóch dołączeniach |
component.inject lub uses[].inject | injectMapping encji FeatureRecipe | ✅ Dozwolone — przechwycenie z założenia: wartość mapowania zastępuje ten wpis |
Tabela traktuje każdą dołączoną encję Feature tak samo, niezależnie od miejsca dołączenia — w komponencie, na granicy podsystemu lub encji Release, przez rozwinięcie adnotacji albo w połączeniu. injectMapping encji FeatureRecipe jest renderowane po dostarczeniu wszystkich bloków inject:, więc zawsze jest późniejszym z dwóch roszczeń: może nadpisać to, co dostarczył komponent lub jedno z jego połączeń, oraz to, co dostarczył blok inject: jej własnego dołączenia, ale klucz już dostarczony przez inną dołączoną encję Feature zatrzymuje kompilację, z podaniem obu.
Encja Feature dołączona do granicy encji Release, której FeatureRecipe renderuje się raz dla granicy (executionScope: boundary), dociera do komponentów objętych granicą tą samą drogą: jej injectMapping uruchamia się raz dla każdego z nich, w kontekście danego komponentu, i podlega wierszom powyższej tabeli jak każde inne mapowanie. Most compose, który przepisuje zmienną hosta konsumenta tak, aby docierał do celu przez jego bramę, jest jednym z takich mapowań, więc inna dołączona encja Feature, która dostarczyła tę samą zmienną, zatrzymuje kompilację, z podaniem obu.
Aby uniknąć szablonowego kodu Go w encjach Recipes, kompilator udostępnia oba elementy:
.context.uses: wzbogacona mapa krawędzi topologicznych (dla złożonej logiki, odwołań do sekretów i śledzenia pochodzenia)..context.inject: wstępnie rozwiązany, spłaszczony słownik, w którym kompilator już rozwiązał wszystkie źródła inject (literały self-inject, odwołania provides w self-inject i międzykomponentowe odwołania provides) do końcowych wartości ciągów, a następnie zastosował przechwyceniainjectMappingencji FeatureRecipe.
Dwustanowy kontekst wstrzykiwania (bezpieczeństwo null a czystość intencji) Podczas generowania konfiguracji dla modyfikatorów (FeatureRecipe powiązanej z dowolnym dołączeniem, poświadczeniem lub innym) kompilator musi pogodzić bezpieczeństwo wskaźników null w szablonach Go, dynamiczny routing sieciowy oraz zachowanie grafu agnostycznego wobec możliwości. W tym celu kompilator udostępnia szablonowi dwustanowy kontekst:
.inject_raw(niezmienna intencja): reprezentuje własny blokinject:komponentu dokładnie w takiej postaci, w jakiej deweloper napisał go w Domenie 1. Jest niezmienna. Jeśli deweloper pominął blok, przyjmuje wartośćnull. Zespół Ops używa jej wyłącznie do sprawdzeń logicznych (np.{{ if not .inject_raw }}do zastosowania zachowań zastępczych). Ponieważ jest niezmienna, chroni szablony Ops przed fałszywymi alarmami, jeśli funkcje routingu przechwytują i modyfikują fizyczny potok dostarczania..context.inject(wstępnie wypełniony i przechwycony potok): równoległa, generowana przez kompilator struktura reprezentująca fizyczną rzeczywistość dostarczania. Zaczyna się jako wstępnie wypełniona mapa (np. mapującaAPI_HOSTna bazowy ciąg celu"backend-instance"). Co istotne, potok ten jest zaprojektowany tak, aby był przechwytywany i głęboko scalany przez encje Features (np. routing sieciowy) za pomocą blokuinjectMapping. Zanim bazowa Recipe zostanie wyrenderowana, potok zawiera w pełni sformatowane, fizycznie poprawne ciągi (np. poprawną pełną nazwę sieciową, taką jak"backend-instance.backend-zone.svc.cluster.local"). Jego zawartość jest podzielona naenv,file,arg(plus ewentualne niestandardowe mechanizmy dostarczania dozwolone przez listy dozwolonych inject encji Component), z wstępnie scalonym słownikiem.allłączącym wszystkie mechanizmy, co ułatwia serializację całego potoku..context.self_inject(Którą własną wartość dostarcza każda nazwa): Odczytywane z tego samego blokuinject:na poziomie komponentu co.inject_raw, w kształcie, w jakim.context.uses.<alias>.injectpodaje nazwy połączenia: dla każdego mechanizmu każda nazwa zapisana przez dewelopera jest mapowana na własny klucz komponentu, który dostarcza jej wpis —provides.<key>dla wpisufrom:,values.<key>dla szablonuvalue:, który odczytuje dokładnie jedną z własnych wartości komponentu i nic więcej, oraz pusty ciąg znaków dla wszystkiego innego (literału, dwóch wartości, odczytu czegokolwiek poza wartościami). Pozwala to encji Recipe uruchamiającej własny obraz dewelopera traktować własne nazwy zmiennych jako domyślne — dostarczając własną wartość pod jej domyślną nazwą tylko wtedy, gdy żaden wpis nie jest już mapowany navalues.<key>, dzięki czemu deweloper, który zmienia nazwę jednej wartości, zachowuje wszystkie pozostałe wartości domyślne. Jest to konwencja katalogu biblioteki standardowej, a nie reguła kompilatora; katalog przedsiębiorstwa może dostarczać własne wartości swoich komponentów w dowolny wybrany przez siebie sposób.
Zespół Ops używa struktury .context.inject wyłącznie do bezpiecznej serializacji (np. {{ toJson .context.inject.all }}) i generowania routingu, dzięki czemu fizyczna infrastruktura otrzymuje w pełni rozwiązane współrzędne, a pierwotna intencja dewelopera pozostaje całkowicie nienaruszona w .inject_raw.
Przykład YAML dewelopera (szczegółowa mapa):
uses: databases: my-postgres-cluster: target: db-main inject: ssm_param: # Agnostic injection paradigm (AWS Systems Manager) - in: MY_DB_HOST # Local identifier from: "host" # Target provides keyKompilator rozwiązuje to w czasie kompilacji (mapując na statyczne ciągi lub wewnętrzne nazwy DNS) i przekazuje oba obiekty do encji Recipe:
"context": { "uses": { ... raw graph ... }, "inject": { "all": { "MY_DB_HOST": "db-main.internal" }, "ssm_param": { "MY_DB_HOST": "db-main.internal" } }}Konfiguracja w zakresie połączenia (values i infra). Poza dostarczaniem kluczy provides celu przez inject krawędź może nieść własną konfigurację — ustawienia poszczególnych połączeń, które konsumująca encja Recipe odczytuje ze wzbogaconego potoku topologii:
.context.uses.<alias>.values— tworzone przez dewelopera, deklarowane w rozbudowanym wpisieusesencji Aggregate, walidowane względemvalueSchemagniazda..context.uses.<alias>.infra— tworzone przez operatora, deklarowane w encji Release, walidowane względeminfraSchemagniazda.
Gniazdo (usesSchema[<socket>]) to kontrakt Architekta określający, jakie połączenia są możliwe i jaką konfigurację mogą nieść; values i infra dzielą tę konfigurację według domeny autorskiej, odzwierciedlając podział values/infra w komponentach. Krawędź ma więc dwóch autorów: deweloper łączy topologię i dostraja ją za pomocą values w encji Aggregate, a operator ustawia infra poszczególnych połączeń w encji Release w ramach gniazd zadeklarowanych przez Architekta. Encja Release może też podłączyć krawędź w zadeklarowanym, lecz niepowiązanym gnieździe do istniejącego komponentu; nie może natomiast zmienić celu krawędzi zadeklarowanej przez dewelopera — zob. entities/release.md §„Per-edge connection configuration”.
Konfiguracja krawędzi ma zakres konsumenta: pojawia się wyłącznie w kontekście węzła, który utworzył krawędź (źródła połączenia), nigdy w kontekście celu. Wyrenderowany wynik samego celu jest zatem niezmienny względem konsumentów, którzy się z nim łączą. Encja Feature dołączona do celu to jedyne miejsce, w którym połączenia są widoczne: jej FeatureRecipe odczytuje, które komponenty używają celu, w .context.used_by — tożsamość każdego z nich, gniazdo, opublikowane provides, przestrzeń nazw i granicę, w której jest umieszczony, a w przypadku encji FeatureRecipe, która deklaruje ich odczyt, także fakty renderowania zgłoszone przez jego dostawców — nigdy jednak własnych values ani infra połączenia. Encja Feature dołączona do konsumenta odczytuje w ten sam sposób, co zgłosiły rendery każdego z jego celów, we wpisie danego połączenia w .context.uses.<alias>.render_facts, o ile jej FeatureRecipe deklaruje ich odczyt.
Załączniki połączenia (features). Połączenie może też nieść własne załączniki — na przykład poświadczenie, które konsument przedstawia komponentowi osiąganemu przez to połączenie — w features: swojego wpisu, z kluczem będącym slotem, który gniazdo deklaruje w swoim featuresSchema. Dzieli je tych samych dwóch autorów: deweloper dołącza je we wpisie połączenia encji Aggregate za pomocą type i values, a operator wymiaruje ten załącznik za pomocą infra lub dołącza własny za pomocą type i infra we wpisie encji Release. Załącznik połączenia nie ma własnego bloku inject, dlatego nie występuje w powyższej regule umiejscowienia: nie jest jednym z miejsc, w których deweloper dyktuje dostarczanie.
Każdy z nich staje się załącznikiem komponentu konsumującego o nazwie <alias>.<slot>, ma więc zakres konsumenta dokładnie tak jak konfiguracja krawędzi: jego FeatureRecipe renderuje się po stronie konsumenta, a wynik celu się z jego powodu nie zmienia. Nie trafia do .features konsumującej encji Recipe, które zawiera tylko załączniki zadeklarowane we własnym bloku komponentu; encja Recipe odczytuje go zamiast tego pod jego połączeniem, w .context.uses.<alias>.features.<slot>. Połączenie utworzone przez załącznik Feature nie niesie żadnych załączników. Zob. entities/aggregate.md §„A connection’s own attachments” oraz entities/component.md §„Topology Sockets”.
A. Zmienne środowiskowe (env) i dynamiczne rozwiązywanie miejsca docelowego
Standardowy mechanizm dostarczania dla nowoczesnych aplikacji cloud-native. Dla jawnych krawędzi topologicznych (np. agenta komunikującego się z bazą danych) Aggrega używa .context.uses do wstrzyknięcia mapowania zmiennych środowiskowych.
- Przypadek użycia: otrzymywanie deterministycznych wewnętrznych nazw DNS, ciągów interpolacji Infrastructure-as-Code (np.
${module.db.endpoint}) lub statycznych wskaźników Vault. Kompilator łączy te statyczne odwołania AOT, aby infrastruktura uruchomieniowa lub kontroler GitOps mogły rozwiązać bieżące wartości.
B. Montowanie plików (file)
Wiele korporacyjnych frameworków AI oczekuje, że ustrukturyzowany plik config.json lub certyfikat .pem będzie istniał w określonej ścieżce na dysku, zamiast polegać na zmiennych środowiskowych.
-
Przypadek użycia: wstrzykiwanie złożonych konfiguracji JSON lub obsługa starszych SDK, które czytają z dysku.
-
Intencja deweloperska:
features:openai_key:type: core/aws-secrets-managervalues:path: /prod/ai/openaikey: "api_token"inject:file:- in: "/etc/secrets/openai.json" # Local pathfrom: "api_token" # The attachment's provides key -
Rzeczywistość operacyjna: operacyjna encja Recipe dynamicznie generuje obiekty Kubernetes
Volume,VolumeMountiExternalSecretpotrzebne do bezpiecznego pobrania danych z sejfu i zamontowania ich w/etc/secrets/openai.json.
C. Argumenty wiersza poleceń (arg)
Prekompilowane pliki binarne (np. węzły robocze w Rust lub Go) często całkowicie pomijają zmienne środowiskowe i oczekują, że wartości zostaną przekazane jako flagi uruchomieniowe w ich poleceniu wykonania.
-
Przypadek użycia: dołączanie fizycznych realiów do polecenia startowego kontenera.
-
Intencja deweloperska:
features:public-ingress:type: core/external-ingressinject:arg:- in: "--callback-url=" # Local flagfrom: "hostname" # The attachment's provides key -
Rzeczywistość operacyjna: nazwa hosta to nazwa, jaką środowisko nadaje komponentowi, więc operator zapisuje ją,
api.enterprise.com, winfratego załącznika we wpisie encji Release dla komponentu. Plugin Wasm encji Feature otrzymuje rozwiązany publiczny URL przez kontrakt wstrzykiwania i emituje JSONPatch, który dynamicznie dołącza tablicę Kubernetesargs:["/app/binary", "--callback-url=https://api.enterprise.com"], całkowicie pomijając bazową encję Recipe encji Component.