Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Architektura encji Provider

Provider renderuje rodzaje wejść encji Recipe do natywnych dla providera plików manifestów. Gdy encja Recipe deklaruje capability: helm, capability: compose lub dowolną inną nazwę providera, kompilator przekazuje renderowanie do providera obsługującego tę nazwę. Ten rozdział opisuje, jak provider jest realizowany jako renderujący encję Provider Plugin, jak działa przekazywanie oraz kontrakt gniazda pluginów, który wiąże kompilator z każdym providerem.

Czego ten rozdział nie obejmuje: modelu kompozycji trzech rodzajów wejść (source: + valuesMapping:, workload:, artifacts: — każdy przyjmuje treść osadzoną lub $import:), którego encja Recipe używa do wytworzenia swojego wyniku. Ten model jest przekrojowy dla wszystkich providerów i znajduje się w ../../architecture/16-recipe-input-composition.md, wraz z macierzą możliwości providerów (Provider Capability Matrix), która określa, jaki rodzaj wejścia obsługuje każdy provider.

Plugin renderujący providera

Renderowanie w ramach Provider obsługuje encja Plugin z pluginType: provider. Plugin renderujący dla providera:

  • obsługuje jedną lub więcej nazw providerów — zadeklarowanych w spec.provider.capabilities. Nazwa providera wskazana przez encję Recipe (spec.capability: helm) wiąże się z tym Pluginem renderującym providera, którego lista spec.provider.capabilities zawiera tę nazwę. Gdy ten sam cel obsługuje więcej niż jeden Plugin, przestrzeń robocza wybiera między nimi za pomocą powiązania providera w .aggrega-config.yaml, rozwiązywanego podczas aggrega pull i zapisywanego w pliku blokady; jeśli nie ma powiązania i jest dokładnie jeden kandydat, używany jest ten kandydat, a jeśli nie ma powiązania i jest więcej niż jeden kandydat, kompilacja zatrzymuje się z wyraźnym błędem, podając nazwy pluginów-kandydatów.
  • przechowuje metadane gniazda providera w tym samym bloku — spec.provider zawiera powyższą listę możliwości wraz z pozostałymi deklaracjami providera. spec.provider.workloadSchema to deklaracja JSON Schema 2020-12 dokumentująca, jak należący do platformy rodzaj Workload jest tłumaczony na natywne wyjście tego providera; katalog biblioteki standardowej deklaruje ją w providerach, które syntetyzują, jako udokumentowany kontrakt tłumaczenia. spec.provider.wellKnownAnnotations wylicza adnotacje granic aggrega.ai/, które odczytuje provider. Obsługa wejścia syntetyzowanego (workload:) jest właściwością providera, egzekwowaną w czasie renderowania — nie zależy od obecności workloadSchema.

Pełny opis pól encji Plugin, w tym bloku spec.provider, znajduje się w ../entities/plugin.md.

Rozdział renderowania według dostawcy

Każda encja Recipe deklaruje dokładnie jedno capability: na początku swojego spec. Kompilator odczytuje to pole i przekazuje renderowanie dostawcy, który obsługuje daną nazwę. Encja Recipe nie może jednocześnie kierować do wielu dostawców. Kompozycja wielu dostawców odbywa się na poziomie encji Release: granica może zawierać komponenty różnych dostawców, a elementy wnoszone przez każdego dostawcę w obliczonej ścieżce składania granicy są składane niezależnie — jedno złożenie na każdą krotkę (path, provider).

Ścieżka rozdziału dla pojedynczego węzła:

  1. Kompilator rozwiązuje URI encji Recipe dla tego węzła poprzez trzypoziomowe wyszukiwanie w encji Manifest w sekcji mapowania dostawcy docelowego. To właśnie grupowanie według osi dostawcy w encji Manifest sprawia, że „ta sama encja Component, różne encje Recipes dla różnych dostawców” jest naturalnym wzorcem.
  2. Pole spec.capability rozwiązanej encji Recipe określa nazwę dostawcy, do którego następuje rozdział.
  3. Kompilator wiąże dostawcę dla tej nazwy: rozwiązuje encję Plugin renderującą dostawcę, której lista spec.provider.capabilities zawiera tę nazwę, i renderuje za pośrednictwem gościa tej encji Plugin. Renderowanie odbywa się wyłącznie w Wasm — nie istnieje renderer po stronie hosta, do którego można by się wycofać, więc nazwa dostawcy, która nie rozwiązuje się do żadnej obsługującej ją encji Plugin, głośno zatrzymuje kompilację na etapie routingu.
  4. Dostawca jest wywoływany z kontekstem renderowania danego węzła (wartości filarów, projekcje .context.*, rodzaje wejść encji Recipe).
  5. Dostawca zwraca wyrenderowane dane wyjściowe. Kompilator kieruje wyrenderowane pliki do asemblera dla danej pary (path, provider), kluczowanego obliczonym directory: granicy połączonym z subDirectory: danego komponentu. Dwie granice, które w ramach tego samego dostawcy dają tę samą ścieżkę, współdzielą asembler — kanonicznym wzorcem jest granica nadrzędna z dwiema granicami podrzędnymi z directory: "{{ .parent_boundary.directory }}", które łączą się w jedno scalone złożenie.

Kształt rozdziału według osi dostawcy w encji Manifest opisano w ../entities/manifest.md, a deklarację jednego dostawcy po stronie encji Recipe — w ../entities/recipe.md. Model składania dla każdej pary (path, provider) oraz lista dozwolonych zmiennych szablonów ścieżek, która kontroluje obliczane ścieżki, są udokumentowane w ../path-template-variables.md.

Kontrakt wtyczek Wasm

Renderowanie Provider odbywa się w piaskownicy WebAssembly. Kompilator Go jest hostem; Plugin renderujący providera (provider-rendering) jest gościem. Dla każdego węzła kompilator przekazuje pluginowi kontekst renderowania węzła, a plugin zwraca wyrenderowane przez siebie pliki. Ten kontrakt jest jednolity dla wszystkich providerów:

  • Kanoniczne kodowanie binarne w obu kierunkach. Kompilator koduje kontekst renderowania — wartości i załączniki węzła, sparsowany .workload, obliczone wpisy artefaktów, listę samych nazw rozwiązanego .source oraz metadane granicy — jako kanoniczny CBOR (RFC 8949 §4.2.1) i przekazuje go wtyczce. Wtyczka odpowiada w tym samym kodowaniu listą wyrenderowanych plików — każdy to ścieżka względna wobec katalogu głównego wyjścia węzła i dokładne bajty do zapisania pod nią, opcjonalnie z formatem pliku — wraz z ewentualną diagnostyką. Każdy eksport gniazda, od renderowania jednego węzła po składanie granicy i łączenie powiązania między granicami, przenosi to kodowanie w obu kierunkach, a zestaw narzędzi do tworzenia wtyczek w każdym języku dekoduje je i koduje za wtyczkę. Odpowiedź, która nie ma kształtu wyjścia danego eksportu w tym kodowaniu, zatrzymuje kompilację. Kontrakt wtyczek opisuje ładunek każdego eksportu.
  • Brak dostępu do systemu plików. Plugins nie mogą odczytywać dowolnych plików z systemu plików hosta. Źródło wskazane w encji Recipe — chart w rejestrze, moduł w repozytorium — jest rozwiązywane przez kompilator przed uruchomieniem pluginu; plugin otrzymuje listę samych nazw jego plików i prosi kompilator o wybrane pliki za pośrednictwem funkcji hosta, która odpowiada wyłącznie w odniesieniu do plików należących do źródła danego węzła.
  • Brak dostępu do sieci. Plugins są deterministyczne i hermetyczne i nie otwierają żadnych własnych połączeń. Zewnętrzne dane wejściowe potrzebne pluginowi podczas renderowania — zdalny schemat, do którego odwołują się wartości chartu — są pobierane przez funkcję hosta kompilatora obsługującą zewnętrzne dane wejściowe, która odpowiada treścią przypiętą w przestrzeni roboczej dla danego odwołania.
  • Deterministyczne wyjście. Przy identycznych danych wejściowych i tej samej wersji wtyczki wtyczka musi wygenerować bajtowo identyczne wyjście. To ten kontrakt sprawia, że gwarancja bajtowo identycznego wyjścia kompilatora obowiązuje od początku do końca, także w warstwie wtyczek. Kompilacja uruchomiona z --verify-determinism renderuje każdy węzeł dwukrotnie i zatrzymuje się, gdy dwa renderowania węzła się różnią.

Architektura gniazd wtyczek na szerszym poziomie rozszerzalności, w tym inne gniazda Wasm w potoku kompilacji (role transformacji i werdyktu gniazda zarządzania), jest opisana w ../../architecture/14-extensibility.md.

Dostawcy z biblioteki standardowej Aggrega

Dostawcy helm, helm-chart, compose, terraform i cloudformation tworzą razem zestaw dostawców biblioteki standardowej. Obejmują one typowe cele wdrożeniowe, nie wymagając od zespołów w przedsiębiorstwach tworzenia własnych dostawców.

helm obsługuje wszystkie trzy rodzaje wejścia: sourced (nadrzędny chart Helm pobierany przez Helm SDK, w którym wynik valuesMapping encji Recipe służy jako nadpisania wartości chartu), synthesized (płaski YAML Kubernetes — obiekt kontrolera wybrany przez form encji Workload (Deployment, StatefulSet, DaemonSet, Job lub CronJob) wraz z obiektami Service i PVC — emitowany z przetworzonej encji Workload) oraz artifacts (samodzielne pliki YAML obok wyniku chartu). To, które z tych trzech rodzajów przyjmuje, przedstawia tabela Provider Capability Matrix w ../../architecture/16-recipe-input-composition.md.

helm-chart obsługuje tryb sourced (kompozycja chartu parasolowego: jeden chart na granicę, jeden sub-chart na komponent) oraz towarzyszące mu artifacts:, w obu formach tworzenia. Wpis artifacts: wczytany przez $import: jest najpierw przetwarzany przez Aggrega jako szablon Go, a następnie wstrzykiwany do katalogu templates/ chartu przed renderowaniem; wpis artifacts: z treścią inline jest obliczany w ten sam sposób i umieszczany w katalogu głównym sub-chartu, bez dołączania informacji o pochodzeniu, gdzie odczytują go własne szablony chartu za pomocą .Files.Get / .Files.Glob z Helm. Samodzielna encja Recipe zawierająca tylko artefakty nie należy do deklarowanych przez niego rodzajów, podobnie jak rodzaj synthesized: chart parasolowy orkiestruje sub-charty, natomiast rodzaj Workload jest pojęciem liściowym, które należy do wnętrza każdego sub-chartu (domena dostawcy helm).

compose obsługuje sourced (wczytuje plik compose i głęboko scala nakładkę valuesMapping), synthesized (emituje services: + volumes: + networks: compose z przeanalizowanej encji Workload dla form stateless i stateful, z ograniczoną obsługą woluminów dla persistentTemplate — PVC poszczególnych replik są sprowadzane do jednego współdzielonego nazwanego woluminu z ostrzeżeniem; formy daemon, scheduled i task nie mają odwzorowania w compose i jawnie przerywają kompilację) oraz artifacts (fragmenty compose, których klucze najwyższego poziomu services: / networks: / volumes: / configs: są scalane z łącznym plikiem docker-compose.yaml danej granicy). Artefakty mogą towarzyszyć każdemu z dwóch pozostałych rodzajów, a samodzielna encja Recipe zawierająca tylko artefakty — artifacts: bez source: i bez workload: — również jest rodzajem deklarowanym przez tego dostawcę: jej fragmenty są scalane według tych samych reguł, więc węzeł wnosi dokładnie to, co deklaruje, i nie potrzebuje encji Workload zastępującej moc obliczeniową, której nie ma.

terraform obsługuje sourced (dołącza moduł Terraform dosłownie i przekazuje wynik valuesMapping jako argumenty bloku module danego komponentu w konfiguracji głównej granicy) oraz artifacts (emituje utworzoną treść HCL lub .tf.json w postaci, jaką daje obliczenie jej szablonu, bez przepisywania jej). Nie oferuje rodzaju wejścia synthesized — nie istnieje wierne odwzorowanie rodzaju Workload platformy na dowolne zasoby Terraform. Dostawca emituje konfigurację i nigdy nie uruchamia Terraform; wartości zależne od środowiska uruchomieniowego pozostają ciągami interpolacji ${ ... }, które środowisko uruchomieniowe Terraform rozwiązuje w czasie apply.

cloudformation renderuje granicę do jednego szablonu stosu AWS CloudFormation, składając fragmenty zasobów tworzone przez jej komponenty w jeden szablon w czystym JSON, udostępniając provides każdego komponentu jako Outputs stosu oraz łącząc krawędzie uses jako Fn::GetAtt w obrębie stosu i jako Fn::ImportValue / Fn::GetStackOutput między stosami. Obsługuje wejście sourced i artifacts oraz emituje konfigurację, nigdy nie uruchamiając CloudFormation; wartości dostępne tylko w czasie działania pozostają funkcjami wewnętrznymi CloudFormation.

Indeks dokumentacji dostawców kieruje do strony referencyjnej każdego dostawcy; to, jakie rodzaje wejścia przyjmuje każdy z nich, określa macierz możliwości w ../../architecture/16-recipe-input-composition.md.

Niestandardowi dostawcy

Zespoły korporacyjne tworzące własnych dostawców postępują według tego samego wzorca co biblioteka standardowa: należy utworzyć encję Plugin renderującą dla dostawcy (pluginType: provider), która deklaruje nazwy obsługiwanych dostawców w spec.provider.capabilities wraz z pozostałymi metadanymi spec.provider, a następnie dostarczyć artefakt Wasm implementujący opisany wyżej kontrakt renderowania. Kompilator traktuje niestandardowych dostawców identycznie jak dostawców z biblioteki standardowej; dyspozycja dla poszczególnych dostawców działa na podstawie nazwy dostawcy zadeklarowanej przez encję Recipe.

Tworzenie dostawcy jest udokumentowane, a nie odłożone na później. Tworzenie dostawcy prowadzi od początku do końca przez budowę działającego gościa dostawcy — samoopis describe(), kompilację, encję Plugin, podłączenie oraz renderowanie, którego wynik można przeczytać. Przewodnik dewelopera pluginów Wasm jest dokumentacją referencyjną encji i cyklu publikacji, a kontrakt pluginu opisuje kształty ładunku i wyniku każdego gniazda. Gości tworzy się w Go, Rust lub TypeScript z użyciem zestawu do tworzenia pluginów.